@@@ much mess, mostly manpages

[mLib] / mem / sub.3.in

.\" -*-nroff-*-
.\"
.\" Manual for efficient small-block allocation
.\"
.\" (c) 1999, 2001, 2003, 2005, 2007, 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 sub 3mLib "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @subarena_create
.\" @subarena_destroy
.\" @subarena_alloc
.\" @subarena_free
.\" @sub_alloc
.\" @sub_free
.\" @sub_init
.
.\" @A_CREATE
.\" @A_DESTROY
.\" @CREATE
.\" @DESTROY
.
.\"--------------------------------------------------------------------------
.SH NAME
sub \- efficient allocation and freeing of small blocks
.
.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.
.nf
.B "#include <mLib/sub.h>"
.PP
.B "typedef struct { ...\& } subarena;"
.PP
.BI "void subarena_create(subarena *" s ", arena *" a );
.BI "void subarena_destroy(subarena *" s );
.BI "void subarena_alloc(subarena *" s ", size_t " sz );
.BI "void subarena_free(subarena *" s ", void *" p ", size_t " sz );
.PP
.B "void sub_init(void);"
.BI "void *sub_alloc(size_t " sz );
.BI "void sub_free(void *" p ", size_t " sz );
.PP
.BI "void *A_CREATE(subarena *" s ", " type );
.BI "void A_DESTROY(subarena *" s ", " type " *" p );
.BI "void *CREATE(" type );
.BI "void DESTROY(" type " *" p );
.fi
.
.\"--------------------------------------------------------------------------
.SH DESCRIPTION
.
The
.B subarena
collection of functions and macros implement an efficient allocator for
small blocks of known sizes, constructed from a general allocator
implemented by an
.BR arena (3).
Free blocks of the same size are linked together in list, making freeing
and allocation fast.  The `free' operation requires the block size as an
argument, so there's no data overhead for an allocated block.  The
system takes advantage of this by allocating big chunks from the
underlying arena and splitting the chunks into smaller blocks of the
right size, so the space and time overhead from the underlying allocator
is divided over many blocks.
.PP
Calling
.B subarena_alloc
allocates a block of
.I sz
bytes from the subarena
.IR s .
If there isn't enough memory to allocate the block, the
exception
.B EXC_NOMEM
is raised.
.PP
The
.B subarena_free
function frees a block allocated by
.B subarena_alloc
from the same subarena.  You must know the size of the block in advance.
Note that
.B subarena_free
never gives memory back to the underlying allocator.  Free sub-blocks
are just made available to later calls of
.BR subarena_alloc .
.PP
Don't try to free blocks allocated by
.B subarena_alloc
to the underlying arena's
.I free
function, or to try freeing blocks obtained directly from the arena's
.I alloc
function using
.BR subarena_free .
If you do, you'll get what you deserve.
.PP
The pair of macros
.B A_CREATE
and
.B A_DESTROY
are intended to provide a slightly more natural interface to
allocation.  The call
.VS
mystruct *p = subarena_alloc(s, sizeof(mystruct));
.VE
can be replaced by
.VS
mystruct p = A_CREATE(s, mystruct);
.VE
Similarly, the block can be freed by saying
.VS
A_DESTROY(s, p)
.VE
rather than the more cumbersome
.VS
subarena_free(s, p, sizeof(*p));
.VE
There is a standard subarena
.B sub_global
which uses
.B arena_global
as its underlying allocator (obtained the first time the subarena is
used).  The functions
.B sub_alloc
and
.B sub_free
and the macros
.B CREATE
and
.B DESTROY
use this subarena.
.PP
The function
.B sub_init
ought to be called before any of the other functions as a matter of good
taste, but actually the system will initialize itself the first time
it's used.
.
.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR arena (3),
.BR exc (3),
.BR alloc (3),
.BR mLib (3).
.
.\"--------------------------------------------------------------------------
.SH AUTHOR
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------