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, 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