.\" -*-nroff-*-
.de VS
.sp 1
.RS
.nf
.ft B
..
.de VE
.ft R
.fi
.RE
.sp 1
..
.TH sub 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
.SH NAME
sub \- efficient allocation and freeing of small blocks
.\" @sub_alloc
.\" @sub_free
.\" @sub_init
.\"
.\" @CREATE
.\" @DESTROY
.\"
.SH SYNOPSIS
.nf
.B "#include <mLib/sub.h>"

.B "void sub_init(void);"
.BI "void *sub_alloc(size_t " sz );
.BI "void sub_free(void *" p ", size_t " sz );

.BI "void *CREATE(" type );
.BI "void DESTROY(" type " *" p );
.fi
.SH DESCRIPTION
The
.B sub
collection of functions and macros implement an efficient allocator for
small blocks of known sizes.  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 system (actually via
.BR xmalloc (3),
q.v.) 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 sub_alloc
allocates a block of
.I sz
bytes.  If there isn't enough memory to allocate the block, the
exception
.B EXC_NOMEM
is raised.
.PP
The
.B sub_free
function frees a block allocated by
.BR sub_alloc .
You must know the size of the block in advance.  Note that
.B sub_free
never gives memory back to the underlying allocator.  Free sub-blocks
are just made available to later calls of
.BR sub_alloc .
.PP
Don't try to pass blocks allocated by
.B sub_alloc
to
.BR free (3);
similarly, don't try to pass blocks allocated by
.BR xmalloc (3)
or
.BR malloc (3)
to
.BR sub_free .
If you do, you'll get what you deserve.
.PP
The pair of macros
.B CREATE
and
.B DESTROY
are intended to provide a slightly more natural interface to
allocation.  The call
.VS
mystruct *p = sub_alloc(sizeof(mystruct));
.VE
can be replaced by
.VS
mystruct p = CREATE(mystruct);
.VE
Similarly, the block can be freed by saying
.VS
DESTROY(p)
.VE
rather than the more cumbersome
.VS
sub_free(p, sizeof(*p));
.VE
The function
.B sub_init
must be called before any of the other
.B sub
functions or macros.
.SH "SEE ALSO"
.BR exc (3),
.BR alloc (3),
.BR mLib (3).
.SH AUTHOR
Mark Wooding, <mdw@nsict.org>