Commit | Line | Data |
---|---|---|
7efdcf32 S |
1 | .ds d \-\^\- |
2 | .ds o \fR[\fP | |
3 | .ds c \fR]\fP | |
4 | .ds | \fR|\fP | |
5 | .de D | |
6 | \\.B \*d\\$1 | |
7 | .. | |
8 | .de DI | |
9 | \\.BI \*d\\$1 \\$2 | |
10 | .. | |
11 | .de DR | |
12 | \\.BR \*d\\$1 \\$2 | |
13 | .. | |
14 | .de Di | |
15 | \\.BI \*d\\$1 " \\$2" | |
16 | .. | |
17 | .de Db | |
18 | \\.B \*d\\$1 " \\$2" | |
19 | .. | |
20 | .de Df | |
21 | \\.B \*d\*ono\*c\\$1 | |
22 | .. | |
23 | .de See | |
24 | See \fB\\$1\fP for details. | |
25 | .. | |
26 | .de SeeIn | |
27 | See \fB\\$1\fP in \fB\\$2\fP for details. | |
28 | .. | |
29 | .TH POOL_ALLOC 3 | |
30 | .SH NAME | |
676e6041 | 31 | pool_alloc, pool_free, pool_free_old, pool_talloc, pool_tfree, pool_create, pool_destroy, pool_boundary |
7efdcf32 S |
32 | \- Allocate and free memory in managed allocation pools. |
33 | .SH SYNOPSIS | |
34 | .B #include "pool_alloc.h" | |
35 | ||
36 | \fBstruct alloc_pool *pool_create(size_t \fIsize\fB, size_t \fIquantum\fB, void (*\fIbomb\fB)(char *), int \fIflags\fB); | |
37 | ||
38 | \fBvoid pool_destroy(struct alloc_pool *\fIpool\fB); | |
39 | ||
40 | \fBvoid *pool_alloc(struct alloc_pool *\fIpool\fB, size_t \fIsize\fB, char *\fImsg\fB); | |
41 | ||
33766a8d | 42 | \fBvoid pool_free(struct alloc_pool *\fIpool\fB, size_t \fIsize\fB, void *\fIaddr\fB); |
7efdcf32 | 43 | |
676e6041 WD |
44 | \fBvoid pool_free_old(struct alloc_pool *\fIpool\fB, void *\fIaddr\fB); |
45 | ||
7efdcf32 S |
46 | \fBvoid *pool_talloc(struct alloc_pool *\fIpool\fB, \fItype\fB), int \fIcount\fB, char *\fImsg\fB); |
47 | ||
48 | \fBvoid pool_tfree(struct alloc_pool *\fIpool\fB, \fItype\fB, int \fIcount\fB, void *\fIaddr\fB); | |
676e6041 WD |
49 | |
50 | \fBvoid pool_boundary(struct alloc_pool *\fIpool\fB, sise_t \fIsize\fB); | |
7efdcf32 S |
51 | .SH DESCRIPTION |
52 | .P | |
53 | The pool allocation routines use | |
54 | .B malloc() | |
55 | for underlying memory management. | |
33766a8d WD |
56 | What allocation pools do is cause memory within a given pool |
57 | to be allocated in large contiguous blocks | |
58 | (called extents) that will be reusable when freed. Unlike | |
59 | .BR malloc() , | |
7efdcf32 | 60 | the allocations are not managed individually. |
33766a8d | 61 | Instead, each extent tracks the total free memory within the |
7efdcf32 S |
62 | extent. Each extent can either be used to allocate memory |
63 | or to manage the freeing of memory within that extent. | |
64 | When an extent has less free memory than a given | |
676e6041 WD |
65 | allocation request, the current extent ceases to be used |
66 | for allocation. See also the | |
67 | .B pool_boundary() | |
68 | function. | |
7efdcf32 S |
69 | .P |
70 | This form of memory management is suited to large numbers of small | |
71 | related allocations that are held for a while | |
72 | and then freed as a group. | |
73 | Because the | |
33766a8d | 74 | underlying allocations are done in large contiguous extents, |
676e6041 | 75 | when an extent is freed, it can release a large enough |
33766a8d WD |
76 | contiguous block of memory to allow the memory to be returned |
77 | to the OS for use by whatever program needs it. | |
78 | You can allocate from one or more memory pools and/or | |
7efdcf32 | 79 | .B malloc() |
33766a8d | 80 | all at the same time without interfering with how pools work. |
7efdcf32 S |
81 | .P |
82 | .B pool_create() | |
83 | Creates an allocation pool for subsequent calls to the pool | |
84 | allocation functions. | |
85 | When an extent is created for allocations it will be | |
86 | .I size | |
87 | bytes. | |
88 | Allocations from the pool have their sizes rounded up to a | |
89 | multiple of | |
90 | .I quantum | |
91 | bytes in length. | |
92 | Specifying | |
93 | .B 0 | |
94 | for | |
95 | .I quantum | |
33766a8d | 96 | will produce a quantum that should meet maximal alignment |
7efdcf32 | 97 | on most platforms. |
33766a8d | 98 | If |
7efdcf32 | 99 | .B POOL_QALIGN |
33766a8d WD |
100 | is set in the |
101 | .IR flags , | |
102 | allocations will be aligned to addresses that are a | |
7efdcf32 S |
103 | multiple of |
104 | .IR quantum . | |
33766a8d | 105 | If |
7efdcf32 | 106 | .B POOL_CLEAR |
33766a8d WD |
107 | is set in the |
108 | .IR flags , | |
109 | all allocations from the pool will be initialized to zeros. | |
110 | You may specify a | |
111 | .B NULL | |
112 | for the | |
113 | .I bomb | |
114 | function pointer if you don't wish to use it. (See the | |
115 | .B pool_alloc() | |
116 | function for how it is used.) | |
7efdcf32 S |
117 | .P |
118 | .B pool_destroy() | |
33766a8d WD |
119 | destroys an allocation |
120 | .I pool | |
121 | and frees all its associated memory. | |
7efdcf32 S |
122 | .P |
123 | .B pool_alloc() | |
124 | allocates | |
125 | .I size | |
126 | bytes from the specified | |
127 | .IR pool . | |
128 | If | |
129 | .I size | |
130 | is | |
33766a8d | 131 | .BR 0 , |
7efdcf32 | 132 | .I quantum |
33766a8d WD |
133 | bytes will be allocated. |
134 | If the pool has been created with | |
135 | .BR POOL_QALIGN , | |
136 | every chunk of memory that is returned will be suitably aligned. | |
137 | You can use this with the default | |
138 | .I quantum | |
139 | size to ensure that all memory can store a variable of any type. | |
140 | If the requested memory cannot be allocated, the | |
7efdcf32 | 141 | .I bomb() |
33766a8d | 142 | function will be called with |
7efdcf32 | 143 | .I msg |
33766a8d WD |
144 | as its sole argument (if the function was defined at the time |
145 | the pool was created), and then a | |
7efdcf32 | 146 | .B NULL |
33766a8d | 147 | address is returned (assuming that the bomb function didn't exit). |
7efdcf32 S |
148 | .P |
149 | .B pool_free() | |
150 | frees | |
151 | .I size | |
33766a8d | 152 | bytes pointed to by an |
7efdcf32 | 153 | .I addr |
33766a8d | 154 | that was previously allocated in the specified |
7efdcf32 | 155 | .IR pool . |
7efdcf32 S |
156 | If |
157 | .I size | |
158 | is | |
33766a8d | 159 | .BR 0 , |
7efdcf32 S |
160 | .I quantum |
161 | bytes will be freed. | |
33766a8d WD |
162 | The memory freed within an extent will not be reusable until |
163 | all of the memory in that extent has been freed with one | |
164 | exception: the most recent pool allocation may be freed back | |
165 | into the pool prior to making any further allocations. | |
166 | If enough free calls are made to indicate that an extent has no | |
167 | remaining allocated objects (as computed by the total freed size for | |
168 | an extent), its memory will be completely freed back to the system. | |
7efdcf32 S |
169 | If |
170 | .I addr | |
171 | is | |
33766a8d WD |
172 | .BR 0 , |
173 | no memory will be freed, but subsequent allocations will come | |
7efdcf32 S |
174 | from a new extent. |
175 | .P | |
676e6041 WD |
176 | .B pool_free_old() |
177 | takes a boundary | |
178 | .I addr | |
179 | value that was returned by | |
180 | .B pool_boundary() | |
181 | and frees up any extents in the | |
182 | .I pool | |
183 | that have data allocated from that point backward in time. | |
184 | NOTE: you must NOT mix calls to both | |
185 | .B pool_free | |
186 | and | |
187 | .B pool_free_old | |
188 | on the same pool! | |
189 | .P | |
190 | .B pool_boundary() | |
191 | asks for a boundary value that can be sent to | |
192 | .B pool_free_old() | |
193 | at a later time to free up all memory allocated prior to a particular | |
194 | moment in time. | |
195 | If the extent that holds the boundary point has allocations from after the | |
196 | boundary point, it will not be freed until a future | |
197 | .B pool_free_old() | |
198 | call encompasses the entirety of the extent's data. | |
199 | If | |
200 | .I len | |
201 | is non-zero, the call will also check if the active extent has at least | |
202 | that much free memory available in it, and if not, it will mark the | |
203 | extent as inactive, forcing a new extent to be used for future allocations. | |
204 | (You can specify -1 for | |
205 | .I len | |
206 | if you want to force a new extent to start.) | |
207 | .P | |
7efdcf32 | 208 | .B pool_talloc() |
33766a8d | 209 | is a macro that takes a |
7efdcf32 | 210 | .I type |
33766a8d | 211 | and a |
7efdcf32 | 212 | .I count |
33766a8d WD |
213 | instead of a |
214 | .IR size . | |
215 | It casts the return value to the correct pointer type. | |
7efdcf32 S |
216 | .P |
217 | .B pool_tfree | |
33766a8d WD |
218 | is a macro that calls |
219 | .B pool_free | |
220 | on memory that was allocated by | |
221 | .BR pool_talloc() . | |
7efdcf32 S |
222 | .SH RETURN VALUE |
223 | .B pool_create() | |
224 | returns a pointer to | |
225 | .BR "struct alloc_pool" . | |
226 | .P | |
227 | .B pool_alloc() | |
228 | and | |
229 | .B pool_talloc() | |
230 | return pointers to the allocated memory, | |
231 | or NULL if the request fails. | |
7efdcf32 S |
232 | The return type of |
233 | .B pool_alloc() | |
234 | will normally require casting to the desired type but | |
235 | .B pool_talloc() | |
236 | will returns a pointer of the requested | |
237 | .IR type . | |
238 | .P | |
676e6041 WD |
239 | .B pool_boundary() |
240 | returns a pointer that should only be used in a call to | |
241 | .BR pool_free_old() . | |
242 | .P | |
7efdcf32 | 243 | .BR pool_free() , |
676e6041 | 244 | .BR pool_free_old() , |
7efdcf32 S |
245 | .B pool_tfree() |
246 | and | |
247 | .B pool_destroy() | |
248 | return no value. | |
249 | .SH SEE ALSO | |
250 | .nf | |
251 | malloc(3) | |
252 | .SH AUTHOR | |
253 | pool_alloc was created by J.W. Schultz of Pegasystems Technologies. | |
254 | .SH BUGS AND ISSUES |