Add a slew of manual pages.

[mLib] / man / sub.3

diff --git a/man/sub.3 b/man/sub.3
new file mode 100644 (file)
index 0000000..b460506
--- /dev/null
+++ b/man/sub.3
@@ -0,0 +1,100 @@
+.\" -*-nroff-*-
+.de VS
+.sp 1
+.RS 5
+.nf
+.ft B
+..
+.de VE
+.ft R
+.fi
+.RE
+.sp 1
+..
+.TH sub 3mLib "8 May 1999" mLib
+.SH NAME
+sub \- efficient allocation and freeing of small blocks
+.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 (3mLib),
+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 (3mLib)
+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 cubersome
+.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 AUTHOR
+Mark Wooding, <mdw@nsict.org>