Commit | Line | Data |
---|---|---|
7efdcf32 S |
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 | ||
33766a8d | 42 | \fBvoid pool_free(struct alloc_pool *\fIpool\fB, size_t \fIsize\fB, void *\fIaddr\fB); |
7efdcf32 S |
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. | |
33766a8d WD |
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() , | |
7efdcf32 | 56 | the allocations are not managed individually. |
33766a8d | 57 | Instead, each extent tracks the total free memory within the |
7efdcf32 S |
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 | |
33766a8d WD |
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. | |
7efdcf32 S |
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 | |
33766a8d WD |
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 | |
7efdcf32 | 74 | .B malloc() |
33766a8d | 75 | all at the same time without interfering with how pools work. |
7efdcf32 S |
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 | |
33766a8d | 91 | will produce a quantum that should meet maximal alignment |
7efdcf32 | 92 | on most platforms. |
33766a8d | 93 | If |
7efdcf32 | 94 | .B POOL_QALIGN |
33766a8d WD |
95 | is set in the |
96 | .IR flags , | |
97 | allocations will be aligned to addresses that are a | |
7efdcf32 S |
98 | multiple of |
99 | .IR quantum . | |
33766a8d | 100 | If |
7efdcf32 | 101 | .B POOL_CLEAR |
33766a8d WD |
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.) | |
7efdcf32 S |
112 | .P |
113 | .B pool_destroy() | |
33766a8d WD |
114 | destroys an allocation |
115 | .I pool | |
116 | and frees all its associated memory. | |
7efdcf32 S |
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 | |
33766a8d | 126 | .BR 0 , |
7efdcf32 | 127 | .I quantum |
33766a8d WD |
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 | |
7efdcf32 | 136 | .I bomb() |
33766a8d | 137 | function will be called with |
7efdcf32 | 138 | .I msg |
33766a8d WD |
139 | as its sole argument (if the function was defined at the time |
140 | the pool was created), and then a | |
7efdcf32 | 141 | .B NULL |
33766a8d | 142 | address is returned (assuming that the bomb function didn't exit). |
7efdcf32 S |
143 | .P |
144 | .B pool_free() | |
145 | frees | |
146 | .I size | |
33766a8d | 147 | bytes pointed to by an |
7efdcf32 | 148 | .I addr |
33766a8d | 149 | that was previously allocated in the specified |
7efdcf32 | 150 | .IR pool . |
7efdcf32 S |
151 | If |
152 | .I size | |
153 | is | |
33766a8d | 154 | .BR 0 , |
7efdcf32 S |
155 | .I quantum |
156 | bytes will be freed. | |
33766a8d WD |
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. | |
7efdcf32 S |
164 | If |
165 | .I addr | |
166 | is | |
33766a8d WD |
167 | .BR 0 , |
168 | no memory will be freed, but subsequent allocations will come | |
7efdcf32 S |
169 | from a new extent. |
170 | .P | |
171 | .B pool_talloc() | |
33766a8d | 172 | is a macro that takes a |
7efdcf32 | 173 | .I type |
33766a8d | 174 | and a |
7efdcf32 | 175 | .I count |
33766a8d WD |
176 | instead of a |
177 | .IR size . | |
178 | It casts the return value to the correct pointer type. | |
7efdcf32 S |
179 | .P |
180 | .B pool_tfree | |
33766a8d WD |
181 | is a macro that calls |
182 | .B pool_free | |
183 | on memory that was allocated by | |
184 | .BR pool_talloc() . | |
7efdcf32 S |
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. | |
7efdcf32 S |
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 |