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

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for configurable memory management
   4 .\"
   5 .\" (c) 2000, 2001, 2005, 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 arena 3mLib "3 June 2000" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @arena_global
  33 .\" @arena_stdlib
  34 .
  35 .\" @arena_fakemalloc
  36 .
  37 .\" @ALLOCV_SAFE_P
  38 .\" @NEWV_SAFE_P
  39 .
  40 .\" @A_ALLOC
  41 .\" @A_ALLOCV
  42 .\" @A_NEW
  43 .\" @A_NEWV
  44 .\" @A_REALLOC
  45 .\" @A_RENEWV
  46 .\" @A_FREE
  47 .
  48 .\" @a_alloc
  49 .\" @a_allocv
  50 .\" @a_realloc
  51 .\" @a_reallocv
  52 .\" @a_free
  53 .
  54 .\"--------------------------------------------------------------------------
  55 .SH "NAME"
  56 arena \- control of memory allocation
  57 .
  58 .\"--------------------------------------------------------------------------
  59 .SH "SYNOPSIS"
  60 .
  61 .nf
  62 .B "#include <mLib/arena.h>"
  63 .PP
  64 .ta 2n
  65 .B "typedef struct {"
  66 .B "    const struct arena_ops *ops";
  67 .B "} arena;"
  68 .PP
  69 .B "typedef struct {"
  70 .BI "   void *(*alloc)(arena *" a ", size_t " sz );
  71 .BI "   void *(*realloc)(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
  72 .BI "   void *(*free)(arena *" a ", void *" p );
  73 .BI "   void *(*purge)(arena *" a );
  74 .B "} arena_ops;"
  75 .PP
  76 .BI "arena *arena_global;"
  77 .BI "arena arena_stdlib;"
  78 .PP
  79 .ta \w'\fBvoid *arena_fakerealloc('u
  80 .BI "void *arena_fakerealloc(arena *" a ", void *" p ,
  81 .BI "   size_t " sz ", size_t " osz );
  82 .PP
  83 .BI "int ALLOCV_SAFE_P(size_t " n ", size_t " sz );
  84 .BI "int NEWV_SAFE_P(" type " *" p ", size_t " n );
  85 .PP
  86 .BI "void *a_alloc(arena *" a ", size_t " sz );
  87 .BI "void *a_allocv(arena *" a ", size_t " n ", size_t " sz );
  88 .BI "void *a_realloc(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
  89 .ta \w'\fBvoid a_reallocv('u
  90 .BI "void *a_reallocv(arena *" a ", void *" p ,
  91 .BI "   size_t " n ", size_t " on ", size_t " sz );
  92 .BI "void a_free(arena *" a );
  93 .PP
  94 .BI "void *A_ALLOC(arena *" a ", size_t " sz );
  95 .BI "void *A_ALLOCV(arena *" a ", size_t " n ", size_t " sz );
  96 .BI "void A_NEW(" type " *" p ", arena *" a );
  97 .BI "void A_NEWV(" type " *" p ", arena *" a ", size_t " n );
  98 .BI "void *A_REALLOC(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
  99 .ta \w'\fBvoid A_REALLOCV('u
 100 .BI "void *A_REALLOCV(arena *" a ", void *" p ,
 101 .BI "   size_t " n ", size_t " on ", size_t " sz );
 102 .ta \w'\fBvoid A_RENEWV('u
 103 .BI "void A_RENEWV(" type " *" q ", " type " *" p ", arena *" a ,
 104 .BI "   size_t " n ", size_t " on ", size_t " sz );
 105 .BI "void A_FREE(arena *" a );
 106 .fi
 107 .
 108 .\"--------------------------------------------------------------------------
 109 .SH "DESCRIPTION"
 110 .
 111 An
 112 .I arena
 113 is a place from which blocks of memory may be allocated and freed.  The
 114 basic
 115 .B mLib
 116 library provides a single standard arena,
 117 .BR arena_stdlib ,
 118 which uses the usual
 119 .BR malloc (3)
 120 and
 121 .BR free (3)
 122 calls.  The global variable
 123 .B arena_global
 124 is a pointer to a `current' arena, which is a good choice to use if
 125 you can't think of anything better.
 126 .PP
 127 The macros
 128 .BR A_ALLOC ,
 129 .B A_REALLOC
 130 and
 131 .B A_FREE
 132 behave like the standard C functions
 133 .BR malloc (3),
 134 .BR realloc (3)
 135 and
 136 .BR free (3),
 137 allocating, resizing and releasing blocks from a given arena.  There are
 138 function-call equivalents with lower-case names too.  For a more
 139 convenient interface to memory allocation, see
 140 .BR alloc (3).
 141 .PP
 142 .B Note:
 143 The
 144 .B realloc
 145 function has an extra argument
 146 .I osz
 147 specifying the old size of the block.  This is for the benefit of arena
 148 handlers which can't easily find the old block's size.
 149 .PP
 150 The macro
 151 .B ALLOCV_SAFE_P
 152 returns nonzero if the product
 153 .IR n "\ \*(mu\ " sz
 154 is representable in type
 155 .B size_t
 156 and zero otherwise;
 157 i.e., it returns true if it would be safe to try to allocate
 158 .IR n "\ \*(mu\ " sz
 159 bytes.
 160 The macro
 161 .BR A_ALLOCV
 162 allocates space for an array of
 163 .I n
 164 elements each of size
 165 .IR sz ,
 166 somewhat like
 167 .BR calloc (3),
 168 except that
 169 .B A_ALLOCV
 170 does not clear the allocated memory.
 171 Likewise, the macro
 172 .B A_REALLOCV
 173 resizes the block pointed to by
 174 .IR p ,
 175 which previously had space for
 176 .I on
 177 elements of size
 178 .IR sz ,
 179 so that it now has enough space for
 180 .I n
 181 elements,
 182 returning the new block address.
 183 There are also function-call equivalents of these macros.
 184 .PP
 185 Finally, the macro
 186 .B A_NEW
 187 sets its argument
 188 .I p
 189 to point to a freshly allocated block of memory
 190 large enough for the type that
 191 .I p
 192 points to,
 193 or to null if allocation failed.
 194 The macro
 195 .B A_NEWV
 196 sets
 197 .I p
 198 to point to memory large enough for
 199 .I n
 200 elements, each of the type that
 201 .I p
 202 points to.
 203 The macro
 204 .B A_RENEWV
 205 sets
 206 .I q
 207 to point to memory large enough for
 208 .I n
 209 elements, each of the type that
 210 .I p
 211 points to.
 212 .
 213 .SS "Defining new arenas"
 214 An
 215 .B arena
 216 is a structure containing a single member,
 217 .BR ops ,
 218 which is a pointer to a structure of type
 219 .BR arena_ops .
 220 The
 221 .B arena
 222 structure may be followed in memory by data which is used by the arena's
 223 manager to maintain its state.
 224 .PP
 225 The
 226 .B arena_ops
 227 table contains function pointers which are called to perform various
 228 memory allocation tasks:
 229 .TP
 230 .BI "void *(*alloc)(arena *" a ", size_t " sz );
 231 Allocates a block of memory, of at least
 232 .I sz
 233 bytes in size, appropriately aligned, and returns its address.
 234 .nf
 235 .TP
 236 .BI "void *(*realloc)(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
 237 .fi
 238 Resizes the block pointed to by
 239 .IR p ,
 240 with
 241 .I osz
 242 interesting bytes in it,
 243 so that it is at least
 244 .I sz
 245 bytes long.  You can use
 246 .B arena_fakerealloc
 247 here, to fake resizing by allocating, copying and freeing, if your arena
 248 doesn't make doing something more efficient easy.
 249 .TP
 250 .BI "void (*free)(arena *" a ", void *" p );
 251 Frees the block pointed to by
 252 .IR p .
 253 .TP
 254 .BI "void (*purge)(arena *" a );
 255 Frees all blocks in the arena.  Used when the arena is being destroyed.
 256 .PP
 257 The behaviour of the
 258 .IR alloc ,
 259 .I realloc
 260 and
 261 .I free
 262 calls with respect to null pointers and zero-sized blocks is as
 263 specified by the ANSI C standard.
 264 .
 265 .\"--------------------------------------------------------------------------
 266 .SH "SEE ALSO"
 267 .
 268 .BR alloc (3),
 269 .BR mLib (3).
 270 .
 271 .\"--------------------------------------------------------------------------
 272 .SH AUTHOR
 273 .
 274 Mark Wooding, <mdw@distorted.org.uk>
 275 .
 276 .\"----- That's all, folks --------------------------------------------------