.RE
.sp 1
..
-.TH sub 3 "8 May 1999" mLib
+.TH sub 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
.SH NAME
sub \- efficient allocation and freeing of small blocks
+.\" @subarena_create
+.\" @subarena_destroy
+.\" @subarena_alloc
+.\" @subarena_free
.\" @sub_alloc
.\" @sub_free
.\" @sub_init
.\"
+.\" @A_CREATE
+.\" @A_DESTROY
.\" @CREATE
.\" @DESTROY
.\"
.nf
.B "#include <mLib/sub.h>"
+.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 );
+
.B "void sub_init(void);"
.BI "void *sub_alloc(size_t " sz );
.BI "void sub_free(void *" p ", size_t " sz );
+.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 sub
+.B subarena
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.
+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 sub_alloc
+.B subarena_alloc
allocates a block of
.I sz
-bytes. If there isn't enough memory to allocate the block, the
+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 sub_free
+.B subarena_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
+.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 sub_alloc .
+.BR subarena_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 .
+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 CREATE
+.B A_CREATE
and
-.B DESTROY
+.B A_DESTROY
are intended to provide a slightly more natural interface to
allocation. The call
.VS
-mystruct *p = sub_alloc(sizeof(mystruct));
+mystruct *p = subarena_alloc(s, sizeof(mystruct));
.VE
can be replaced by
.VS
-mystruct p = CREATE(mystruct);
+mystruct p = A_CREATE(s, mystruct);
.VE
Similarly, the block can be freed by saying
.VS
-DESTROY(p)
+A_DESTROY(s, p)
.VE
-rather than the more cubersome
+rather than the more cumbersome
.VS
-sub_free(p, sizeof(*p));
+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
-must be called before any of the other
-.B sub
-functions or macros.
+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@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blobdiff