3 poolalloc, poolfree, poolmsize, poolrealloc, poolcompact, poolcheck, poolblockcheck,
4 pooldump \- general memory management routines
13 void* poolalloc(Pool* pool, ulong size)
16 void poolfree(Pool* pool, void* ptr)
19 ulong poolmsize(Pool* pool, void* ptr)
22 void* poolrealloc(Pool* pool, void* ptr, ulong size)
25 void poolcompact(Pool* pool)
28 void poolcheck(Pool *pool)
31 void poolblockcheck(Pool *pool, void *ptr)
34 void pooldump(Pool *pool);
36 These routines provide a general memory management facility.
37 Memory is retrieved from a coarser allocator (e.g.
41 and then allocated to callers.
42 The routines are locked and thus may safely be used in
43 multiprocess programs.
46 attempts to allocate a block of size
48 it returns a pointer to the block when successful and nil otherwise.
51 returns a non-nil pointer.
53 returns an allocated block to the pool.
54 It is an error to free a block more than once or to free a
55 pointer not returned by
59 is legal and is a no-op.
63 bytes the block associated with
65 which must have been previously returned by
69 If the block's size can be adjusted, a (possibly different) pointer to the new block is returned.
70 The contents up to the lesser of the old and new sizes are unchanged.
71 After a successful call to
73 the return value should be used rather than
76 If the request cannot be satisfied,
78 returns nil, and the old pointer remains valid.
80 When blocks are allocated, there is often some extra space left at the end
81 that would usually go unused.
83 grows the block to encompass this extra space and returns the new size.
89 routines validate a single allocated block or the entire pool, respectively.
93 if corruption is detected.
95 prints a summary line for every block in the
102 structure itself provides much of the setup interface.
105 .ta \w'\fL 'u +\w'\fLulong 'u +\w'\fLlastcompact; 'u
106 typedef struct Pool Pool;
109 ulong maxsize; /* of entire Pool */
110 ulong cursize; /* of Pool */
111 ulong curfree; /* total free bytes in Pool */
112 ulong curalloc; /* total allocated bytes in Pool */
113 ulong minarena; /* smallest size of new arena */
114 ulong quantum; /* allocated blocks should be multiple of */
115 ulong minblock; /* smallest newly allocated block */
117 int nfree; /* number of calls to free */
118 int lastcompact; /* nfree at time of last poolcompact */
119 void* (*alloc)(ulong);
120 int (*merge)(void*, void*);
121 void (*move)(void* from, void* to);
123 void (*unlock)(Pool*);
124 void (*print)(Pool*, char*, ...);
125 void (*panic)(Pool*, char*, ...);
126 void (*logstack)(Pool*);
129 .ta \w'\fL 'u +\w'POOL_ANTAGONISM 'u
131 POOL_ANTAGONISM = 1<<0,
132 POOL_PARANOIA = 1<<1,
133 POOL_VERBOSITY = 1<<2,
134 POOL_DEBUGGING = 1<<3,
136 POOL_TOLERANCE = 1<<5,
141 The pool obtains arenas of memory to manage by calling the the given
144 The total number of requested bytes will not exceed
146 Each allocation request will be for at least
150 When a new arena is allocated, the pool routines try to
151 merge it with the surrounding arenas, in an attempt to combat fragmentation.
154 is non-nil, it is called with the addresses of two blocks from
156 that the pool routines suspect might be adjacent.
157 If they are not mergeable,
160 If they are mergeable,
162 should merge them into one block in its own bookkeeping
165 To ease fragmentation and make
166 block reuse easier, the sizes requested of the pool routines are rounded up to a multiple of
169 the carrying out requests.
170 If, after rounding, the block size is still less than
174 will be used as the block size.
177 defragments the pool, moving blocks in order to aggregate
179 Each time it moves a block, it notifies the
181 routine that the contents have moved.
184 is called, the contents have already moved,
187 should never be dereferenced.
190 routine is supplied (i.e. it is nil), then calling
194 When the pool routines need to allocate a new arena but cannot,
197 has returned nil or because doing so would use more than
201 is called once to defragment the memory
202 and the request is retried.
205 are protected by the pool routines calling
208 before modifying the pool, and
213 When internal corruption is detected,
217 style argument that specifies what happened.
221 When the pool routines wish to convey a message
222 to the caller (usually because logging is turned on; see below),
224 is called, also with a
229 is a bit vector that tweaks the behavior of the pool routines
231 Most are useful for debugging in one way or another.
236 fills blocks with non-zero garbage before releasing them to the user,
239 fills the blocks on receipt.
240 This tickles both user programs and the innards of the allocator.
241 Specifically, each 32-bit word of the memory is marked with a pointer value exclusive-or'ed
243 The pointer value is the pointer to the beginning of the allocated block
244 and the constant varies in order to distinguish different markings.
245 Freed blocks use the constant
247 newly allocated blocks
249 and newly created unallocated blocks
255 returns a block starting at
257 each word of the block will contain the value
259 Recognizing these numbers in memory-related crashes can
260 help diagnose things like double-frees or dangling pointers.
264 causes the allocator to walk the entire pool whenever locking or unlocking itself,
265 looking for corruption.
266 This slows runtime by a few orders of magnitude
267 when many blocks are in use.
271 the entire pool structure is printed
274 each time the pool is locked or unlocked.
278 whose format is unspecified and volatile.
279 It should not be used by most programs.
282 is set, a single line is printed via
284 at the beginning and end of each pool call.
288 it will be called as well.
289 This provides a mechanism for external programs to search for leaks.
292 for one such program.)
294 The pool routines are strict about the amount of space callers use.
295 If even a single byte is written past the end of the allotted space of a block, they
296 will notice when that block is next used in a call to
300 (or at the next entry into the allocator, when
306 Since forgetting to allocate space for the
307 terminating NUL on strings is such a common error,
310 is set and a single NUL is found written past the end of a block,
312 will be called with a notification, but
320 fills the passed block with garbage rather than
321 return it to the free pool.
323 .B /usr/local/plan9/src/libc/port/pool.c
328 .B /usr/local/plan9/src/libc/port/malloc.c
329 is a complete example.
