.\" -*-nroff-*-
.TH arena 3 "3 June 2000" mLib
.SH "NAME"
arena \- control of memory allocation
.\" @arena_global
.\" @arena_stdlib
.\" @arena_fakemalloc
.\" @a_alloc
.\" @a_realloc
.\" @a_free
.\" @A_ALLOC
.\" @A_REALLOC
.\" @A_FREE
.SH "SYNOPSIS"
.nf
.B "#include <mLib/arena.h>"

.BI "arena *arena_global;"
.BI "arena arena_stdlib;"

.BI "void *arena_fakerealloc(arena *" a ", void *" p ", size_t " sz );

.BI "void *a_alloc(arena *" a ", size_t " sz );
.BI "void *a_realloc(arena *" a ", void *" p ", size_t " sz );
.BI "void a_free(arena *" a );

.BI "void *A_ALLOC(arena *" a ", size_t " sz );
.BI "void *A_REALLOC(arena *" a ", void *" p ", size_t " sz );
.BI "void A_FREE(arena *" a );
.fi
.SH "DESCRIPTION"
An
.I arena
is a place from which blocks of memory may be allocated and freed.  The
basic
.B mLib
library provides a single standard arena,
.BR arena_stdlib ,
which uses the usual
.BR malloc (3)
and
.BR free (3)
calls.  The global variable
.B arena_global
is a pointer to a `current' arena, which is a good choice to use if
you can't think of anything better.
.PP
The macros
.BR A_ALLOC ,
.B A_REALLOC
and
.B A_FREE
behave like the standard C functions
.BR malloc (3),
.BR realloc (3)
and
.BR free (3),
allocating, resizing and releasing blocks from a given arena.  There are
function-call equivalents with lower-case names too.  For a more
convenient interface to memory allocation, see
.BR alloc (3).
.PP
.SS "Defining new arenas"
An
.B arena
is a structure containing a single member,
.BR ops ,
which is a pointer to a structure of type
.BR arena_ops .
The
.B arena
structure may be followed in memory by data which is used by the arena's
manager to maintain its state.
.PP
The
.B arena_ops
table contains function pointers which are called to perform various
memory allocation tasks:
.TP
.BI "void *(*" alloc ")(arena *" a ", size_t " sz );
Allocates a block of memory, of at least
.I sz
bytes in size, appropriately aligned, and returns its address.
.TP
.BI "void *(*" realloc ")(arena *" a ", void *" p ", size_t " sz );
Resizes the block pointed to by
.IR p ,
so that it is at least
.I sz
bytes long.  You can use
.B arena_fakerealloc
here, to fake resizing by allocating, copying and freeing, if your arena
doesn't make doing something more efficient easy.
.TP
.BI "void (*" free ")(arena *" a ", void *" p );
Frees the block pointed to by
.IR p .
.TP
.BI "void (*" purge ")(arena *" a );
Frees all blocks in the arena.  Used when the arena is being destroyed.
.PP
The behaviour of the
.IR alloc ,
.I realloc
and
.I free
calls with respect to null pointers and zero-sized blocks is as
specified by the ANSI C standard.
.SH "SEE ALSO"
.BR alloc (3),
.BR mLib (3).
.SH AUTHOR
Mark Wooding, <mdw@nsict.org>