| 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_talloc, pool_tfree, pool_create, pool_destroy |
| 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, sise_t \fIsize\fB, void *\fIaddr\fB); |
| 43 | |
| 44 | \fBvoid *pool_talloc(struct alloc_pool *\fIpool\fB, \fItype\fB), int \fIcount\fB, char *\fImsg\fB); |
| 45 | |
| 46 | \fBvoid pool_tfree(struct alloc_pool *\fIpool\fB, \fItype\fB, int \fIcount\fB, void *\fIaddr\fB); |
| 47 | .SH DESCRIPTION |
| 48 | .P |
| 49 | The pool allocation routines use |
| 50 | .B malloc() |
| 51 | for underlying memory management. |
| 52 | What allocation pools do is cause |
| 53 | memory within a given pool to be in large contigious blocks |
| 54 | (called extents) that when freed will be reusable. Unlike |
| 55 | .B malloc() |
| 56 | the allocations are not managed individually. |
| 57 | Instead each extent tracks the total free memory within the |
| 58 | extent. Each extent can either be used to allocate memory |
| 59 | or to manage the freeing of memory within that extent. |
| 60 | When an extent has less free memory than a given |
| 61 | allocation request or when the first request to free |
| 62 | memory within that extent is received the extent ceases to |
| 63 | be used for allocation. |
| 64 | .P |
| 65 | This form of memory management is suited to large numbers of small |
| 66 | related allocations that are held for a while |
| 67 | and then freed as a group. |
| 68 | Because the |
| 69 | underlying allocations are done in large contigious extents |
| 70 | when an extent is freed it releases a large enough |
| 71 | contigious block of memory to be useful to subsequent |
| 72 | .B malloc() |
| 73 | and |
| 74 | .B pool_alloc() |
| 75 | calls even if allocations from other pools or from |
| 76 | .B malloc() |
| 77 | are made between allocations from a given pool. |
| 78 | .P |
| 79 | .B pool_create() |
| 80 | Creates an allocation pool for subsequent calls to the pool |
| 81 | allocation functions. |
| 82 | When an extent is created for allocations it will be |
| 83 | .I size |
| 84 | bytes. |
| 85 | Allocations from the pool have their sizes rounded up to a |
| 86 | multiple of |
| 87 | .I quantum |
| 88 | bytes in length. |
| 89 | Specifying |
| 90 | .B 0 |
| 91 | for |
| 92 | .I quantum |
| 93 | Will produce a quantum that should meet maximal allignment |
| 94 | on most platforms. |
| 95 | If the |
| 96 | .B POOL_QALIGN |
| 97 | .I flag |
| 98 | is set allocations will be aligned to addresses that are a |
| 99 | multiple of |
| 100 | .IR quantum . |
| 101 | If the |
| 102 | .B POOL_CLEAR |
| 103 | .I flag |
| 104 | is set all allocations from the pool will be zero filled. |
| 105 | .P |
| 106 | .B pool_destroy() |
| 107 | destroys an allocation pool and frees all memory allocated |
| 108 | in that pool. |
| 109 | .P |
| 110 | .B pool_alloc() |
| 111 | allocates |
| 112 | .I size |
| 113 | bytes from the specified |
| 114 | .IR pool . |
| 115 | If |
| 116 | .I size |
| 117 | is |
| 118 | .B 0 |
| 119 | .I quantum |
| 120 | bytes will be freed. |
| 121 | If the requested memory cannot be allocated |
| 122 | .B pool_alloc() |
| 123 | will call |
| 124 | .I bomb() |
| 125 | function, if defined, with |
| 126 | .I msg |
| 127 | as it's sole argument and |
| 128 | .B NULL |
| 129 | will be returned. |
| 130 | .P |
| 131 | .B pool_free() |
| 132 | frees |
| 133 | .I size |
| 134 | bytes pointed to by |
| 135 | .I addr |
| 136 | previously allocated in the specified |
| 137 | .IR pool . |
| 138 | The memory freed within an extent will not be reusable until |
| 139 | all of the memory in that extent has been freed but |
| 140 | depending on the order in which the |
| 141 | allocations are freed some extents may be released for reuse |
| 142 | while others are still in use. |
| 143 | If |
| 144 | .I size |
| 145 | is |
| 146 | .B 0 |
| 147 | .I quantum |
| 148 | bytes will be freed. |
| 149 | If |
| 150 | .I addr |
| 151 | is |
| 152 | .B 0 |
| 153 | no memory will be freed but subsequent allocations will come |
| 154 | from a new extent. |
| 155 | .P |
| 156 | .B pool_talloc() |
| 157 | is a macro that take a |
| 158 | .I type |
| 159 | and |
| 160 | .I count |
| 161 | instead of |
| 162 | .I size |
| 163 | and will cast the return value to the correct type. |
| 164 | .P |
| 165 | .B pool_tfree |
| 166 | is a macro to free memory previously allocated in the |
| 167 | specified |
| 168 | .IR pool . |
| 169 | .SH RETURN VALUE |
| 170 | .B pool_create() |
| 171 | returns a pointer to |
| 172 | .BR "struct alloc_pool" . |
| 173 | .P |
| 174 | .B pool_alloc() |
| 175 | and |
| 176 | .B pool_talloc() |
| 177 | return pointers to the allocated memory, |
| 178 | or NULL if the request fails. |
| 179 | For each extent so long as no allocations are smaller than varaible |
| 180 | allignment requirements this pointer will be suitably |
| 181 | alligned for any kind of variable. |
| 182 | The return type of |
| 183 | .B pool_alloc() |
| 184 | will normally require casting to the desired type but |
| 185 | .B pool_talloc() |
| 186 | will returns a pointer of the requested |
| 187 | .IR type . |
| 188 | .P |
| 189 | .BR pool_free() , |
| 190 | .B pool_tfree() |
| 191 | and |
| 192 | .B pool_destroy() |
| 193 | return no value. |
| 194 | .SH SEE ALSO |
| 195 | .nf |
| 196 | malloc(3) |
| 197 | .SH AUTHOR |
| 198 | pool_alloc was created by J.W. Schultz of Pegasystems Technologies. |
| 199 | .SH BUGS AND ISSUES |