@@@ fltfmt wip

[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
.
.\" @ALLOCV_SAFE_P
.\" @NEWV_SAFE_P
.
.\" @A_ALLOC
.\" @A_ALLOCV
.\" @A_NEW
.\" @A_NEWV
.\" @A_REALLOC
.\" @A_RENEWV
.\" @A_FREE
.
.\" @a_alloc
.\" @a_allocv
.\" @a_realloc
.\" @a_reallocv
.\" @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 "int ALLOCV_SAFE_P(size_t " n ", size_t " sz );
.BI "int NEWV_SAFE_P(" type " *" p ", size_t " n );
.PP
.BI "void *a_alloc(arena *" a ", size_t " sz );
.BI "void *a_allocv(arena *" a ", size_t " n ", size_t " sz );
.BI "void *a_realloc(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
.ta \w'\fBvoid a_reallocv('u
.BI "void *a_reallocv(arena *" a ", void *" p ,
.BI "	size_t " n ", size_t " on ", size_t " sz );
.BI "void a_free(arena *" a );
.PP
.BI "void *A_ALLOC(arena *" a ", size_t " sz );
.BI "void *A_ALLOCV(arena *" a ", size_t " n ", size_t " sz );
.BI "void A_NEW(" type " *" p ", arena *" a );
.BI "void A_NEWV(" type " *" p ", arena *" a ", size_t " n );
.BI "void *A_REALLOC(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
.ta \w'\fBvoid A_REALLOCV('u
.BI "void *A_REALLOCV(arena *" a ", void *" p ,
.BI "	size_t " n ", size_t " on ", size_t " sz );
.ta \w'\fBvoid A_RENEWV('u
.BI "void A_RENEWV(" type " *" q ", " type " *" p ", arena *" a ,
.BI "	size_t " n ", size_t " on ", 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
.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
The macro
.B ALLOCV_SAFE_P
returns nonzero if the product
.IR n "\ \*(mu\ " sz
is representable in type
.B size_t
and zero otherwise;
i.e., it returns true if it would be safe to try to allocate
.IR n "\ \*(mu\ " sz
bytes.
The macro
.BR A_ALLOCV
allocates space for an array of
.I n
elements each of size
.IR sz ,
somewhat like
.BR calloc (3),
except that
.B A_ALLOCV
does not clear the allocated memory.
Likewise, the macro
.B A_REALLOCV
resizes the block pointed to by
.IR p ,
which previously had space for
.I on
elements of size
.IR sz ,
so that it now has enough space for
.I n
elements,
returning the new block address.
There are also function-call equivalents of these macros.
.PP
Finally, the macro
.B A_NEW
sets its argument
.I p
to point to a freshly allocated block of memory
large enough for the type that
.I p
points to,
or to null if allocation failed.
The macro
.B A_NEWV
sets
.I p
to point to memory large enough for
.I n
elements, each of the type that
.I p
points to.
The macro
.B A_RENEWV
sets
.I q
to point to memory large enough for
.I n
elements, each of the type that
.I p
points to.
.
.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 --------------------------------------------------