sys/man/2/pool

   1 .TH POOL 2
   2 .SH NAME
   3 poolalloc, poolallocalign, poolfree, poolmsize, poolisoverlap, poolrealloc, poolcompact, poolcheck, poolblockcheck,
   4 pooldump \- general memory management routines
   5 .SH SYNOPSIS
   6 .B #include <u.h>
   7 .br
   8 .B #include <libc.h>
   9 .br
  10 .B #include <pool.h>
  11 .PP
  12 .B
  13 void*   poolalloc(Pool* pool, ulong size)
  14 .PP
  15 .B
  16 void*   poolallocalign(Pool *pool, ulong size,
  17 .br
  18 .B
  19                 ulong align, long offset, ulong span)
  20 .PP
  21 .B
  22 void    poolfree(Pool* pool, void* ptr)
  23 .PP
  24 .B
  25 ulong   poolmsize(Pool* pool, void* ptr)
  26 .PP
  27 .B
  28 int     poolisoverlap(Pool* pool, void* ptr, ulong len)
  29 .PP
  30 .B
  31 void*   poolrealloc(Pool* pool, void* ptr, ulong size)
  32 .PP
  33 .B
  34 int     poolcompact(Pool* pool)
  35 .PP
  36 .B
  37 void    poolcheck(Pool *pool)
  38 .PP
  39 .B
  40 void    poolblockcheck(Pool *pool, void *ptr)
  41 .PP
  42 .B
  43 void    pooldump(Pool *pool);
  44 .SH DESCRIPTION
  45 These routines provide a general memory management facility.
  46 Memory is retrieved from a coarser allocator (e.g.
  47 .I sbrk
  48 or the kernel's
  49 .IR xalloc )
  50 and then allocated to callers.
  51 The routines are locked and thus may safely be used in
  52 multiprocess programs.
  53 .PP
  54 .I Poolalloc
  55 attempts to allocate a block of size
  56 .BR size ;
  57 it returns a pointer to the block when successful and nil otherwise.
  58 The call
  59 .B "poolalloc(0)
  60 returns a non-nil pointer.
  61 .I Poolfree
  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
  65 .IR poolalloc .
  66 The call
  67 .B "poolfree(nil)
  68 is legal and is a no-op.
  69 .PP
  70 .I Poolallocalign
  71 attempts to allocate a block of size
  72 .B size
  73 with the given alignment constraints.
  74 If
  75 .I align
  76 is non-zero,
  77 the returned pointer is aligned to be equal to
  78 .I offset
  79 modulo
  80 .IR align .
  81 If
  82 .I span
  83 is non-zero,
  84 the
  85 .I n
  86 byte block allocated will not span a
  87 .IR span -byte
  88 boundary.
  89 .PP
  90 .I Poolrealloc
  91 attempts to resize to
  92 .B nsize
  93 bytes the block associated with
  94 .BR ptr ,
  95 which must have been previously returned by
  96 .I poolalloc
  97 or
  98 .IR poolrealloc .
  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
 102 .IR poolrealloc ,
 103 the return value should be used rather than
 104 .B ptr
 105 to access the block.
 106 If the request cannot be satisfied,
 107 .I poolrealloc
 108 returns nil, and the old pointer remains valid.
 109 .PP
 110 When blocks are allocated, there is often some extra space left at the end
 111 that would usually go unused.
 112 .IR Poolmsize
 113 grows the block to encompass this extra space and returns the new size.
 114 .PP
 115 .I Poolisoverlap
 116 checks if the byte span
 117 .BR [ptr , ptr + len)
 118 overlaps the arenas of the specified
 119 .BR pool ,
 120 returning non-zero when there is overlap or zero if none.
 121 .PP
 122 The
 123 .I poolblockcheck
 124 and
 125 .I poolcheck
 126 routines validate a single allocated block or the entire pool, respectively.
 127 They call
 128 .B panic
 129 (see below)
 130 if corruption is detected.
 131 .I Pooldump
 132 prints a summary line for every block in the
 133 pool, using the
 134 .B print
 135 function (see below).
 136 .PP
 137 The
 138 .B Pool
 139 structure itself provides much of the setup interface.
 140 .IP
 141 .EX
 142 .ta \w'\fL    'u +\w'\fLulong 'u +\w'\fLlastcompact;  'u
 143 typedef struct Pool Pool;
 144 struct Pool {
 145         char*   name;
 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 */
 153         int     flags;
 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);
 159         void    (*lock)(Pool*);
 160         void    (*unlock)(Pool*);
 161         void    (*print)(Pool*, char*, ...);
 162         void    (*panic)(Pool*, char*, ...);
 163         void    (*logstack)(Pool*);
 164         void*   private;
 165 };
 166 .ta \w'\fL    'u +\w'POOL_ANTAGONISM 'u
 167 enum {  /* flags */
 168         POOL_ANTAGONISM = 1<<0,
 169         POOL_PARANOIA   = 1<<1,
 170         POOL_VERBOSITY  = 1<<2,
 171         POOL_DEBUGGING  = 1<<3,
 172         POOL_LOGGING    = 1<<4,
 173         POOL_TOLERANCE  = 1<<5,
 174         POOL_NOREUSE    = 1<<6,
 175 };
 176 .EE
 177 .PP
 178 The pool obtains arenas of memory to manage by calling the given
 179 .B alloc
 180 routine.
 181 The total number of requested bytes will not exceed
 182 .BR maxsize .
 183 Each allocation request will be for at least
 184 .B minarena
 185 bytes.
 186 .PP
 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.
 189 If
 190 .B merge
 191 is non-nil, it is called with the addresses of two blocks from
 192 .B alloc
 193 that the pool routines suspect might be adjacent.
 194 If they are not mergeable,
 195 .B merge
 196 must return zero.
 197 If they are mergeable,
 198 .B merge
 199 should merge them into one block in its own bookkeeping
 200 and return non-zero.
 201 .PP
 202 To ease fragmentation and make
 203 block reuse easier, the sizes requested of the pool routines are rounded up to a multiple of
 204 .B quantum
 205 before
 206 the carrying out requests.
 207 If, after rounding, the block size is still less than
 208 .B minblock
 209 bytes,
 210 .B minblock
 211 will be used as the block size.
 212 .PP
 213 .I Poolcompact
 214 defragments the pool, moving blocks in order to aggregate
 215 the free space.
 216 Each time it moves a block, it notifies the
 217 .B move
 218 routine that the contents have moved.
 219 At the time that
 220 .B move
 221 is called, the contents have already moved,
 222 so
 223 .B from
 224 should never be dereferenced.
 225 If no
 226 .B move
 227 routine is supplied (i.e. it is nil), then calling
 228 .I poolcompact
 229 is a no-op.
 230 .PP
 231 When the pool routines need to allocate a new arena but cannot,
 232 either because
 233 .B alloc
 234 has returned nil or because doing so would use more than
 235 .B maxsize
 236 bytes,
 237 .I poolcompact
 238 is called once to defragment the memory
 239 and the request is retried.
 240 .PP
 241 .I Pools
 242 are protected by the pool routines calling
 243 .B lock
 244 (when non-nil)
 245 before modifying the pool, and
 246 calling
 247 .B unlock
 248 when finished.
 249 .PP
 250 When internal corruption is detected,
 251 .B panic
 252 is called with a
 253 .IR print (2)
 254 style argument that specifies what happened.
 255 It is assumed that
 256 .B panic
 257 never returns.
 258 When the pool routines wish to convey a message
 259 to the caller (usually because logging is turned on; see below),
 260 .B print
 261 is called, also with a
 262 .IR print (2)
 263 style argument.
 264 .PP
 265 .B Flags
 266 is a bit vector that tweaks the behavior of the pool routines
 267 in various ways.
 268 Most are useful for debugging in one way or another.
 269 When
 270 .B POOL_ANTAGONISM
 271 is set,
 272 .I poolalloc
 273 fills blocks with non-zero garbage before releasing them to the user,
 274 and
 275 .I poolfree
 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
 279 with a constant.
 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
 283 .BR 0xF7000000 ,
 284 newly allocated blocks
 285 .BR 0xF9000000 ,
 286 and newly created unallocated blocks
 287 .BR 0xF1000000 .
 288 For example, if
 289 .B POOL_ANTAGONISM
 290 is set and
 291 .I poolalloc
 292 returns a block starting at
 293 .BR 0x00012345 ,
 294 each word of the block will contain the value
 295 .BR 0xF90012345 .
 296 Recognizing these numbers in memory-related crashes can
 297 help diagnose things like double-frees or dangling pointers.
 298 .PP
 299 Setting
 300 .B POOL_PARANOIA
 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.
 305 If
 306 .B POOL_VERBOSITY
 307 is set,
 308 the entire pool structure is printed
 309 (via
 310 .BR print )
 311 each time the pool is locked or unlocked.
 312 .B POOL_DEBUGGING
 313 enables internal
 314 debugging output,
 315 whose format is unspecified and volatile.
 316 It should not be used by most programs.
 317 When
 318 .B POOL_LOGGING
 319 is set, a single line is printed via
 320 .B print
 321 at the beginning and end of each pool call.
 322 If
 323 .B logstack
 324 is not nil,
 325 it will be called as well.
 326 This provides a mechanism for external programs to search for leaks.
 327 (See
 328 .IR leak (1)
 329 for one such program.)
 330 .PP
 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
 334 .I poolrealloc
 335 or
 336 .I free
 337 (or at the next entry into the allocator, when
 338 .B POOL_PARANOIA
 339 is set),
 340 and
 341 .B panic
 342 will be called.
 343 Since forgetting to allocate space for the
 344 terminating NUL on strings is such a common error,
 345 if
 346 .B POOL_TOLERANCE
 347 is set and a single NUL is found written past the end of a block,
 348 .B print
 349 will be called with a notification, but
 350 .B panic
 351 will not be.
 352 .PP
 353 When
 354 .B POOL_NOREUSE
 355 is set,
 356 .B poolfree
 357 fills the passed block with garbage rather than
 358 return it to the free pool.
 359 .SH SOURCE
 360 .B /sys/src/libc/port/pool.c
 361 .SH SEE ALSO
 362 .IR malloc (2),
 363 .IR brk (2)
 364 .PP
 365 .B /sys/src/libc/port/malloc.c
 366 is a complete example.