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