Commit | Line | Data |
---|---|---|
adec5584 | 1 | .\" -*-nroff-*- |
c4ccbbf9 MW |
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" | |
adec5584 MW |
32 | .\" @GROWBUF_SIZE |
33 | .\" @GROWBUF_EXTEND | |
34 | .\" @GROWBUF_REPLACE | |
35 | . | |
c4ccbbf9 | 36 | .\"-------------------------------------------------------------------------- |
adec5584 MW |
37 | .SH NAME |
38 | growbuf \- extend buffers efficiently | |
39 | . | |
c4ccbbf9 | 40 | .\"-------------------------------------------------------------------------- |
adec5584 | 41 | .SH SYNOPSIS |
c4ccbbf9 | 42 | . |
adec5584 MW |
43 | .nf |
44 | .B "#include <mLib/growbuf.h>" | |
d056fbdf | 45 | .PP |
adec5584 MW |
46 | .BI "GROWBUF_SIZE(size_t " sz ", size_t " want ", " \c |
47 | .BI "size_t " init ", size_t " granule ");" | |
d056fbdf | 48 | .PP |
adec5584 MW |
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 | . | |
c4ccbbf9 | 57 | .\"-------------------------------------------------------------------------- |
adec5584 | 58 | .SH DESCRIPTION |
c4ccbbf9 | 59 | . |
adec5584 MW |
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 | . | |
c4ccbbf9 | 127 | .\"-------------------------------------------------------------------------- |
adec5584 | 128 | .SH "SEE ALSO" |
c4ccbbf9 | 129 | . |
adec5584 MW |
130 | .BR arena (3), |
131 | .BR mLib (3). | |
132 | . | |
c4ccbbf9 | 133 | .\"-------------------------------------------------------------------------- |
adec5584 | 134 | .SH AUTHOR |
c4ccbbf9 | 135 | . |
adec5584 | 136 | Mark Wooding, <mdw@distorted.org.uk> |
c4ccbbf9 MW |
137 | . |
138 | .\"----- That's all, folks -------------------------------------------------- |