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