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 .\" @CREATE
  43 .\" @DESTROY
  44 .
  45 .\"--------------------------------------------------------------------------
  46 .SH NAME
  47 sub \- efficient allocation and freeing of small blocks
  48 .
  49 .\"--------------------------------------------------------------------------
  50 .SH SYNOPSIS
  51 .
  52 .nf
  53 .B "#include <mLib/sub.h>"
  54 .PP
  55 .B "typedef struct { ...\& } subarena;"
  56 .PP
  57 .BI "void subarena_create(subarena *" s ", arena *" a );
  58 .BI "void subarena_destroy(subarena *" s );
  59 .BI "void subarena_alloc(subarena *" s ", size_t " sz );
  60 .BI "void subarena_free(subarena *" s ", void *" p ", size_t " sz );
  61 .PP
  62 .B "void sub_init(void);"
  63 .BI "void *sub_alloc(size_t " sz );
  64 .BI "void sub_free(void *" p ", size_t " sz );
  65 .PP
  66 .BI "void *A_CREATE(subarena *" s ", " type );
  67 .BI "void A_DESTROY(subarena *" s ", " type " *" p );
  68 .BI "void *CREATE(" type );
  69 .BI "void DESTROY(" type " *" p );
  70 .fi
  71 .
  72 .\"--------------------------------------------------------------------------
  73 .SH DESCRIPTION
  74 .
  75 The
  76 .B subarena
  77 collection of functions and macros implement an efficient allocator for
  78 small blocks of known sizes, constructed from a general allocator
  79 implemented by an
  80 .BR arena (3).
  81 Free blocks of the same size are linked together in list, making freeing
  82 and allocation fast.  The `free' operation requires the block size as an
  83 argument, so there's no data overhead for an allocated block.  The
  84 system takes advantage of this by allocating big chunks from the
  85 underlying arena and splitting the chunks into smaller blocks of the
  86 right size, so the space and time overhead from the underlying allocator
  87 is divided over many blocks.
  88 .PP
  89 Calling
  90 .B subarena_alloc
  91 allocates a block of
  92 .I sz
  93 bytes from the subarena
  94 .IR s .
  95 If there isn't enough memory to allocate the block, the
  96 exception
  97 .B EXC_NOMEM
  98 is raised.
  99 .PP
 100 The
 101 .B subarena_free
 102 function frees a block allocated by
 103 .B subarena_alloc
 104 from the same subarena.  You must know the size of the block in advance.
 105 Note that
 106 .B subarena_free
 107 never gives memory back to the underlying allocator.  Free sub-blocks
 108 are just made available to later calls of
 109 .BR subarena_alloc .
 110 .PP
 111 Don't try to free blocks allocated by
 112 .B subarena_alloc
 113 to the underlying arena's
 114 .I free
 115 function, or to try freeing blocks obtained directly from the arena's
 116 .I alloc
 117 function using
 118 .BR subarena_free .
 119 If you do, you'll get what you deserve.
 120 .PP
 121 The pair of macros
 122 .B A_CREATE
 123 and
 124 .B A_DESTROY
 125 are intended to provide a slightly more natural interface to
 126 allocation.  The call
 127 .VS
 128 mystruct *p = subarena_alloc(s, sizeof(mystruct));
 129 .VE
 130 can be replaced by
 131 .VS
 132 mystruct p = A_CREATE(s, mystruct);
 133 .VE
 134 Similarly, the block can be freed by saying
 135 .VS
 136 A_DESTROY(s, p)
 137 .VE
 138 rather than the more cumbersome
 139 .VS
 140 subarena_free(s, p, sizeof(*p));
 141 .VE
 142 There is a standard subarena
 143 .B sub_global
 144 which uses
 145 .B arena_global
 146 as its underlying allocator (obtained the first time the subarena is
 147 used).  The functions
 148 .B sub_alloc
 149 and
 150 .B sub_free
 151 and the macros
 152 .B CREATE
 153 and
 154 .B DESTROY
 155 use this subarena.
 156 .PP
 157 The function
 158 .B sub_init
 159 ought to be called before any of the other functions as a matter of good
 160 taste, but actually the system will initialize itself the first time
 161 it's used.
 162 .
 163 .\"--------------------------------------------------------------------------
 164 .SH "SEE ALSO"
 165 .
 166 .BR arena (3),
 167 .BR exc (3),
 168 .BR alloc (3),
 169 .BR mLib (3).
 170 .
 171 .\"--------------------------------------------------------------------------
 172 .SH AUTHOR
 173 .
 174 Mark Wooding, <mdw@distorted.org.uk>
 175 .
 176 .\"----- That's all, folks --------------------------------------------------