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_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, size_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 memory within a given pool
  53 to be allocated in large contiguous blocks
  54 (called extents) that will be reusable when freed.  Unlike
  55 .BR 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 at the request of the user),
  62 memory within that extent ceases to be used for allocation,
  63 and a new extent is added to the pool.
  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 contiguous extents,
  70 when an extent is freed, it releases a large enough
  71 contiguous block of memory to allow the memory to be returned
  72 to the OS for use by whatever program needs it.
  73 You can allocate from one or more memory pools and/or
  74 .B malloc()
  75 all at the same time without interfering with how pools work.
  76 .P
  77 .B pool_create()
  78 Creates an allocation pool for subsequent calls to the pool
  79 allocation functions.
  80 When an extent is created for allocations it will be
  81 .I size
  82 bytes.
  83 Allocations from the pool have their sizes rounded up to a
  84 multiple of
  85 .I quantum
  86 bytes in length.
  87 Specifying
  88 .B 0
  89 for
  90 .I quantum
  91 will produce a quantum that should meet maximal alignment
  92 on most platforms.
  93 If
  94 .B POOL_QALIGN
  95 is set in the
  96 .IR flags ,
  97 allocations will be aligned to addresses that are a
  98 multiple of
  99 .IR quantum .
 100 If
 101 .B POOL_CLEAR
 102 is set in the
 103 .IR flags ,
 104 all allocations from the pool will be initialized to zeros.
 105 You may specify a
 106 .B NULL
 107 for the
 108 .I bomb
 109 function pointer if you don't wish to use it.  (See the
 110 .B pool_alloc()
 111 function for how it is used.)
 112 .P
 113 .B pool_destroy()
 114 destroys an allocation
 115 .I pool
 116 and frees all its associated memory.
 117 .P
 118 .B pool_alloc()
 119 allocates
 120 .I size
 121 bytes from the specified
 122 .IR pool .
 123 If
 124 .I size
 125 is
 126 .BR 0 ,
 127 .I quantum
 128 bytes will be allocated.
 129 If the pool has been created with
 130 .BR POOL_QALIGN ,
 131 every chunk of memory that is returned will be suitably aligned.
 132 You can use this with the default
 133 .I quantum
 134 size to ensure that all memory can store a variable of any type.
 135 If the requested memory cannot be allocated, the
 136 .I bomb()
 137 function will be called with
 138 .I msg
 139 as its sole argument (if the function was defined at the time
 140 the pool was created), and then a
 141 .B NULL
 142 address is returned (assuming that the bomb function didn't exit).
 143 .P
 144 .B pool_free()
 145 frees
 146 .I size
 147 bytes pointed to by an
 148 .I addr
 149 that was previously allocated in the specified
 150 .IR pool .
 151 If
 152 .I size
 153 is
 154 .BR 0 ,
 155 .I quantum
 156 bytes will be freed.
 157 The memory freed within an extent will not be reusable until
 158 all of the memory in that extent has been freed with one
 159 exception: the most recent pool allocation may be freed back
 160 into the pool prior to making any further allocations.
 161 If enough free calls are made to indicate that an extent has no
 162 remaining allocated objects (as computed by the total freed size for
 163 an extent), its memory will be completely freed back to the system.
 164 If
 165 .I addr
 166 is
 167 .BR 0 ,
 168 no memory will be freed, but subsequent allocations will come
 169 from a new extent.
 170 .P
 171 .B pool_talloc()
 172 is a macro that takes a
 173 .I type
 174 and a
 175 .I count
 176 instead of a
 177 .IR size .
 178 It casts the return value to the correct pointer type.
 179 .P
 180 .B pool_tfree
 181 is a macro that calls
 182 .B pool_free
 183 on memory that was allocated by
 184 .BR pool_talloc() .
 185 .SH RETURN VALUE
 186 .B pool_create()
 187 returns a pointer to
 188 .BR "struct alloc_pool" .
 189 .P
 190 .B pool_alloc()
 191 and
 192 .B pool_talloc()
 193 return pointers to the allocated memory,
 194 or NULL if the request fails.
 195 The return type of
 196 .B pool_alloc()
 197 will normally require casting to the desired type but
 198 .B pool_talloc()
 199 will returns a pointer of the requested
 200 .IR type .
 201 .P
 202 .BR pool_free() ,
 203 .B pool_tfree()
 204 and
 205 .B pool_destroy()
 206 return no value.
 207 .SH SEE ALSO
 208 .nf
 209 malloc(3)
 210 .SH AUTHOR
 211 pool_alloc was created by J.W. Schultz of Pegasystems Technologies.
 212 .SH BUGS AND ISSUES