Manpages: Move manpages (back?) into the top-level directory.

[mLib] / dspool.3

diff --git a/dspool.3 b/dspool.3
new file mode 100644 (file)
index 0000000..59e91b4
--- /dev/null
+++ b/dspool.3
@@ -0,0 +1,94 @@
+.\" -*-nroff-*-
+.de VS
+.sp 1
+.in +5n
+.ft B
+.nf
+..
+.de VE
+.ft R
+.in -5n
+.sp 1
+.fi
+..
+.TH dspool 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
+.SH NAME
+dspool \- pools of preallocated dynamic strings
+.\" @dspool_create
+.\" @dspool_destroy
+.\" @dspool_get
+.\" @dspool_put
+.\"
+.\" @DSGET
+.\" @DSPUT
+.\"
+.SH SYNOPSIS
+.nf
+.B "#include <mLib/dspool.h>"
+
+.BI "void dspool_create(dspool *" p ", size_t " isz );
+.BI "void dspool_destroy(dspool *" p );
+.BI "dstr *dspool_get(dspool *" p );
+.BI "void dspool_put(dspool *" p ", dstr *" d );
+
+.BI "void DSGET(dspool *" p ", " d );
+.BI "void DSPUT(dspool *" p ", dstr *" d );
+.fi
+.SH DESCRIPTION
+A dynamic string pool maintains a collection of `spare' dynamic
+strings.  Some pieces of code require high turnover of strings, and
+allocating and freeing them entails a large amount of overhead.  A
+dynamic string pool keeps a list of dynamic strings which have been
+allocated but are not currently in use.
+.PP
+A pool is created by the function
+.BR dspool_create .
+It is passed the address of a pool structure
+.I p
+and the initial size
+.I isz
+to allocate for new dynamic strings obtained from the pool.  A newly
+created pool contains no strings.  Once a pool is no longer required,
+the function
+.B dspool_destroy
+will release all the strings in the pool, such that the pool can safely
+be thrown away.
+.PP
+A string is obtained from a pool by calling
+.BR dspool_get .
+If the pool is empty, a new string is allocated; otherwise a string is
+chosen from those currently in the pool.
+.PP
+A string is returned to the pool by the
+.B dspool_put
+function.  It is passed the address of a pool and the address of a
+string to return.  The string must have been allocated from
+.I some
+dynamic string pool, although it's not actually necessary to return it
+to the pool from which it was allocated.
+.PP
+The macro call
+.VS
+DSGET(p, d);
+.VE
+is equivalent to the assignment
+.VS
+d = dspool_get(p);
+.VE
+(except that it's probably quicker).  The macro
+.B DSPUT
+is entirely equivalent to the function
+.B dspool_put
+except for improved performance.
+.SH CAVEATS
+The string pool allocator requires the suballocator (see
+.BR sub (3)
+for details).  You must ensure that
+.B sub_init
+is called before any strings are allocated from a string pool.
+.SH SEE ALSO
+.BR dstr (3),
+.BR sub (3),
+.BR mLib (3).
+.SH AUTHOR
+Mark Wooding, <mdw@distorted.org.uk>