2 .TH arena 3 "3 June 2000" "Straylight/Edgeware" "mLib utilities library"
4 arena \- control of memory allocation
16 .B "#include <mLib/arena.h>"
19 .B "\h'4n'const struct arena_ops *ops";
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 );
29 .BI "arena *arena_global;"
30 .BI "arena arena_stdlib;"
32 .BI "void *arena_fakerealloc(arena *" a ", void *" p ,
33 .BI " size_t " sz ", size_t " osz );
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 );
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 );
46 is a place from which blocks of memory may be allocated and freed. The
49 library provides a single standard arena,
55 calls. The global variable
57 is a pointer to a `current' arena, which is a good choice to use if
58 you can't think of anything better.
65 behave like the standard C functions
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
78 function has an extra argument
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.
83 .SS "Defining new arenas"
86 is a structure containing a single member,
88 which is a pointer to a structure of type
92 structure may be followed in memory by data which is used by the arena's
93 manager to maintain its state.
97 table contains function pointers which are called to perform various
98 memory allocation tasks:
100 .BI "void *(*alloc)(arena *" a ", size_t " sz );
101 Allocates a block of memory, of at least
103 bytes in size, appropriately aligned, and returns its address.
106 .BI "void *(*realloc)(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
108 Resizes the block pointed to by
112 interesting bytes in it,
113 so that it is at least
115 bytes long. You can use
117 here, to fake resizing by allocating, copying and freeing, if your arena
118 doesn't make doing something more efficient easy.
120 .BI "void (*free)(arena *" a ", void *" p );
121 Frees the block pointed to by
124 .BI "void (*purge)(arena *" a );
125 Frees all blocks in the arena. Used when the arena is being destroyed.
132 calls with respect to null pointers and zero-sized blocks is as
133 specified by the ANSI C standard.
138 Mark Wooding, <mdw@distorted.org.uk>