chiark - git - mdw - mLib/blob - man/dspool.3

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