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 .\" @arena_fakemalloc
  35 .\" @a_alloc
  36 .\" @a_realloc
  37 .\" @a_free
  38 .\" @A_ALLOC
  39 .\" @A_REALLOC
  40 .\" @A_FREE
  41 .
  42 .\"--------------------------------------------------------------------------
  43 .SH "NAME"
  44 arena \- control of memory allocation
  45 .
  46 .\"--------------------------------------------------------------------------
  47 .SH "SYNOPSIS"
  48 .
  49 .nf
  50 .B "#include <mLib/arena.h>"
  51 .PP
  52 .ta 2n
  53 .B "typedef struct {"
  54 .B "    const struct arena_ops *ops";
  55 .B "} arena;"
  56 .PP
  57 .B "typedef struct {"
  58 .BI "   void *(*alloc)(arena *" a ", size_t " sz );
  59 .BI "   void *(*realloc)(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
  60 .BI "   void *(*free)(arena *" a ", void *" p );
  61 .BI "   void *(*purge)(arena *" a );
  62 .B "} arena_ops;"
  63 .PP
  64 .BI "arena *arena_global;"
  65 .BI "arena arena_stdlib;"
  66 .PP
  67 .ta \w'\fBvoid *arena_fakerealloc('u
  68 .BI "void *arena_fakerealloc(arena *" a ", void *" p ,
  69 .BI "   size_t " sz ", size_t " osz );
  70 .PP
  71 .BI "void *a_alloc(arena *" a ", size_t " sz );
  72 .BI "void *a_realloc(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
  73 .BI "void a_free(arena *" a );
  74 .PP
  75 .BI "void *A_ALLOC(arena *" a ", size_t " sz );
  76 .BI "void *A_REALLOC(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
  77 .BI "void A_FREE(arena *" a );
  78 .fi
  79 .
  80 .\"--------------------------------------------------------------------------
  81 .SH "DESCRIPTION"
  82 .
  83 An
  84 .I arena
  85 is a place from which blocks of memory may be allocated and freed.  The
  86 basic
  87 .B mLib
  88 library provides a single standard arena,
  89 .BR arena_stdlib ,
  90 which uses the usual
  91 .BR malloc (3)
  92 and
  93 .BR free (3)
  94 calls.  The global variable
  95 .B arena_global
  96 is a pointer to a `current' arena, which is a good choice to use if
  97 you can't think of anything better.
  98 .PP
  99 The macros
 100 .BR A_ALLOC ,
 101 .B A_REALLOC
 102 and
 103 .B A_FREE
 104 behave like the standard C functions
 105 .BR malloc (3),
 106 .BR realloc (3)
 107 and
 108 .BR free (3),
 109 allocating, resizing and releasing blocks from a given arena.  There are
 110 function-call equivalents with lower-case names too.  For a more
 111 convenient interface to memory allocation, see
 112 .BR alloc (3).
 113 .PP
 114 .B Note:
 115 The
 116 .B realloc
 117 function has an extra argument
 118 .I osz
 119 specifying the old size of the block.  This is for the benefit of arena
 120 handlers which can't easily find the old block's size.
 121 .PP
 122 .
 123 .SS "Defining new arenas"
 124 An
 125 .B arena
 126 is a structure containing a single member,
 127 .BR ops ,
 128 which is a pointer to a structure of type
 129 .BR arena_ops .
 130 The
 131 .B arena
 132 structure may be followed in memory by data which is used by the arena's
 133 manager to maintain its state.
 134 .PP
 135 The
 136 .B arena_ops
 137 table contains function pointers which are called to perform various
 138 memory allocation tasks:
 139 .TP
 140 .BI "void *(*alloc)(arena *" a ", size_t " sz );
 141 Allocates a block of memory, of at least
 142 .I sz
 143 bytes in size, appropriately aligned, and returns its address.
 144 .nf
 145 .TP
 146 .BI "void *(*realloc)(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
 147 .fi
 148 Resizes the block pointed to by
 149 .IR p ,
 150 with
 151 .I osz
 152 interesting bytes in it,
 153 so that it is at least
 154 .I sz
 155 bytes long.  You can use
 156 .B arena_fakerealloc
 157 here, to fake resizing by allocating, copying and freeing, if your arena
 158 doesn't make doing something more efficient easy.
 159 .TP
 160 .BI "void (*free)(arena *" a ", void *" p );
 161 Frees the block pointed to by
 162 .IR p .
 163 .TP
 164 .BI "void (*purge)(arena *" a );
 165 Frees all blocks in the arena.  Used when the arena is being destroyed.
 166 .PP
 167 The behaviour of the
 168 .IR alloc ,
 169 .I realloc
 170 and
 171 .I free
 172 calls with respect to null pointers and zero-sized blocks is as
 173 specified by the ANSI C standard.
 174 .
 175 .\"--------------------------------------------------------------------------
 176 .SH "SEE ALSO"
 177 .
 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 --------------------------------------------------