lib/pool_alloc.3

   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