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. |
fb01d1fb WD |
98 | Unless |
99 | .B POOL_NO_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 . | |
fb01d1fb WD |
105 | A |
106 | .B NULL | |
107 | may be specified for the | |
108 | .I bomb | |
109 | function pointer if it is not needed. (See the | |
110 | .B pool_alloc() | |
111 | function for how it is used.) | |
33766a8d | 112 | If |
7efdcf32 | 113 | .B POOL_CLEAR |
33766a8d WD |
114 | is set in the |
115 | .IR flags , | |
116 | all allocations from the pool will be initialized to zeros. | |
fb01d1fb WD |
117 | If either |
118 | .B POOL_PREPEND | |
119 | or | |
120 | .B POOL_INTERN | |
121 | is specified in the | |
122 | .IR flags , | |
123 | each extent's data structure will be allocated at the start of the | |
124 | .IR size -length | |
125 | buffer (rather than as a separate, non-pool allocation), with the | |
126 | former extending the | |
127 | .I size | |
128 | to hold the structure, and the latter subtracting the structure's | |
129 | length from the indicated | |
130 | .IR size . | |
7efdcf32 S |
131 | .P |
132 | .B pool_destroy() | |
33766a8d WD |
133 | destroys an allocation |
134 | .I pool | |
135 | and frees all its associated memory. | |
7efdcf32 S |
136 | .P |
137 | .B pool_alloc() | |
138 | allocates | |
139 | .I size | |
140 | bytes from the specified | |
141 | .IR pool . | |
142 | If | |
143 | .I size | |
144 | is | |
33766a8d | 145 | .BR 0 , |
7efdcf32 | 146 | .I quantum |
33766a8d | 147 | bytes will be allocated. |
fb01d1fb WD |
148 | If the pool has been created without |
149 | .BR POOL_NO_QALIGN , | |
33766a8d WD |
150 | every chunk of memory that is returned will be suitably aligned. |
151 | You can use this with the default | |
152 | .I quantum | |
153 | size to ensure that all memory can store a variable of any type. | |
154 | If the requested memory cannot be allocated, the | |
7efdcf32 | 155 | .I bomb() |
33766a8d | 156 | function will be called with |
7efdcf32 | 157 | .I msg |
33766a8d WD |
158 | as its sole argument (if the function was defined at the time |
159 | the pool was created), and then a | |
7efdcf32 | 160 | .B NULL |
33766a8d | 161 | address is returned (assuming that the bomb function didn't exit). |
7efdcf32 S |
162 | .P |
163 | .B pool_free() | |
164 | frees | |
165 | .I size | |
33766a8d | 166 | bytes pointed to by an |
7efdcf32 | 167 | .I addr |
33766a8d | 168 | that was previously allocated in the specified |
7efdcf32 | 169 | .IR pool . |
7efdcf32 S |
170 | If |
171 | .I size | |
172 | is | |
33766a8d | 173 | .BR 0 , |
7efdcf32 S |
174 | .I quantum |
175 | bytes will be freed. | |
33766a8d WD |
176 | The memory freed within an extent will not be reusable until |
177 | all of the memory in that extent has been freed with one | |
178 | exception: the most recent pool allocation may be freed back | |
179 | into the pool prior to making any further allocations. | |
180 | If enough free calls are made to indicate that an extent has no | |
181 | remaining allocated objects (as computed by the total freed size for | |
182 | an extent), its memory will be completely freed back to the system. | |
7efdcf32 S |
183 | If |
184 | .I addr | |
185 | is | |
fb01d1fb | 186 | .BR NULL , |
33766a8d | 187 | no memory will be freed, but subsequent allocations will come |
7efdcf32 S |
188 | from a new extent. |
189 | .P | |
676e6041 WD |
190 | .B pool_free_old() |
191 | takes a boundary | |
192 | .I addr | |
193 | value that was returned by | |
194 | .B pool_boundary() | |
195 | and frees up any extents in the | |
196 | .I pool | |
197 | that have data allocated from that point backward in time. | |
198 | NOTE: you must NOT mix calls to both | |
199 | .B pool_free | |
200 | and | |
201 | .B pool_free_old | |
202 | on the same pool! | |
203 | .P | |
204 | .B pool_boundary() | |
205 | asks for a boundary value that can be sent to | |
206 | .B pool_free_old() | |
207 | at a later time to free up all memory allocated prior to a particular | |
208 | moment in time. | |
209 | If the extent that holds the boundary point has allocations from after the | |
210 | boundary point, it will not be freed until a future | |
211 | .B pool_free_old() | |
212 | call encompasses the entirety of the extent's data. | |
213 | If | |
214 | .I len | |
215 | is non-zero, the call will also check if the active extent has at least | |
216 | that much free memory available in it, and if not, it will mark the | |
217 | extent as inactive, forcing a new extent to be used for future allocations. | |
218 | (You can specify -1 for | |
219 | .I len | |
220 | if you want to force a new extent to start.) | |
221 | .P | |
7efdcf32 | 222 | .B pool_talloc() |
33766a8d | 223 | is a macro that takes a |
7efdcf32 | 224 | .I type |
33766a8d | 225 | and a |
7efdcf32 | 226 | .I count |
33766a8d WD |
227 | instead of a |
228 | .IR size . | |
229 | It casts the return value to the correct pointer type. | |
7efdcf32 S |
230 | .P |
231 | .B pool_tfree | |
33766a8d WD |
232 | is a macro that calls |
233 | .B pool_free | |
234 | on memory that was allocated by | |
235 | .BR pool_talloc() . | |
7efdcf32 S |
236 | .SH RETURN VALUE |
237 | .B pool_create() | |
238 | returns a pointer to | |
239 | .BR "struct alloc_pool" . | |
240 | .P | |
241 | .B pool_alloc() | |
242 | and | |
243 | .B pool_talloc() | |
244 | return pointers to the allocated memory, | |
245 | or NULL if the request fails. | |
7efdcf32 S |
246 | The return type of |
247 | .B pool_alloc() | |
248 | will normally require casting to the desired type but | |
249 | .B pool_talloc() | |
250 | will returns a pointer of the requested | |
251 | .IR type . | |
252 | .P | |
676e6041 WD |
253 | .B pool_boundary() |
254 | returns a pointer that should only be used in a call to | |
255 | .BR pool_free_old() . | |
256 | .P | |
7efdcf32 | 257 | .BR pool_free() , |
676e6041 | 258 | .BR pool_free_old() , |
7efdcf32 S |
259 | .B pool_tfree() |
260 | and | |
261 | .B pool_destroy() | |
262 | return no value. | |
263 | .SH SEE ALSO | |
264 | .nf | |
265 | malloc(3) | |
266 | .SH AUTHOR | |
267 | pool_alloc was created by J.W. Schultz of Pegasystems Technologies. | |
268 | .SH BUGS AND ISSUES |