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

   1 .\" -*-nroff-*-
   2 .TH arena 3 "3 June 2000" "Straylight/Edgeware" "mLib utilities library"
   3 .SH "NAME"
   4 arena \- control of memory allocation
   5 .\" @arena_global
   6 .\" @arena_stdlib
   7 .\" @arena_fakemalloc
   8 .\" @a_alloc
   9 .\" @a_realloc
  10 .\" @a_free
  11 .\" @A_ALLOC
  12 .\" @A_REALLOC
  13 .\" @A_FREE
  14 .SH "SYNOPSIS"
  15 .nf
  16 .B "#include <mLib/arena.h>"
  17
  18 .ta 2n
  19 .B "typedef struct {"
  20 .B "    const struct arena_ops *ops";
  21 .B "} arena;"
  22
  23 .B "typedef struct {"
  24 .BI "   void *(*alloc)(arena *" a ", size_t " sz );
  25 .BI "   void *(*realloc)(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
  26 .BI "   void *(*free)(arena *" a ", void *" p );
  27 .BI "   void *(*purge)(arena *" a );
  28 .B "} arena_ops;"
  29
  30 .BI "arena *arena_global;"
  31 .BI "arena arena_stdlib;"
  32
  33 .ta \w'\fBvoid *arena_fakerealloc('u
  34 .BI "void *arena_fakerealloc(arena *" a ", void *" p ,
  35 .BI "   size_t " sz ", size_t " osz );
  36
  37 .BI "void *a_alloc(arena *" a ", size_t " sz );
  38 .BI "void *a_realloc(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
  39 .BI "void a_free(arena *" a );
  40
  41 .BI "void *A_ALLOC(arena *" a ", size_t " sz );
  42 .BI "void *A_REALLOC(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
  43 .BI "void A_FREE(arena *" a );
  44 .fi
  45 .SH "DESCRIPTION"
  46 An
  47 .I arena
  48 is a place from which blocks of memory may be allocated and freed.  The
  49 basic
  50 .B mLib
  51 library provides a single standard arena,
  52 .BR arena_stdlib ,
  53 which uses the usual
  54 .BR malloc (3)
  55 and
  56 .BR free (3)
  57 calls.  The global variable
  58 .B arena_global
  59 is a pointer to a `current' arena, which is a good choice to use if
  60 you can't think of anything better.
  61 .PP
  62 The macros
  63 .BR A_ALLOC ,
  64 .B A_REALLOC
  65 and
  66 .B A_FREE
  67 behave like the standard C functions
  68 .BR malloc (3),
  69 .BR realloc (3)
  70 and
  71 .BR free (3),
  72 allocating, resizing and releasing blocks from a given arena.  There are
  73 function-call equivalents with lower-case names too.  For a more
  74 convenient interface to memory allocation, see
  75 .BR alloc (3).
  76 .PP
  77 .B Note:
  78 The
  79 .B realloc
  80 function has an extra argument
  81 .I osz
  82 specifying the old size of the block.  This is for the benefit of arena
  83 handlers which can't easily find the old block's size.
  84 .PP
  85 .SS "Defining new arenas"
  86 An
  87 .B arena
  88 is a structure containing a single member,
  89 .BR ops ,
  90 which is a pointer to a structure of type
  91 .BR arena_ops .
  92 The
  93 .B arena
  94 structure may be followed in memory by data which is used by the arena's
  95 manager to maintain its state.
  96 .PP
  97 The
  98 .B arena_ops
  99 table contains function pointers which are called to perform various
 100 memory allocation tasks:
 101 .TP
 102 .BI "void *(*alloc)(arena *" a ", size_t " sz );
 103 Allocates a block of memory, of at least
 104 .I sz
 105 bytes in size, appropriately aligned, and returns its address.
 106 .nf
 107 .TP
 108 .BI "void *(*realloc)(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
 109 .fi
 110 Resizes the block pointed to by
 111 .IR p ,
 112 with
 113 .I osz
 114 interesting bytes in it,
 115 so that it is at least
 116 .I sz
 117 bytes long.  You can use
 118 .B arena_fakerealloc
 119 here, to fake resizing by allocating, copying and freeing, if your arena
 120 doesn't make doing something more efficient easy.
 121 .TP
 122 .BI "void (*free)(arena *" a ", void *" p );
 123 Frees the block pointed to by
 124 .IR p .
 125 .TP
 126 .BI "void (*purge)(arena *" a );
 127 Frees all blocks in the arena.  Used when the arena is being destroyed.
 128 .PP
 129 The behaviour of the
 130 .IR alloc ,
 131 .I realloc
 132 and
 133 .I free
 134 calls with respect to null pointers and zero-sized blocks is as
 135 specified by the ANSI C standard.
 136 .SH "SEE ALSO"
 137 .BR alloc (3),
 138 .BR mLib (3).
 139 .SH AUTHOR
 140 Mark Wooding, <mdw@distorted.org.uk>