X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/mLib/blobdiff_plain/08da152ecf0c34dbb9fbfa9e863f1057c092e860..471f9daa24ee9251730e234fe92ad65c1fa9dff3:/man/sub.3

diff --git a/man/sub.3 b/man/sub.3
index 0d93166..ef61110 100644
--- a/man/sub.3
+++ b/man/sub.3
@@ -1,7 +1,7 @@
 .\" -*-nroff-*-
 .de VS
 .sp 1
-.RS 5
+.RS
 .nf
 .ft B
 ..
@@ -11,13 +11,19 @@
 .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
 .\"
@@ -25,85 +31,110 @@ sub \- efficient allocation and freeing of small blocks
 .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).