@@@ much mess, mostly manpages

[mLib] / mem / arena.3.in

.\" -*-nroff-*-
.\"
.\" Manual for configurable memory management
.\"
.\" (c) 2000, 2001, 2005, 2009, 2023, 2024 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of the mLib utilities library.
.\"
.\" mLib is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU Library General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or (at
.\" your option) any later version.
.\"
.\" mLib is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Library General Public
.\" License along with mLib.  If not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
.\" USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH arena 3mLib "3 June 2000" "Straylight/Edgeware" "mLib utilities library"
.\" @arena_global
.\" @arena_stdlib
.\" @arena_fakemalloc
.\" @a_alloc
.\" @a_realloc
.\" @a_free
.\" @A_ALLOC
.\" @A_REALLOC
.\" @A_FREE
.
.\"--------------------------------------------------------------------------
.SH "NAME"
arena \- control of memory allocation
.
.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
.
.nf
.B "#include <mLib/arena.h>"
.PP
.ta 2n
.B "typedef struct {"
.B "	const struct arena_ops *ops";
.B "} arena;"
.PP
.B "typedef struct {"
.BI "	void *(*alloc)(arena *" a ", size_t " sz );
.BI "	void *(*realloc)(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
.BI "	void *(*free)(arena *" a ", void *" p );
.BI "	void *(*purge)(arena *" a );
.B "} arena_ops;"
.PP
.BI "arena *arena_global;"
.BI "arena arena_stdlib;"
.PP
.ta \w'\fBvoid *arena_fakerealloc('u
.BI "void *arena_fakerealloc(arena *" a ", void *" p ,
.BI "	size_t " sz ", size_t " osz );
.PP
.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 );
.PP
.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>
.
.\"----- That's all, folks --------------------------------------------------