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