.\" -*-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@nsict.org>