chiark - git - mdw - mLib/blob - sub.3

   1 .\" -*-nroff-*-
   2 .de VS
   3 .sp 1
   4 .RS
   5 .nf
   6 .ft B
   7 ..
   8 .de VE
   9 .ft R
  10 .fi
  11 .RE
  12 .sp 1
  13 ..
  14 .TH sub 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
  15 .SH NAME
  16 sub \- efficient allocation and freeing of small blocks
  17 .\" @subarena_create
  18 .\" @subarena_destroy
  19 .\" @subarena_alloc
  20 .\" @subarena_free
  21 .\" @sub_alloc
  22 .\" @sub_free
  23 .\" @sub_init
  24 .\"
  25 .\" @A_CREATE
  26 .\" @A_DESTROY
  27 .\" @CREATE
  28 .\" @DESTROY
  29 .\"
  30 .SH SYNOPSIS
  31 .nf
  32 .B "#include <mLib/sub.h>"
  33
  34 .BI "void subarena_create(subarena *" s ", arena *" a );
  35 .BI "void subarena_destroy(subarena *" s );
  36 .BI "void subarena_alloc(subarena *" s ", size_t " sz );
  37 .BI "void subarena_free(subarena *" s ", void *" p ", size_t " sz );
  38
  39 .B "void sub_init(void);"
  40 .BI "void *sub_alloc(size_t " sz );
  41 .BI "void sub_free(void *" p ", size_t " sz );
  42
  43 .BI "void *A_CREATE(subarena *" s ", " type );
  44 .BI "void A_DESTROY(subarena *" s ", " type " *" p );
  45 .BI "void *CREATE(" type );
  46 .BI "void DESTROY(" type " *" p );
  47 .fi
  48 .SH DESCRIPTION
  49 The
  50 .B subarena
  51 collection of functions and macros implement an efficient allocator for
  52 small blocks of known sizes, constructed from a general allocator
  53 implemented by an
  54 .BR arena (3).
  55 Free blocks of the same size are linked together in list, making freeing
  56 and allocation fast.  The `free' operation requires the block size as an
  57 argument, so there's no data overhead for an allocated block.  The
  58 system takes advantage of this by allocating big chunks from the
  59 underlying arena and splitting the chunks into smaller blocks of the
  60 right size, so the space and time overhead from the underlying allocator
  61 is divided over many blocks.
  62 .PP
  63 Calling
  64 .B subarena_alloc
  65 allocates a block of
  66 .I sz
  67 bytes from the subarena
  68 .IR s .
  69 If there isn't enough memory to allocate the block, the
  70 exception
  71 .B EXC_NOMEM
  72 is raised.
  73 .PP
  74 The
  75 .B subarena_free
  76 function frees a block allocated by
  77 .B subarena_alloc
  78 from the same subarena.  You must know the size of the block in advance.
  79 Note that
  80 .B subarena_free
  81 never gives memory back to the underlying allocator.  Free sub-blocks
  82 are just made available to later calls of
  83 .BR subarena_alloc .
  84 .PP
  85 Don't try to free blocks allocated by
  86 .B subarena_alloc
  87 to the underlying arena's
  88 .I free
  89 function, or to try freeing blocks obtained directly from the arena's
  90 .I alloc
  91 function using
  92 .BR subarena_free .
  93 If you do, you'll get what you deserve.
  94 .PP
  95 The pair of macros
  96 .B A_CREATE
  97 and
  98 .B A_DESTROY
  99 are intended to provide a slightly more natural interface to
 100 allocation.  The call
 101 .VS
 102 mystruct *p = subarena_alloc(s, sizeof(mystruct));
 103 .VE
 104 can be replaced by
 105 .VS
 106 mystruct p = A_CREATE(s, mystruct);
 107 .VE
 108 Similarly, the block can be freed by saying
 109 .VS
 110 A_DESTROY(s, p)
 111 .VE
 112 rather than the more cumbersome
 113 .VS
 114 subarena_free(s, p, sizeof(*p));
 115 .VE
 116 There is a standard subarena
 117 .B sub_global
 118 which uses
 119 .B arena_global
 120 as its underlying allocator (obtained the first time the subarena is
 121 used).  The functions
 122 .B sub_alloc
 123 and
 124 .B sub_free
 125 and the macros
 126 .B CREATE
 127 and
 128 .B DESTROY
 129 use this subarena.
 130 .PP
 131 The function
 132 .B sub_init
 133 ought to be called before any of the other functions as a matter of good
 134 taste, but actually the system will initialize itself the first time
 135 it's used.
 136 .SH "SEE ALSO"
 137 .BR arena (3),
 138 .BR exc (3),
 139 .BR alloc (3),
 140 .BR mLib (3).
 141 .SH AUTHOR
 142 Mark Wooding, <mdw@distorted.org.uk>