| 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 |
| 31 | pool_alloc, pool_free, pool_free_old, pool_talloc, pool_tfree, pool_create, pool_destroy, pool_boundary |
| 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 | |
| 42 | \fBvoid pool_free(struct alloc_pool *\fIpool\fB, size_t \fIsize\fB, void *\fIaddr\fB); |
| 43 | |
| 44 | \fBvoid pool_free_old(struct alloc_pool *\fIpool\fB, void *\fIaddr\fB); |
| 45 | |
| 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); |
| 49 | |
| 50 | \fBvoid pool_boundary(struct alloc_pool *\fIpool\fB, sise_t \fIsize\fB); |
| 51 | .SH DESCRIPTION |
| 52 | .P |
| 53 | The pool allocation routines use |
| 54 | .B malloc() |
| 55 | for underlying memory management. |
| 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() , |
| 60 | the allocations are not managed individually. |
| 61 | Instead, each extent tracks the total free memory within the |
| 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 |
| 65 | allocation request, the current extent ceases to be used |
| 66 | for allocation. See also the |
| 67 | .B pool_boundary() |
| 68 | function. |
| 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 |
| 74 | underlying allocations are done in large contiguous extents, |
| 75 | when an extent is freed, it can release a large enough |
| 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 |
| 79 | .B malloc() |
| 80 | all at the same time without interfering with how pools work. |
| 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 |
| 96 | will produce a quantum that should meet maximal alignment |
| 97 | on most platforms. |
| 98 | Unless |
| 99 | .B POOL_NO_QALIGN |
| 100 | is set in the |
| 101 | .IR flags , |
| 102 | allocations will be aligned to addresses that are a |
| 103 | multiple of |
| 104 | .IR quantum . |
| 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.) |
| 112 | If |
| 113 | .B POOL_CLEAR |
| 114 | is set in the |
| 115 | .IR flags , |
| 116 | all allocations from the pool will be initialized to zeros. |
| 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 . |
| 131 | .P |
| 132 | .B pool_destroy() |
| 133 | destroys an allocation |
| 134 | .I pool |
| 135 | and frees all its associated memory. |
| 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 |
| 145 | .BR 0 , |
| 146 | .I quantum |
| 147 | bytes will be allocated. |
| 148 | If the pool has been created without |
| 149 | .BR POOL_NO_QALIGN , |
| 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 |
| 155 | .I bomb() |
| 156 | function will be called with |
| 157 | .I msg |
| 158 | as its sole argument (if the function was defined at the time |
| 159 | the pool was created), and then a |
| 160 | .B NULL |
| 161 | address is returned (assuming that the bomb function didn't exit). |
| 162 | .P |
| 163 | .B pool_free() |
| 164 | frees |
| 165 | .I size |
| 166 | bytes pointed to by an |
| 167 | .I addr |
| 168 | that was previously allocated in the specified |
| 169 | .IR pool . |
| 170 | If |
| 171 | .I size |
| 172 | is |
| 173 | .BR 0 , |
| 174 | .I quantum |
| 175 | bytes will be freed. |
| 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. |
| 183 | If |
| 184 | .I addr |
| 185 | is |
| 186 | .BR NULL , |
| 187 | no memory will be freed, but subsequent allocations will come |
| 188 | from a new extent. |
| 189 | .P |
| 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 |
| 222 | .B pool_talloc() |
| 223 | is a macro that takes a |
| 224 | .I type |
| 225 | and a |
| 226 | .I count |
| 227 | instead of a |
| 228 | .IR size . |
| 229 | It casts the return value to the correct pointer type. |
| 230 | .P |
| 231 | .B pool_tfree |
| 232 | is a macro that calls |
| 233 | .B pool_free |
| 234 | on memory that was allocated by |
| 235 | .BR pool_talloc() . |
| 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. |
| 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 |
| 253 | .B pool_boundary() |
| 254 | returns a pointer that should only be used in a call to |
| 255 | .BR pool_free_old() . |
| 256 | .P |
| 257 | .BR pool_free() , |
| 258 | .BR pool_free_old() , |
| 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 |