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

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for efficient small-block allocation
   4 .\"
   5 .\" (c) 1999, 2001, 2003, 2005, 2007, 2009, 2023, 2024 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the mLib utilities library.
  11 .\"
  12 .\" mLib is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU Library General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or (at
  15 .\" your option) any later version.
  16 .\"
  17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  20 .\" License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with mLib.  If not, write to the Free Software
  24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25 .\" USA.
  26 .
  27 .\"--------------------------------------------------------------------------
  28 .so ../defs.man \" @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH sub 3mLib "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @subarena_create
  33 .\" @subarena_destroy
  34 .\" @subarena_alloc
  35 .\" @subarena_free
  36 .\" @sub_alloc
  37 .\" @sub_free
  38 .\" @sub_init
  39 .
  40 .\" @A_CREATE
  41 .\" @A_DESTROY
  42 .\" @A_SUBNEW
  43 .\" @CREATE
  44 .\" @DESTROY
  45 .\" @NEW
  46 .
  47 .\"--------------------------------------------------------------------------
  48 .SH NAME
  49 sub \- efficient allocation and freeing of small blocks
  50 .
  51 .\"--------------------------------------------------------------------------
  52 .SH SYNOPSIS
  53 .
  54 .nf
  55 .B "#include <mLib/sub.h>"
  56 .PP
  57 .B "typedef struct { ...\& } subarena;"
  58 .PP
  59 .BI "void subarena_create(subarena *" s ", arena *" a );
  60 .BI "void subarena_destroy(subarena *" s );
  61 .BI "void subarena_alloc(subarena *" s ", size_t " sz );
  62 .BI "void *A_CREATE(subarena *" s ", " type );
  63 .BI "A_SUBNEW(" type "* " p ", subarena *" s );
  64 .BI "void subarena_free(subarena *" s ", void *" p ", size_t " sz );
  65 .BI "void A_DESTROY(subarena *" s ", " type " *" p );
  66 .PP
  67 .B "void sub_init(void);"
  68 .BI "void *sub_alloc(size_t " sz );
  69 .BI "void *CREATE(" type );
  70 .BI "NEW(" type "* " p );
  71 .BI "void sub_free(void *" p ", size_t " sz );
  72 .BI "void DESTROY(" type " *" p );
  73 .fi
  74 .
  75 .\"--------------------------------------------------------------------------
  76 .SH DESCRIPTION
  77 .
  78 The
  79 .B subarena
  80 collection of functions and macros implement an efficient allocator for
  81 small blocks of known sizes, constructed from a general allocator
  82 implemented by an
  83 .BR arena (3).
  84 Free blocks of the same size are linked together in list, making freeing
  85 and allocation fast.  The `free' operation requires the block size as an
  86 argument, so there's no data overhead for an allocated block.  The
  87 system takes advantage of this by allocating big chunks from the
  88 underlying arena and splitting the chunks into smaller blocks of the
  89 right size, so the space and time overhead from the underlying allocator
  90 is divided over many blocks.
  91 .PP
  92 Calling
  93 .B subarena_alloc
  94 allocates a block of
  95 .I sz
  96 bytes from the subarena
  97 .IR s .
  98 If there isn't enough memory to allocate the block, the
  99 exception
 100 .B EXC_NOMEM
 101 is raised.
 102 .PP
 103 The
 104 .B subarena_free
 105 function frees a block allocated by
 106 .B subarena_alloc
 107 from the same subarena.  You must know the size of the block in advance.
 108 Note that
 109 .B subarena_free
 110 never gives memory back to the underlying allocator.  Free sub-blocks
 111 are just made available to later calls of
 112 .BR subarena_alloc .
 113 .PP
 114 Don't try to free blocks allocated by
 115 .B subarena_alloc
 116 to the underlying arena's
 117 .I free
 118 function, or to try freeing blocks obtained directly from the arena's
 119 .I alloc
 120 function using
 121 .BR subarena_free .
 122 If you do, you'll get what you deserve.
 123 .PP
 124 The macros
 125 .BR A_CREATE ,
 126 .BR A_SUBNEW ,
 127 and
 128 .B A_DESTROY
 129 are intended to provide a slightly more natural interface to
 130 allocation.  The call
 131 .VS
 132 mystruct *p = subarena_alloc(s, sizeof(mystruct));
 133 .VE
 134 can be replaced by
 135 .VS
 136 mystruct *p = A_CREATE(s, mystruct);
 137 .VE
 138 or
 139 .VS
 140 mystruct *p;
 141 A_SUBNEW(p, s);
 142 .VE
 143 Similarly, the block can be freed by saying
 144 .VS
 145 A_DESTROY(s, p)
 146 .VE
 147 rather than the more cumbersome
 148 .VS
 149 subarena_free(s, p, sizeof(*p));
 150 .VE
 151 There is a standard subarena
 152 .B sub_global
 153 which uses
 154 .B arena_global
 155 as its underlying allocator (obtained the first time the subarena is
 156 used).  The functions
 157 .B sub_alloc
 158 and
 159 .B sub_free
 160 and the macros
 161 .BI CREATE ,
 162 .BI NEW
 163 and
 164 .B DESTROY
 165 use this subarena.
 166 .PP
 167 The function
 168 .B sub_init
 169 ought to be called before any of the other functions as a matter of good
 170 taste, but actually the system will initialize itself the first time
 171 it's used.
 172 .
 173 .\"--------------------------------------------------------------------------
 174 .SH "SEE ALSO"
 175 .
 176 .BR arena (3),
 177 .BR exc (3),
 178 .BR alloc (3),
 179 .BR mLib (3).
 180 .
 181 .\"--------------------------------------------------------------------------
 182 .SH AUTHOR
 183 .
 184 Mark Wooding, <mdw@distorted.org.uk>
 185 .
 186 .\"----- That's all, folks --------------------------------------------------