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 3 "20 June 1999" mLib
  15 .SH NAME
  16 dspool \- pools of preallocated dynamic strings
  17 .\" @dspool_create
  18 .\" @dspool_destroy
  19 .\" @dspool_get
  20 .\" @dspool_put
  21 .\"
  22 .\" @DSGET
  23 .\" @DSPUT
  24 .\"
  25 .SH SYNOPSIS
  26 .nf
  27 .B "#include <mLib/dspool.h>"
  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
  34 .BI "void DSGET(dspool *" p ", " d );
  35 .BI "void DSPUT(dspool *" p ", dstr *" d );
  36 .fi
  37 .SH DESCRIPTION
  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.
  43 .PP
  44 A pool is created by the function
  45 .BR dspool_create .
  46 It is passed the address of a pool structure
  47 .I p
  48 and the initial size
  49 .I isz
  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,
  52 the function
  53 .B dspool_destroy
  54 will release all the strings in the pool, such that the pool can safely
  55 be thrown away.
  56 .PP
  57 A string is obtained from a pool by calling
  58 .BR dspool_get .
  59 If the pool is empty, a new string is allocated; otherwise a string is
  60 chosen from those currently in the pool.
  61 .PP
  62 A string is returned to the pool by the
  63 .B dspool_put
  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
  66 .I some
  67 dynamic string pool, although it's not actually necessary to return it
  68 to the pool from which it was allocated.
  69 .PP
  70 The macro call
  71 .VS
  72 DSGET(p, d);
  73 .VE
  74 is equivalent to the assignment
  75 .VS
  76 d = dspool_get(p);
  77 .VE
  78 (except that it's probably quicker).  The macro
  79 .B DSPUT
  80 is entirely equivalent to the function
  81 .B dspool_put
  82 except for improved performance.
  83 .SH CAVEATS
  84 The string pool allocator requires the suballocator (see
  85 .BR sub (3)
  86 for details).  You must ensure that
  87 .B sub_init
  88 is called before any strings are allocated from a string pool.
  89 .SH SEE ALSO
  90 .BR dstr (3),
  91 .BR sub (3),
  92 .BR mLib (3).
  93 .SH AUTHOR
  94 Mark Wooding, <mdw@nsict.org>