chiark - git - mdw - mLib/blob - struct/dspool.3.in

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for string pools
   4 .\"
   5 .\" (c) 1999, 2001, 2005, 2009, 2023, 2024 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the mLib utilities library.
  11 .\"
  12 .\" mLib is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU Library General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or (at
  15 .\" your option) any later version.
  16 .\"
  17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  20 .\" License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with mLib.  If not, write to the Free Software
  24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25 .\" USA.
  26 .
  27 .\"--------------------------------------------------------------------------
  28 .so ../defs.man \" @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH dspool 3mLib "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @dspool_create
  33 .\" @dspool_destroy
  34 .\" @dspool_get
  35 .\" @dspool_put
  36 .
  37 .\" @DSGET
  38 .\" @DSPUT
  39 .
  40 .\"--------------------------------------------------------------------------
  41 .SH NAME
  42 dspool \- pools of preallocated dynamic strings
  43 .
  44 .\"--------------------------------------------------------------------------
  45 .SH SYNOPSIS
  46 .
  47 .nf
  48 .B "#include <mLib/dspool.h>"
  49 .PP
  50 .B "typedef struct { ...\& } dspool;"
  51 .PP
  52 .BI "void dspool_create(dspool *" p ", size_t " isz );
  53 .BI "void dspool_destroy(dspool *" p );
  54 .BI "dstr *dspool_get(dspool *" p );
  55 .BI "void dspool_put(dspool *" p ", dstr *" d );
  56 .PP
  57 .BI "void DSGET(dspool *" p ", " d );
  58 .BI "void DSPUT(dspool *" p ", dstr *" d );
  59 .fi
  60 .
  61 .\"--------------------------------------------------------------------------
  62 .SH DESCRIPTION
  63 .
  64 A dynamic string pool maintains a collection of `spare' dynamic
  65 strings.  Some pieces of code require high turnover of strings, and
  66 allocating and freeing them entails a large amount of overhead.  A
  67 dynamic string pool keeps a list of dynamic strings which have been
  68 allocated but are not currently in use.
  69 .PP
  70 A pool is created by the function
  71 .BR dspool_create .
  72 It is passed the address of a pool structure
  73 .I p
  74 and the initial size
  75 .I isz
  76 to allocate for new dynamic strings obtained from the pool.  A newly
  77 created pool contains no strings.  Once a pool is no longer required,
  78 the function
  79 .B dspool_destroy
  80 will release all the strings in the pool, such that the pool can safely
  81 be thrown away.
  82 .PP
  83 A string is obtained from a pool by calling
  84 .BR dspool_get .
  85 If the pool is empty, a new string is allocated; otherwise a string is
  86 chosen from those currently in the pool.
  87 .PP
  88 A string is returned to the pool by the
  89 .B dspool_put
  90 function.  It is passed the address of a pool and the address of a
  91 string to return.  The string must have been allocated from
  92 .I some
  93 dynamic string pool, although it's not actually necessary to return it
  94 to the pool from which it was allocated.
  95 .PP
  96 The macro call
  97 .VS
  98 DSGET(p, d);
  99 .VE
 100 is equivalent to the assignment
 101 .VS
 102 d = dspool_get(p);
 103 .VE
 104 (except that it's probably quicker).  The macro
 105 .B DSPUT
 106 is entirely equivalent to the function
 107 .B dspool_put
 108 except for improved performance.
 109 .
 110 .\"--------------------------------------------------------------------------
 111 .SH CAVEATS
 112 .
 113 The string pool allocator requires the suballocator (see
 114 .BR sub (3)
 115 for details).  You must ensure that
 116 .B sub_init
 117 is called before any strings are allocated from a string pool.
 118 .
 119 .\"--------------------------------------------------------------------------
 120 .SH SEE ALSO
 121 .
 122 .BR dstr (3),
 123 .BR sub (3),
 124 .BR mLib (3).
 125 .
 126 .\"--------------------------------------------------------------------------
 127 .SH AUTHOR
 128 .
 129 Mark Wooding, <mdw@distorted.org.uk>
 130 .
 131 .\"----- That's all, folks --------------------------------------------------