3 poolalloc, poolallocalign, poolfree, poolmsize, poolisoverlap, poolrealloc, poolcompact, poolcheck, poolblockcheck,
4 pooldump \- general memory management routines
13 void* poolalloc(Pool* pool, ulong size)
16 void* poolallocalign(Pool *pool, ulong size,
19 ulong align, long offset, ulong span)
22 void poolfree(Pool* pool, void* ptr)
25 ulong poolmsize(Pool* pool, void* ptr)
28 int poolisoverlap(Pool* pool, void* ptr, ulong len)
31 void* poolrealloc(Pool* pool, void* ptr, ulong size)
34 void poolcompact(Pool* pool)
37 void poolcheck(Pool *pool)
40 void poolblockcheck(Pool *pool, void *ptr)
43 void pooldump(Pool *pool);
45 These routines provide a general memory management facility.
46 Memory is retrieved from a coarser allocator (e.g.
50 and then allocated to callers.
51 The routines are locked and thus may safely be used in
52 multiprocess programs.
55 attempts to allocate a block of size
57 it returns a pointer to the block when successful and nil otherwise.
60 returns a non-nil pointer.
62 returns an allocated block to the pool.
63 It is an error to free a block more than once or to free a
64 pointer not returned by
68 is legal and is a no-op.
71 attempts to allocate a block of size
73 with the given alignment constraints.
77 the returned pointer is aligned to be equal to
86 byte block allocated will not span a
93 bytes the block associated with
95 which must have been previously returned by
99 If the block's size can be adjusted, a (possibly different) pointer to the new block is returned.
100 The contents up to the lesser of the old and new sizes are unchanged.
101 After a successful call to
103 the return value should be used rather than
106 If the request cannot be satisfied,
108 returns nil, and the old pointer remains valid.
110 When blocks are allocated, there is often some extra space left at the end
111 that would usually go unused.
113 grows the block to encompass this extra space and returns the new size.
116 checks if the byte span
117 .BR [ptr , ptr + len)
118 overlaps the arenas of the specified
120 returning non-zero when there is overlap or zero if none.
126 routines validate a single allocated block or the entire pool, respectively.
130 if corruption is detected.
132 prints a summary line for every block in the
135 function (see below).
139 structure itself provides much of the setup interface.
142 .ta \w'\fL 'u +\w'\fLulong 'u +\w'\fLlastcompact; 'u
143 typedef struct Pool Pool;
146 uintptr maxsize; /* of entire Pool */
147 uintptr cursize; /* of Pool */
148 uintptr curfree; /* total free bytes in Pool */
149 uintptr curalloc; /* total allocated bytes in Pool */
150 ulong minarena; /* smallest size of new arena */
151 ulong quantum; /* allocated blocks should be multiple of */
152 ulong minblock; /* smallest newly allocated block */
154 int nfree; /* number of calls to free */
155 int lastcompact; /* nfree at time of last poolcompact */
156 void* (*alloc)(ulong);
157 int (*merge)(void*, void*);
158 void (*move)(void* from, void* to);
160 void (*unlock)(Pool*);
161 void (*print)(Pool*, char*, ...);
162 void (*panic)(Pool*, char*, ...);
163 void (*logstack)(Pool*);
166 .ta \w'\fL 'u +\w'POOL_ANTAGONISM 'u
168 POOL_ANTAGONISM = 1<<0,
169 POOL_PARANOIA = 1<<1,
170 POOL_VERBOSITY = 1<<2,
171 POOL_DEBUGGING = 1<<3,
173 POOL_TOLERANCE = 1<<5,
178 The pool obtains arenas of memory to manage by calling the given
181 The total number of requested bytes will not exceed
183 Each allocation request will be for at least
187 When a new arena is allocated, the pool routines try to
188 merge it with the surrounding arenas, in an attempt to combat fragmentation.
191 is non-nil, it is called with the addresses of two blocks from
193 that the pool routines suspect might be adjacent.
194 If they are not mergeable,
197 If they are mergeable,
199 should merge them into one block in its own bookkeeping
202 To ease fragmentation and make
203 block reuse easier, the sizes requested of the pool routines are rounded up to a multiple of
206 the carrying out requests.
207 If, after rounding, the block size is still less than
211 will be used as the block size.
214 defragments the pool, moving blocks in order to aggregate
216 Each time it moves a block, it notifies the
218 routine that the contents have moved.
221 is called, the contents have already moved,
224 should never be dereferenced.
227 routine is supplied (i.e. it is nil), then calling
231 When the pool routines need to allocate a new arena but cannot,
234 has returned nil or because doing so would use more than
238 is called once to defragment the memory
239 and the request is retried.
242 are protected by the pool routines calling
245 before modifying the pool, and
250 When internal corruption is detected,
254 style argument that specifies what happened.
258 When the pool routines wish to convey a message
259 to the caller (usually because logging is turned on; see below),
261 is called, also with a
266 is a bit vector that tweaks the behavior of the pool routines
268 Most are useful for debugging in one way or another.
273 fills blocks with non-zero garbage before releasing them to the user,
276 fills the blocks on receipt.
277 This tickles both user programs and the innards of the allocator.
278 Specifically, each 32-bit word of the memory is marked with a pointer value exclusive-or'ed
280 The pointer value is the pointer to the beginning of the allocated block
281 and the constant varies in order to distinguish different markings.
282 Freed blocks use the constant
284 newly allocated blocks
286 and newly created unallocated blocks
292 returns a block starting at
294 each word of the block will contain the value
296 Recognizing these numbers in memory-related crashes can
297 help diagnose things like double-frees or dangling pointers.
301 causes the allocator to walk the entire pool whenever locking or unlocking itself,
302 looking for corruption.
303 This slows runtime by a few orders of magnitude
304 when many blocks are in use.
308 the entire pool structure is printed
311 each time the pool is locked or unlocked.
315 whose format is unspecified and volatile.
316 It should not be used by most programs.
319 is set, a single line is printed via
321 at the beginning and end of each pool call.
325 it will be called as well.
326 This provides a mechanism for external programs to search for leaks.
329 for one such program.)
331 The pool routines are strict about the amount of space callers use.
332 If even a single byte is written past the end of the allotted space of a block, they
333 will notice when that block is next used in a call to
337 (or at the next entry into the allocator, when
343 Since forgetting to allocate space for the
344 terminating NUL on strings is such a common error,
347 is set and a single NUL is found written past the end of a block,
349 will be called with a notification, but
357 fills the passed block with garbage rather than
358 return it to the free pool.
360 .B /sys/src/libc/port/pool.c
365 .B /sys/src/libc/port/malloc.c
366 is a complete example.