Infrastructure: Split the files into subdirectories.

[mLib] / mem / sub.3

diff --git a/mem/sub.3 b/mem/sub.3
new file mode 100644 (file)
index 0000000..b1f6083
--- /dev/null
+++ b/mem/sub.3
@@ -0,0 +1,142 @@
+.\" -*-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
+.\" @subarena_create
+.\" @subarena_destroy
+.\" @subarena_alloc
+.\" @subarena_free
+.\" @sub_alloc
+.\" @sub_free
+.\" @sub_init
+.\"
+.\" @A_CREATE
+.\" @A_DESTROY
+.\" @CREATE
+.\" @DESTROY
+.\"
+.SH SYNOPSIS
+.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 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>