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 If
  99 .B POOL_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 If
 106 .B POOL_CLEAR
 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.)
 117 .P
 118 .B pool_destroy()
 119 destroys an allocation
 120 .I pool
 121 and frees all its associated memory.
 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
 131 .BR 0 ,
 132 .I quantum
 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
 141 .I bomb()
 142 function will be called with
 143 .I msg
 144 as its sole argument (if the function was defined at the time
 145 the pool was created), and then a
 146 .B NULL
 147 address is returned (assuming that the bomb function didn't exit).
 148 .P
 149 .B pool_free()
 150 frees
 151 .I size
 152 bytes pointed to by an
 153 .I addr
 154 that was previously allocated in the specified
 155 .IR pool .
 156 If
 157 .I size
 158 is
 159 .BR 0 ,
 160 .I quantum
 161 bytes will be freed.
 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.
 169 If
 170 .I addr
 171 is
 172 .BR 0 ,
 173 no memory will be freed, but subsequent allocations will come
 174 from a new extent.
 175 .P
 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
 208 .B pool_talloc()
 209 is a macro that takes a
 210 .I type
 211 and a
 212 .I count
 213 instead of a
 214 .IR size .
 215 It casts the return value to the correct pointer type.
 216 .P
 217 .B pool_tfree
 218 is a macro that calls
 219 .B pool_free
 220 on memory that was allocated by
 221 .BR pool_talloc() .
 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.
 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
 239 .B pool_boundary()
 240 returns a pointer that should only be used in a call to
 241 .BR pool_free_old() .
 242 .P
 243 .BR pool_free() ,
 244 .BR pool_free_old() ,
 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