@@@ wip type definitions in manpage synopses

[mLib] / mem / arena.3

.\" -*-nroff-*-
.TH arena 3 "3 June 2000" "Straylight/Edgeware" "mLib utilities library"
.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>"

.B "typedef struct {"
.B "\h'4n'const struct arena_ops *ops";
.B "} arena;"

.B "typedef struct {"
.BI "\h'4n'void *(*alloc)(arena *" a ", size_t " sz );
.BI "\h'4n'void *(*realloc)(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
.BI "\h'4n'void *(*free)(arena *" a ", void *" p );
.BI "\h'4n'void *(*purge)(arena *" a );
.B "} arena_ops;"

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

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

.BI "void *a_alloc(arena *" a ", size_t " sz );
.BI "void *a_realloc(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
.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 ", size_t " osz );
.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
.B Note:
The
.B realloc
function has an extra argument
.I osz
specifying the old size of the block.  This is for the benefit of arena
handlers which can't easily find the old block's size.
.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.
.nf
.TP
.BI "void *(*realloc)(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
.fi
Resizes the block pointed to by
.IR p ,
with
.I osz
interesting bytes in it,
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@distorted.org.uk>