9787c8a8 |
1 | .\" -*-nroff-*- |
2 | .de VS |
3 | .sp 1 |
4 | .RS |
5 | .nf |
6 | .ft B |
7 | .. |
8 | .de VE |
9 | .ft R |
10 | .fi |
11 | .RE |
12 | .sp 1 |
13 | .. |
fbf20b5b |
14 | .TH pool 3 "7 July 2000" "Straylight/Edgeware" "mLib utilities library" |
9787c8a8 |
15 | .SH "NAME" |
16 | pool \- resource pool management |
17 | .\" @pool_alloc |
18 | .\" @pool_strdup |
c5775f49 |
19 | .\" @pool_init |
9787c8a8 |
20 | .\" @pool_create |
21 | .\" @pool_destroy |
22 | .\" @pool_sub |
23 | .\" @pool_add |
24 | .\" @POOL_ADD |
25 | .\" @pool_fopen |
26 | .\" @pool_fclose |
27 | .\" @pool_subarena |
28 | .SH "SYNOPSIS" |
29 | .nf |
30 | .B "#include <mLib/pool.h>" |
31 | |
c5775f49 |
32 | .BI "void pool_init(pool *" p ", arena *" a ); |
9787c8a8 |
33 | .BI "pool *pool_create(arena *" a ); |
34 | .BI "pool *pool_sub(pool *" p ); |
35 | .BI "void pool_destroy(pool *" p ); |
36 | .BI "void pool_add(pool *" p ", pool_resource *" r , |
37 | .BI " void (*" dfn ")(pool_resource *" r )); |
38 | .BI "void *pool_alloc(pool *" p ", size_t " sz ); |
39 | .BI "char *pool_strdup(pool *" p ", const char *" s ); |
40 | .BI "pool_file *pool_fopen(pool *" p ", const char *" file ", const char *" how ); |
41 | .BI "int pool_fclose(pool_file *" pf ); |
42 | .BI "subarena *pool_subarena(pool *" p ); |
43 | |
44 | .BI "void POOL_ADD(pool *" p ", pool_resource *" r , |
45 | .BI " void (*" dfn ")(pool_resource *" r )); |
46 | .fi |
47 | .SH "DESCRIPTION" |
48 | .SS "Overview" |
49 | A |
50 | .I "resource pool" |
51 | is a collection of resources (e.g., memory, files) which may be disposed |
52 | of simultaneously. |
53 | .PP |
54 | A pool may be a |
55 | .IR "root pool" , |
56 | in which case it stands on its own, or it may be a |
d4efbcd9 |
57 | .IR "subpool" |
9787c8a8 |
58 | of another pool (which may in turn either be a root pool or a subpool of |
59 | another). |
60 | .PP |
61 | Pools manage memory efficiently. Memory is allocated in large chunks |
62 | from an |
63 | .BR arena (3), |
64 | and given out as necessary to callers. There is no way of freeing |
65 | memory dynamically; instead, the memory allocated by a pool is freed |
66 | when the pool is destroyed. While allocation is rapid, there is waste |
67 | because the allocator has to ensure that blocks are properly aligned. |
68 | Since pools offer an arena interface, it is possible to build a |
69 | .BR subarena (3) |
70 | over them. This also enables memory in the subarena to be reclaimed |
71 | when the pool is destroyed. |
72 | .PP |
73 | Other resources (e.g., file handles) may be added to the pool. The pool |
74 | will automatically release any resources it has when it's destroyed. |
75 | Attaching resources to an appropriate pool can therefore be a useful way |
76 | of avoiding memory leaks. |
77 | .SS "Creating and destroying pools" |
78 | A new root pool is created using |
79 | .BR pool_create , |
80 | passing it an arena from which it can allocate large memory blocks. |
c5775f49 |
81 | Alternatively, you can allocate a |
82 | .B pool |
83 | structure from somewhere and initialize it by passing its address and an |
84 | arena to |
85 | .BR pool_init . |
9787c8a8 |
86 | .PP |
87 | A subpool is created by calling |
88 | .BR pool_sub , |
89 | naming the parent pool. |
90 | .PP |
91 | Pools are destroyed by passing them to |
92 | .BR pool_destroy . |
c5775f49 |
93 | Pools created by |
94 | .B pool_create |
95 | are completely destroyed, since the memory containing the pool structure |
96 | is allocated from the pool itself. Subpools and pools allocated by the |
97 | caller and initialized by |
98 | .BR pool_init , |
99 | on the other hand, are |
100 | allocated from a parent pool, and may be reused after being `destroyed'. |
9787c8a8 |
101 | .SS "Memory allocation" |
102 | Memory is allocated from a pool by calling |
103 | .BR pool_alloc , |
104 | passing it the pool and the size of memory requested. There is an |
105 | interface for copying strings, |
106 | .BR pool_strdup , |
107 | since this is a common operation. Note that there is no |
108 | .BR pool_free : |
109 | if this is important, either use the pool's arena |
110 | .B p->pa |
111 | directly or create a subpool. |
112 | .PP |
113 | A pool provides an |
114 | .BR arena (3) |
115 | interface, |
116 | .BR p->a , |
117 | which can be passed to other components to cause them to use the pool |
118 | for memory allocation. |
119 | .SS "Other resources" |
120 | Pool resources have a header of type |
121 | .B pool_resource |
122 | with the structure: |
123 | .VS |
124 | typedef struct pool_resource { |
125 | struct pool_resource *next; |
126 | void (*destroy)(struct pool_resource */*r*/); |
127 | } pool_resource; |
128 | .VE |
129 | Resources are added to the pool by passing a pointer to the pool, the |
130 | resource block and a destruction function to |
131 | .BR pool_add . |
132 | .PP |
133 | If your resource is freed before the pool is destroyed, manually zero |
134 | the |
135 | .B destroy |
136 | field in the resource header to let the pool manager know not to free |
137 | the resource again. |
138 | .PP |
139 | It's usual to allocate the resource structures from the pool's arena so |
140 | that they're automatically freed when the pool is destroyed. |
141 | .PP |
142 | A |
143 | .BR subarena (3) |
144 | may be created for a particular pool by calling |
145 | .BR pool_subarena . |
146 | The subarena and its contents will be freed automatically when the pool |
147 | is destroyed. |
148 | .PP |
149 | Files may be opened and registered with a pool by |
150 | .BR pool_fopen : |
151 | the |
152 | .I pool |
153 | argument specifies which pool, and the |
154 | .I file |
155 | and |
156 | .I how |
157 | arguments are passed to the standard |
158 | .BR fopen (3) |
159 | function. The return value is a pointer to a |
160 | .B pool_file |
161 | structure, containing a member |
162 | .B fp |
163 | which is the actual file handle. Don't call |
164 | .B fclose |
165 | directly on the file handle: instead pass the whole structure to |
166 | .B pool_fclose |
167 | which will ensure that it doesn't get closed twice by accident. It's |
168 | advisable to close files by hand, to prevent the process from running |
169 | out; it's just not a disaster if you forget by accident. |
170 | .SH "SEE ALSO" |
171 | .BR alloc (3), |
172 | .BR arena (3), |
173 | .BR mLib (3), |
174 | .BR subarena (3). |
175 | .SH AUTHOR |
9b5ac6ff |
176 | Mark Wooding, <mdw@distorted.org.uk> |