chiark - git - mdw - mLib/blob - mem/growbuf.3

   1 .\" -*-nroff-*-
   2 .TH growbuf 3 "9 March 2024" "Straylight/Edgeware" "mLib utilities library"
   3 .\" @GROWBUF_SIZE
   4 .\" @GROWBUF_EXTEND
   5 .\" @GROWBUF_REPLACE
   6 .
   7 .SH NAME
   8 growbuf \- extend buffers efficiently
   9 .
  10 .SH SYNOPSIS
  11 .nf
  12 .B "#include <mLib/growbuf.h>"
  13
  14 .BI "GROWBUF_SIZE(size_t " sz ", size_t " want ", " \c
  15 .BI "size_t " init ", size_t " granule ");"
  16
  17 .ds mT \fBGROWBUF_EXTEND(
  18 .BI "\*(mTarena *" a ", " type " *" buf ", size_t " sz ", size_t " want ","
  19 .BI "\h'\w'\*(mT'u'size_t " init ", size_t " granule ");"
  20 .ds mT \fBGROWBUF_REPLACE(
  21 .BI "\*(mTarena *" a ", " type " *" buf ", size_t " sz ", size_t " want ","
  22 .BI "\h'\w'\*(mT'u'size_t " init ", size_t " granule ");"
  23 .fi
  24 .
  25 .SH DESCRIPTION
  26 The
  27 .B "<mLib/growbuf.h>"
  28 header file defines macros useful for dynamically resizing buffers.
  29 .PP
  30 The situation envisaged is a buffer, at address
  31 .IR buf ,
  32 with space to hold
  33 .I sz
  34 objects each of size
  35 .IR granule ;
  36 but it has become necessary to store
  37 .I want
  38 objects in the buffer.
  39 If the current size
  40 .I sz
  41 is zero, then the buffer pointer
  42 .I buf
  43 may be null;
  44 otherwise, it is assumed to have been allocated from the arena
  45 .IR a .
  46 The size
  47 .I init
  48 is a suggested minimal nonzero size, again counting objects of size
  49 .IR granule .
  50 .PP
  51 The
  52 .B GROWBUF_SIZE
  53 macro merely adjusts
  54 .I sz
  55 so that it is at least as large as
  56 .IR want ;
  57 it is
  58 .I assumed
  59 on entry that
  60 .IR sz "\ <\ " want ;
  61 nothing especially terrible will happen if this is not the case,
  62 but unnecessary work will take place,
  63 and
  64 .I sz
  65 will be left nonzero if it was previously zero,
  66 even if
  67 .IR want "\ =\ 0."
  68 .B GROWBUF_SIZE
  69 arranges to increase buffer sizes in a geometric progression
  70 so as to minimize reallocation and copying overheads \(en
  71 the number of reallocations will be
  72 at most logarithmic in the final size
  73 and each byte is copied an (amortized) constant number of times.
  74 .PP
  75 The
  76 .B GROWBUF_EXTEND
  77 macro will additionally resize the buffer,
  78 preserving its contents,
  79 and adjusting
  80 .I buf
  81 to point to its new location;
  82 if
  83 .I want
  84 \(<=
  85 .I sz
  86 then nothing happens.
  87 The
  88 .B GROWBUF_REPLACE
  89 macro is similar, except that it
  90 .I discards
  91 the existing buffer contents if the buffer needs to be adjusted.
  92 .
  93 .SH "SEE ALSO"
  94 .BR arena (3),
  95 .BR mLib (3).
  96 .
  97 .SH AUTHOR
  98 Mark Wooding, <mdw@distorted.org.uk>