@@@ much mess, mostly manpages

[mLib] / struct / dspool.3.in

.\" -*-nroff-*-
.\"
.\" Manual for string pools
.\"
.\" (c) 1999, 2001, 2005, 2009, 2023, 2024 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of the mLib utilities library.
.\"
.\" mLib is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU Library General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or (at
.\" your option) any later version.
.\"
.\" mLib is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Library General Public
.\" License along with mLib.  If not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
.\" USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH dspool 3mLib "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @dspool_create
.\" @dspool_destroy
.\" @dspool_get
.\" @dspool_put
.
.\" @DSGET
.\" @DSPUT
.
.\"--------------------------------------------------------------------------
.SH NAME
dspool \- pools of preallocated dynamic strings
.
.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.
.nf
.B "#include <mLib/dspool.h>"
.PP
.B "typedef struct { ...\& } dspool;"
.PP
.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 );
.PP
.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>
.
.\"----- That's all, folks --------------------------------------------------