~mdw / mLib / blame
| Commit | Line | Data |
|---|---|---|
| adec5584 MW |
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>" | |
| d056fbdf | 13 | .PP |
| adec5584 MW |
14 | .BI "GROWBUF_SIZE(size_t " sz ", size_t " want ", " \c |
| 15 | .BI "size_t " init ", size_t " granule ");" | |
| d056fbdf | 16 | .PP |
| adec5584 MW |
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> |