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