X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/mLib/blobdiff_plain/8e94a44e0eacbec394bc93d87db275295e7a670d..b6b9d458c78364bdbbd7fbd7ec543bc364014b45:/man/dspool.3

diff --git a/man/dspool.3 b/man/dspool.3
new file mode 100644
index 0000000..72465dc
--- /dev/null
+++ b/man/dspool.3
@@ -0,0 +1,85 @@
+.\" -*-nroff-*-
+.de VS
+.sp 1
+.in +5n
+.ft B
+.nf
+..
+.de VE
+.ft R
+.in -5n
+.sp 1
+.fi
+..
+.TH dspool 3mLib "20 June 1999" mLib
+.SH NAME
+dspool \- pools of preallocated dynamic strings
+.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 "dstr *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 izs
+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 (3mLib)
+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 (3mLib),
+.BR sub (3mLib).
+.SH AUTHOR
+Mark Wooding, <mdw@nsict.org>