3 poolalloc, poolallocalign, poolfree, poolmsize, 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 void* poolrealloc(Pool* pool, void* ptr, ulong size)
31 void poolcompact(Pool* pool)
34 void poolcheck(Pool *pool)
37 void poolblockcheck(Pool *pool, void *ptr)
40 void pooldump(Pool *pool);
42 These routines provide a general memory management facility.
43 Memory is retrieved from a coarser allocator (e.g.
47 and then allocated to callers.
48 The routines are locked and thus may safely be used in
49 multiprocess programs.
52 attempts to allocate a block of size
54 it returns a pointer to the block when successful and nil otherwise.
57 returns a non-nil pointer.
59 returns an allocated block to the pool.
60 It is an error to free a block more than once or to free a
61 pointer not returned by
65 is legal and is a no-op.
68 attempts to allocate a block of size
70 with the given alignment constraints.
74 the returned pointer is aligned to be equal to
83 byte block allocated will not span a
90 bytes the block associated with
92 which must have been previously returned by
96 If the block's size can be adjusted, a (possibly different) pointer to the new block is returned.
97 The contents up to the lesser of the old and new sizes are unchanged.
98 After a successful call to
100 the return value should be used rather than
103 If the request cannot be satisfied,
105 returns nil, and the old pointer remains valid.
107 When blocks are allocated, there is often some extra space left at the end
108 that would usually go unused.
110 grows the block to encompass this extra space and returns the new size.
116 routines validate a single allocated block or the entire pool, respectively.
120 if corruption is detected.
122 prints a summary line for every block in the
125 function (see below).
129 structure itself provides much of the setup interface.
132 .ta \w'\fL 'u +\w'\fLulong 'u +\w'\fLlastcompact; 'u
133 typedef struct Pool Pool;
136 uintptr maxsize; /* of entire Pool */
137 uintptr cursize; /* of Pool */
138 uintptr curfree; /* total free bytes in Pool */
139 uintptr curalloc; /* total allocated bytes in Pool */
140 ulong minarena; /* smallest size of new arena */
141 ulong quantum; /* allocated blocks should be multiple of */
142 ulong minblock; /* smallest newly allocated block */
144 int nfree; /* number of calls to free */
145 int lastcompact; /* nfree at time of last poolcompact */
146 void* (*alloc)(ulong);
147 int (*merge)(void*, void*);
148 void (*move)(void* from, void* to);
150 void (*unlock)(Pool*);
151 void (*print)(Pool*, char*, ...);
152 void (*panic)(Pool*, char*, ...);
153 void (*logstack)(Pool*);
156 .ta \w'\fL 'u +\w'POOL_ANTAGONISM 'u
158 POOL_ANTAGONISM = 1<<0,
159 POOL_PARANOIA = 1<<1,
160 POOL_VERBOSITY = 1<<2,
161 POOL_DEBUGGING = 1<<3,
163 POOL_TOLERANCE = 1<<5,
168 The pool obtains arenas of memory to manage by calling the the given
171 The total number of requested bytes will not exceed
173 Each allocation request will be for at least
177 When a new arena is allocated, the pool routines try to
178 merge it with the surrounding arenas, in an attempt to combat fragmentation.
181 is non-nil, it is called with the addresses of two blocks from
183 that the pool routines suspect might be adjacent.
184 If they are not mergeable,
187 If they are mergeable,
189 should merge them into one block in its own bookkeeping
192 To ease fragmentation and make
193 block reuse easier, the sizes requested of the pool routines are rounded up to a multiple of
196 the carrying out requests.
197 If, after rounding, the block size is still less than
201 will be used as the block size.
204 defragments the pool, moving blocks in order to aggregate
206 Each time it moves a block, it notifies the
208 routine that the contents have moved.
211 is called, the contents have already moved,
214 should never be dereferenced.
217 routine is supplied (i.e. it is nil), then calling
221 When the pool routines need to allocate a new arena but cannot,
224 has returned nil or because doing so would use more than
228 is called once to defragment the memory
229 and the request is retried.
232 are protected by the pool routines calling
235 before modifying the pool, and
240 When internal corruption is detected,
244 style argument that specifies what happened.
248 When the pool routines wish to convey a message
249 to the caller (usually because logging is turned on; see below),
251 is called, also with a
256 is a bit vector that tweaks the behavior of the pool routines
258 Most are useful for debugging in one way or another.
263 fills blocks with non-zero garbage before releasing them to the user,
266 fills the blocks on receipt.
267 This tickles both user programs and the innards of the allocator.
268 Specifically, each 32-bit word of the memory is marked with a pointer value exclusive-or'ed
270 The pointer value is the pointer to the beginning of the allocated block
271 and the constant varies in order to distinguish different markings.
272 Freed blocks use the constant
274 newly allocated blocks
276 and newly created unallocated blocks
282 returns a block starting at
284 each word of the block will contain the value
286 Recognizing these numbers in memory-related crashes can
287 help diagnose things like double-frees or dangling pointers.
291 causes the allocator to walk the entire pool whenever locking or unlocking itself,
292 looking for corruption.
293 This slows runtime by a few orders of magnitude
294 when many blocks are in use.
298 the entire pool structure is printed
301 each time the pool is locked or unlocked.
305 whose format is unspecified and volatile.
306 It should not be used by most programs.
309 is set, a single line is printed via
311 at the beginning and end of each pool call.
315 it will be called as well.
316 This provides a mechanism for external programs to search for leaks.
319 for one such program.)
321 The pool routines are strict about the amount of space callers use.
322 If even a single byte is written past the end of the allotted space of a block, they
323 will notice when that block is next used in a call to
327 (or at the next entry into the allocator, when
333 Since forgetting to allocate space for the
334 terminating NUL on strings is such a common error,
337 is set and a single NUL is found written past the end of a block,
339 will be called with a notification, but
347 fills the passed block with garbage rather than
348 return it to the free pool.
350 .B /sys/src/libc/port/pool.c
355 .B /sys/src/libc/port/malloc.c
356 is a complete example.