Annotation of embedaddon/rsync/lib/pool_alloc.3, revision 1.1.1.1
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:
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, 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.
98: If
99: .B POOL_QALIGN
100: is set in the
101: .IR flags ,
102: allocations will be aligned to addresses that are a
103: multiple of
104: .IR quantum .
105: If
106: .B POOL_CLEAR
107: is set in the
108: .IR flags ,
109: all allocations from the pool will be initialized to zeros.
110: You may specify a
111: .B NULL
112: for the
113: .I bomb
114: function pointer if you don't wish to use it. (See the
115: .B pool_alloc()
116: function for how it is used.)
117: .P
118: .B pool_destroy()
119: destroys an allocation
120: .I pool
121: and frees all its associated memory.
122: .P
123: .B pool_alloc()
124: allocates
125: .I size
126: bytes from the specified
127: .IR pool .
128: If
129: .I size
130: is
131: .BR 0 ,
132: .I quantum
133: bytes will be allocated.
134: If the pool has been created with
135: .BR POOL_QALIGN ,
136: every chunk of memory that is returned will be suitably aligned.
137: You can use this with the default
138: .I quantum
139: size to ensure that all memory can store a variable of any type.
140: If the requested memory cannot be allocated, the
141: .I bomb()
142: function will be called with
143: .I msg
144: as its sole argument (if the function was defined at the time
145: the pool was created), and then a
146: .B NULL
147: address is returned (assuming that the bomb function didn't exit).
148: .P
149: .B pool_free()
150: frees
151: .I size
152: bytes pointed to by an
153: .I addr
154: that was previously allocated in the specified
155: .IR pool .
156: If
157: .I size
158: is
159: .BR 0 ,
160: .I quantum
161: bytes will be freed.
162: The memory freed within an extent will not be reusable until
163: all of the memory in that extent has been freed with one
164: exception: the most recent pool allocation may be freed back
165: into the pool prior to making any further allocations.
166: If enough free calls are made to indicate that an extent has no
167: remaining allocated objects (as computed by the total freed size for
168: an extent), its memory will be completely freed back to the system.
169: If
170: .I addr
171: is
172: .BR 0 ,
173: no memory will be freed, but subsequent allocations will come
174: from a new extent.
175: .P
176: .B pool_free_old()
177: takes a boundary
178: .I addr
179: value that was returned by
180: .B pool_boundary()
181: and frees up any extents in the
182: .I pool
183: that have data allocated from that point backward in time.
184: NOTE: you must NOT mix calls to both
185: .B pool_free
186: and
187: .B pool_free_old
188: on the same pool!
189: .P
190: .B pool_boundary()
191: asks for a boundary value that can be sent to
192: .B pool_free_old()
193: at a later time to free up all memory allocated prior to a particular
194: moment in time.
195: If the extent that holds the boundary point has allocations from after the
196: boundary point, it will not be freed until a future
197: .B pool_free_old()
198: call encompasses the entirety of the extent's data.
199: If
200: .I len
201: is non-zero, the call will also check if the active extent has at least
202: that much free memory available in it, and if not, it will mark the
203: extent as inactive, forcing a new extent to be used for future allocations.
204: (You can specify -1 for
205: .I len
206: if you want to force a new extent to start.)
207: .P
208: .B pool_talloc()
209: is a macro that takes a
210: .I type
211: and a
212: .I count
213: instead of a
214: .IR size .
215: It casts the return value to the correct pointer type.
216: .P
217: .B pool_tfree
218: is a macro that calls
219: .B pool_free
220: on memory that was allocated by
221: .BR pool_talloc() .
222: .SH RETURN VALUE
223: .B pool_create()
224: returns a pointer to
225: .BR "struct alloc_pool" .
226: .P
227: .B pool_alloc()
228: and
229: .B pool_talloc()
230: return pointers to the allocated memory,
231: or NULL if the request fails.
232: The return type of
233: .B pool_alloc()
234: will normally require casting to the desired type but
235: .B pool_talloc()
236: will returns a pointer of the requested
237: .IR type .
238: .P
239: .B pool_boundary()
240: returns a pointer that should only be used in a call to
241: .BR pool_free_old() .
242: .P
243: .BR pool_free() ,
244: .BR pool_free_old() ,
245: .B pool_tfree()
246: and
247: .B pool_destroy()
248: return no value.
249: .SH SEE ALSO
250: .nf
251: malloc(3)
252: .SH AUTHOR
253: pool_alloc was created by J.W. Schultz of Pegasystems Technologies.
254: .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