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