24 See \fB\\$1\fP for details.
27 See \fB\\$1\fP in \fB\\$2\fP for details.
31 pool_alloc, pool_free, pool_talloc, pool_tfree, pool_create, pool_destroy
32 \- Allocate and free memory in managed allocation pools.
34 .B #include "pool_alloc.h"
36 \fBstruct alloc_pool *pool_create(size_t \fIsize\fB, size_t \fIquantum\fB, void (*\fIbomb\fB)(char *), int \fIflags\fB);
38 \fBvoid pool_destroy(struct alloc_pool *\fIpool\fB);
40 \fBvoid *pool_alloc(struct alloc_pool *\fIpool\fB, size_t \fIsize\fB, char *\fImsg\fB);
42 \fBvoid pool_free(struct alloc_pool *\fIpool\fB, size_t \fIsize\fB, void *\fIaddr\fB);
44 \fBvoid *pool_talloc(struct alloc_pool *\fIpool\fB, \fItype\fB), int \fIcount\fB, char *\fImsg\fB);
46 \fBvoid pool_tfree(struct alloc_pool *\fIpool\fB, \fItype\fB, int \fIcount\fB, void *\fIaddr\fB);
49 The pool allocation routines use
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
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.
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.
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
75 all at the same time without interfering with how pools work.
78 Creates an allocation pool for subsequent calls to the pool
80 When an extent is created for allocations it will be
83 Allocations from the pool have their sizes rounded up to a
91 will produce a quantum that should meet maximal alignment
97 allocations will be aligned to addresses that are a
104 all allocations from the pool will be initialized to zeros.
109 function pointer if you don't wish to use it. (See the
111 function for how it is used.)
114 destroys an allocation
116 and frees all its associated memory.
121 bytes from the specified
128 bytes will be allocated.
129 If the pool has been created with
131 every chunk of memory that is returned will be suitably aligned.
132 You can use this with the default
134 size to ensure that all memory can store a variable of any type.
135 If the requested memory cannot be allocated, the
137 function will be called with
139 as its sole argument (if the function was defined at the time
140 the pool was created), and then a
142 address is returned (assuming that the bomb function didn't exit).
147 bytes pointed to by an
149 that was previously allocated in the specified
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.
168 no memory will be freed, but subsequent allocations will come
172 is a macro that takes a
178 It casts the return value to the correct pointer type.
181 is a macro that calls
183 on memory that was allocated by
188 .BR "struct alloc_pool" .
193 return pointers to the allocated memory,
194 or NULL if the request fails.
197 will normally require casting to the desired type but
199 will returns a pointer of the requested
211 pool_alloc was created by J.W. Schultz of Pegasystems Technologies.