chiark / gitweb /
Import buf from Catacomb; split out the dstr bits, and throw away the mp and
[mLib] / man / dspool.3
CommitLineData
b6b9d458 1.\" -*-nroff-*-
2.de VS
3.sp 1
4.in +5n
5.ft B
6.nf
7..
8.de VE
9.ft R
10.in -5n
11.sp 1
12.fi
13..
fbf20b5b 14.TH dspool 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
b6b9d458 15.SH NAME
16dspool \- pools of preallocated dynamic strings
08da152e 17.\" @dspool_create
18.\" @dspool_destroy
19.\" @dspool_get
20.\" @dspool_put
21.\"
22.\" @DSGET
23.\" @DSPUT
24.\"
b6b9d458 25.SH SYNOPSIS
26.nf
d2a91066 27.B "#include <mLib/dspool.h>"
b6b9d458 28
29.BI "void dspool_create(dspool *" p ", size_t " isz );
30.BI "void dspool_destroy(dspool *" p );
31.BI "dstr *dspool_get(dspool *" p );
32.BI "void dspool_put(dspool *" p ", dstr *" d );
33
d2a91066 34.BI "void DSGET(dspool *" p ", " d );
b6b9d458 35.BI "void DSPUT(dspool *" p ", dstr *" d );
36.fi
37.SH DESCRIPTION
38A dynamic string pool maintains a collection of `spare' dynamic
39strings. Some pieces of code require high turnover of strings, and
40allocating and freeing them entails a large amount of overhead. A
41dynamic string pool keeps a list of dynamic strings which have been
42allocated but are not currently in use.
43.PP
44A pool is created by the function
45.BR dspool_create .
46It is passed the address of a pool structure
47.I p
48and the initial size
d2a91066 49.I isz
b6b9d458 50to allocate for new dynamic strings obtained from the pool. A newly
51created pool contains no strings. Once a pool is no longer required,
52the function
53.B dspool_destroy
54will release all the strings in the pool, such that the pool can safely
55be thrown away.
56.PP
57A string is obtained from a pool by calling
58.BR dspool_get .
59If the pool is empty, a new string is allocated; otherwise a string is
60chosen from those currently in the pool.
61.PP
62A string is returned to the pool by the
63.B dspool_put
64function. It is passed the address of a pool and the address of a
65string to return. The string must have been allocated from
66.I some
67dynamic string pool, although it's not actually necessary to return it
68to the pool from which it was allocated.
69.PP
70The macro call
71.VS
72DSGET(p, d);
73.VE
74is equivalent to the assignment
75.VS
76d = dspool_get(p);
77.VE
78(except that it's probably quicker). The macro
79.B DSPUT
80is entirely equivalent to the function
81.B dspool_put
82except for improved performance.
83.SH CAVEATS
84The string pool allocator requires the suballocator (see
08da152e 85.BR sub (3)
b6b9d458 86for details). You must ensure that
87.B sub_init
88is called before any strings are allocated from a string pool.
89.SH SEE ALSO
08da152e 90.BR dstr (3),
91.BR sub (3),
92.BR mLib (3).
b6b9d458 93.SH AUTHOR
9b5ac6ff 94Mark Wooding, <mdw@distorted.org.uk>