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 | |
b1a20bee MW |
35 | .\" @GROWBUF_RENEWV |
36 | .\" @GROWBUF_REPLACEV | |
adec5584 | 37 | . |
c4ccbbf9 | 38 | .\"-------------------------------------------------------------------------- |
adec5584 MW |
39 | .SH NAME |
40 | growbuf \- extend buffers efficiently | |
41 | . | |
c4ccbbf9 | 42 | .\"-------------------------------------------------------------------------- |
adec5584 | 43 | .SH SYNOPSIS |
c4ccbbf9 | 44 | . |
adec5584 MW |
45 | .nf |
46 | .B "#include <mLib/growbuf.h>" | |
d056fbdf | 47 | .PP |
b1a20bee MW |
48 | .ta \w'\fBvoid GROWBUF_SIZE('u |
49 | .BI "void GROWBUF_SIZE(" type ", " type " &" sz ", " type " " want , | |
50 | .BI " " type " " init ", " type " " granule ");" | |
d056fbdf | 51 | .PP |
b1a20bee MW |
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 ");" | |
adec5584 MW |
67 | .fi |
68 | . | |
c4ccbbf9 | 69 | .\"-------------------------------------------------------------------------- |
adec5584 | 70 | .SH DESCRIPTION |
c4ccbbf9 | 71 | . |
adec5584 MW |
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. | |
b1a20bee MW |
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 . | |
adec5584 | 151 | . |
c4ccbbf9 | 152 | .\"-------------------------------------------------------------------------- |
adec5584 | 153 | .SH "SEE ALSO" |
c4ccbbf9 | 154 | . |
adec5584 MW |
155 | .BR arena (3), |
156 | .BR mLib (3). | |
157 | . | |
c4ccbbf9 | 158 | .\"-------------------------------------------------------------------------- |
adec5584 | 159 | .SH AUTHOR |
c4ccbbf9 | 160 | . |
adec5584 | 161 | Mark Wooding, <mdw@distorted.org.uk> |
c4ccbbf9 MW |
162 | . |
163 | .\"----- That's all, folks -------------------------------------------------- |