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

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