14 .TH dspool 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
16 dspool \- pools of preallocated dynamic strings
27 .B "#include <mLib/dspool.h>"
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 );
34 .BI "void DSGET(dspool *" p ", " d );
35 .BI "void DSPUT(dspool *" p ", dstr *" d );
38 A dynamic string pool maintains a collection of `spare' dynamic
39 strings. Some pieces of code require high turnover of strings, and
40 allocating and freeing them entails a large amount of overhead. A
41 dynamic string pool keeps a list of dynamic strings which have been
42 allocated but are not currently in use.
44 A pool is created by the function
46 It is passed the address of a pool structure
50 to allocate for new dynamic strings obtained from the pool. A newly
51 created pool contains no strings. Once a pool is no longer required,
54 will release all the strings in the pool, such that the pool can safely
57 A string is obtained from a pool by calling
59 If the pool is empty, a new string is allocated; otherwise a string is
60 chosen from those currently in the pool.
62 A string is returned to the pool by the
64 function. It is passed the address of a pool and the address of a
65 string to return. The string must have been allocated from
67 dynamic string pool, although it's not actually necessary to return it
68 to the pool from which it was allocated.
74 is equivalent to the assignment
78 (except that it's probably quicker). The macro
80 is entirely equivalent to the function
82 except for improved performance.
84 The string pool allocator requires the suballocator (see
86 for details). You must ensure that
88 is called before any strings are allocated from a string pool.
94 Mark Wooding, <mdw@distorted.org.uk>