Update for new arena management.

[mLib] / man / arena.3

diff --git a/man/arena.3 b/man/arena.3
new file mode 100644 (file)
index 0000000..d7631c2
--- /dev/null
+++ b/man/arena.3
@@ -0,0 +1,113 @@
+.\" -*-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>