mdw@git.distorted.org.uk Git - mLib/blob - mem/growbuf.3.in

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for buffer extension
   4 .\"
   5 .\" (c) 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 growbuf 3mLib "9 March 2024" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @GROWBUF_SIZE
  33 .\" @GROWBUF_EXTEND
  34 .\" @GROWBUF_REPLACE
  35 .\" @GROWBUF_RENEWV
  36 .\" @GROWBUF_REPLACEV
  37 .
  38 .\"--------------------------------------------------------------------------
  39 .SH NAME
  40 growbuf \- extend buffers efficiently
  41 .
  42 .\"--------------------------------------------------------------------------
  43 .SH SYNOPSIS
  44 .
  45 .nf
  46 .B "#include <mLib/growbuf.h>"
  47 .PP
  48 .ta \w'\fBvoid GROWBUF_SIZE('u
  49 .BI "void GROWBUF_SIZE(" type ", " type " &" sz ", " type " " want ,
  50 .BI "   " type " " init ", " type " " granule ");"
  51 .PP
  52 .ta \w'\fBvoid GROWBUF_EXTEND('u
  53 .BI "\fBvoid GROWBUF_EXTEND(" type ", arena *" a ", " type " *&" buf ,
  54 .BI "   " type " &" sz ", " type " " want ,
  55 .BI "   " type " " init ", " type " " granule ");"
  56 .ta \w'\fBvoid GROWBUF_REPLACE('u
  57 .BI "\fBvoid GROWBUF_REPLACE(" type ", arena *" a ", " type " *&" buf ,
  58 .BI "   " type " &" sz ", " type " " want ,
  59 .BI "   " type " " init ", " type " " granule ");"
  60 .PP
  61 .ta \w'\fBvoid GROWBUF_RENEWV('u
  62 .BI "\fBvoid GROWBUF_RENEWV(" type ", arena *" a ", " type " *&" buf ,
  63 .BI "   " type " &" sz ", " type " " want ", " type " " init ");"
  64 .ta \w'\fBvoid GROWBUF_REPLACEV('u
  65 .BI "\fBvoid GROWBUF_REPLACEV(" type ", arena *" a ", " type " *&" buf ,
  66 .BI "   " type " &" sz ", " type " " want ", " type " " init ");"
  67 .fi
  68 .
  69 .\"--------------------------------------------------------------------------
  70 .SH DESCRIPTION
  71 .
  72 The
  73 .B "<mLib/growbuf.h>"
  74 header file defines macros useful for dynamically resizing buffers.
  75 .PP
  76 The situation envisaged is a buffer, at address
  77 .IR buf ,
  78 with space to hold
  79 .I sz
  80 objects each of size
  81 .IR granule ;
  82 but it has become necessary to store
  83 .I want
  84 objects in the buffer.
  85 If the current size
  86 .I sz
  87 is zero, then the buffer pointer
  88 .I buf
  89 may be null;
  90 otherwise, it is assumed to have been allocated from the arena
  91 .IR a .
  92 The size
  93 .I init
  94 is a suggested minimal nonzero size, again counting objects of size
  95 .IR granule .
  96 .PP
  97 The
  98 .B GROWBUF_SIZE
  99 macro merely adjusts
 100 .I sz
 101 so that it is at least as large as
 102 .IR want ;
 103 it is
 104 .I assumed
 105 on entry that
 106 .IR sz "\ <\ " want ;
 107 nothing especially terrible will happen if this is not the case,
 108 but unnecessary work will take place,
 109 and
 110 .I sz
 111 will be left nonzero if it was previously zero,
 112 even if
 113 .IR want "\ =\ 0."
 114 .B GROWBUF_SIZE
 115 arranges to increase buffer sizes in a geometric progression
 116 so as to minimize reallocation and copying overheads \(en
 117 the number of reallocations will be
 118 at most logarithmic in the final size
 119 and each byte is copied an (amortized) constant number of times.
 120 .PP
 121 The
 122 .B GROWBUF_EXTEND
 123 macro will additionally resize the buffer,
 124 preserving its contents,
 125 and adjusting
 126 .I buf
 127 to point to its new location;
 128 if
 129 .I want
 130 \(<=
 131 .I sz
 132 then nothing happens.
 133 The
 134 .B GROWBUF_REPLACE
 135 macro is similar, except that it
 136 .I discards
 137 the existing buffer contents if the buffer needs to be adjusted.
 138 .PP
 139 The
 140 .B GROWBUF_RENEWV
 141 macro is the same as
 142 .B GROWBUF_EXTEND
 143 except that it implicitly uses
 144 .BI "sizeof(*" buf )
 145 as its
 146 .IR granule ;
 147 the
 148 .B GROWBUF_REPLACEV
 149 macro is similarly like
 150 .BR GROWBUF_REPLACE .
 151 .
 152 .\"--------------------------------------------------------------------------
 153 .SH "SEE ALSO"
 154 .
 155 .BR arena (3),
 156 .BR mLib (3).
 157 .
 158 .\"--------------------------------------------------------------------------
 159 .SH AUTHOR
 160 .
 161 Mark Wooding, <mdw@distorted.org.uk>
 162 .
 163 .\"----- That's all, folks --------------------------------------------------