Annotation of embedaddon/rsync/lib/pool_alloc.3, revision 1.1.1.3
1.1 misho 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_free_old, pool_talloc, pool_tfree, pool_create, pool_destroy, pool_boundary
32: \- Allocate and free memory in managed allocation pools.
33: .SH SYNOPSIS
34: .B #include "pool_alloc.h"
35:
1.1.1.3 ! misho 36: \fBstruct alloc_pool *pool_create(size_t \fIsize\fB, size_t \fIquantum\fB, void (*\fIbomb\fB)(char*,char*,int), int \fIflags\fB);
1.1 misho 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_free_old(struct alloc_pool *\fIpool\fB, void *\fIaddr\fB);
45:
46: \fBvoid *pool_talloc(struct alloc_pool *\fIpool\fB, \fItype\fB), int \fIcount\fB, char *\fImsg\fB);
47:
48: \fBvoid pool_tfree(struct alloc_pool *\fIpool\fB, \fItype\fB, int \fIcount\fB, void *\fIaddr\fB);
49:
50: \fBvoid pool_boundary(struct alloc_pool *\fIpool\fB, sise_t \fIsize\fB);
51: .SH DESCRIPTION
52: .P
53: The pool allocation routines use
54: .B malloc()
55: for underlying memory management.
56: What allocation pools do is cause memory within a given pool
57: to be allocated in large contiguous blocks
58: (called extents) that will be reusable when freed. Unlike
59: .BR malloc() ,
60: the allocations are not managed individually.
61: Instead, each extent tracks the total free memory within the
62: extent. Each extent can either be used to allocate memory
63: or to manage the freeing of memory within that extent.
64: When an extent has less free memory than a given
65: allocation request, the current extent ceases to be used
66: for allocation. See also the
67: .B pool_boundary()
68: function.
69: .P
70: This form of memory management is suited to large numbers of small
71: related allocations that are held for a while
72: and then freed as a group.
73: Because the
74: underlying allocations are done in large contiguous extents,
75: when an extent is freed, it can release a large enough
76: contiguous block of memory to allow the memory to be returned
77: to the OS for use by whatever program needs it.
78: You can allocate from one or more memory pools and/or
79: .B malloc()
80: all at the same time without interfering with how pools work.
81: .P
82: .B pool_create()
83: Creates an allocation pool for subsequent calls to the pool
84: allocation functions.
85: When an extent is created for allocations it will be
86: .I size
87: bytes.
88: Allocations from the pool have their sizes rounded up to a
89: multiple of
90: .I quantum
91: bytes in length.
92: Specifying
93: .B 0
94: for
95: .I quantum
96: will produce a quantum that should meet maximal alignment
97: on most platforms.
1.1.1.2 misho 98: Unless
99: .B POOL_NO_QALIGN
1.1 misho 100: is set in the
101: .IR flags ,
102: allocations will be aligned to addresses that are a
103: multiple of
104: .IR quantum .
1.1.1.2 misho 105: A
106: .B NULL
107: may be specified for the
108: .I bomb
109: function pointer if it is not needed. (See the
110: .B pool_alloc()
111: function for how it is used.)
1.1 misho 112: If
113: .B POOL_CLEAR
114: is set in the
115: .IR flags ,
116: all allocations from the pool will be initialized to zeros.
1.1.1.2 misho 117: If either
118: .B POOL_PREPEND
119: or
120: .B POOL_INTERN
121: is specified in the
122: .IR flags ,
123: each extent's data structure will be allocated at the start of the
124: .IR size -length
125: buffer (rather than as a separate, non-pool allocation), with the
126: former extending the
127: .I size
128: to hold the structure, and the latter subtracting the structure's
129: length from the indicated
130: .IR size .
1.1 misho 131: .P
132: .B pool_destroy()
133: destroys an allocation
134: .I pool
135: and frees all its associated memory.
136: .P
137: .B pool_alloc()
138: allocates
139: .I size
140: bytes from the specified
141: .IR pool .
142: If
143: .I size
144: is
145: .BR 0 ,
146: .I quantum
147: bytes will be allocated.
1.1.1.2 misho 148: If the pool has been created without
149: .BR POOL_NO_QALIGN ,
1.1 misho 150: every chunk of memory that is returned will be suitably aligned.
151: You can use this with the default
152: .I quantum
153: size to ensure that all memory can store a variable of any type.
154: If the requested memory cannot be allocated, the
155: .I bomb()
156: function will be called with
157: .I msg
158: as its sole argument (if the function was defined at the time
159: the pool was created), and then a
160: .B NULL
161: address is returned (assuming that the bomb function didn't exit).
162: .P
163: .B pool_free()
164: frees
165: .I size
166: bytes pointed to by an
167: .I addr
168: that was previously allocated in the specified
169: .IR pool .
170: If
171: .I size
172: is
173: .BR 0 ,
174: .I quantum
175: bytes will be freed.
176: The memory freed within an extent will not be reusable until
177: all of the memory in that extent has been freed with one
178: exception: the most recent pool allocation may be freed back
179: into the pool prior to making any further allocations.
180: If enough free calls are made to indicate that an extent has no
181: remaining allocated objects (as computed by the total freed size for
182: an extent), its memory will be completely freed back to the system.
183: If
184: .I addr
185: is
1.1.1.2 misho 186: .BR NULL ,
1.1 misho 187: no memory will be freed, but subsequent allocations will come
188: from a new extent.
189: .P
190: .B pool_free_old()
191: takes a boundary
192: .I addr
193: value that was returned by
194: .B pool_boundary()
195: and frees up any extents in the
196: .I pool
197: that have data allocated from that point backward in time.
198: NOTE: you must NOT mix calls to both
199: .B pool_free
200: and
201: .B pool_free_old
202: on the same pool!
203: .P
204: .B pool_boundary()
205: asks for a boundary value that can be sent to
206: .B pool_free_old()
207: at a later time to free up all memory allocated prior to a particular
208: moment in time.
209: If the extent that holds the boundary point has allocations from after the
210: boundary point, it will not be freed until a future
211: .B pool_free_old()
212: call encompasses the entirety of the extent's data.
213: If
214: .I len
215: is non-zero, the call will also check if the active extent has at least
216: that much free memory available in it, and if not, it will mark the
217: extent as inactive, forcing a new extent to be used for future allocations.
218: (You can specify -1 for
219: .I len
220: if you want to force a new extent to start.)
221: .P
222: .B pool_talloc()
223: is a macro that takes a
224: .I type
225: and a
226: .I count
227: instead of a
228: .IR size .
229: It casts the return value to the correct pointer type.
230: .P
231: .B pool_tfree
232: is a macro that calls
233: .B pool_free
234: on memory that was allocated by
235: .BR pool_talloc() .
236: .SH RETURN VALUE
237: .B pool_create()
238: returns a pointer to
239: .BR "struct alloc_pool" .
240: .P
241: .B pool_alloc()
242: and
243: .B pool_talloc()
244: return pointers to the allocated memory,
245: or NULL if the request fails.
246: The return type of
247: .B pool_alloc()
248: will normally require casting to the desired type but
249: .B pool_talloc()
250: will returns a pointer of the requested
251: .IR type .
252: .P
253: .B pool_boundary()
254: returns a pointer that should only be used in a call to
255: .BR pool_free_old() .
256: .P
257: .BR pool_free() ,
258: .BR pool_free_old() ,
259: .B pool_tfree()
260: and
261: .B pool_destroy()
262: return no value.
263: .SH SEE ALSO
264: .nf
265: malloc(3)
266: .SH AUTHOR
267: pool_alloc was created by J.W. Schultz of Pegasystems Technologies.
268: .SH BUGS AND ISSUES
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to pool_alloc.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / rsync / lib