comparison: docs/Writerside/topics/buffer.h.md
docs/Writerside/topics/buffer.h.md
- changeset 1269
- e15ca477d448
- parent 1264
- 8ff604356af7
- child 1270
- 503f0ad94c6c
equal
deleted
inserted
replaced
| 1268:a84403b0a503 | 1269:e15ca477d448 |
|---|---|
| 208 CxBufferFlushConfig config); | 208 CxBufferFlushConfig config); |
| 209 | 209 |
| 210 size_t cxBufferFlush(CxBuffer *buffer); | 210 size_t cxBufferFlush(CxBuffer *buffer); |
| 211 ``` | 211 ``` |
| 212 | 212 |
| 213 <warning> | 213 With the function `cxBufferEnableFlushing()` you can configure a flushing strategy for the contents of the buffer. |
| 214 TODO: document | 214 |
| 215 </warning> | 215 Flushing, once enabled, may happen in the following cases: |
| 216 1. when data is written to the buffer, the capacity is insufficient, and `CX_BUFFER_AUTO_EXTEND` is _not_ enabled | |
| 217 2. when data is written to the buffer, and the required capacity exceeds the `threshold` configuration | |
| 218 3. when `cxBufferFlush()` is called explicitly | |
| 219 | |
| 220 > By combining the `CX_BUFFER_AUTO_EXTEND` flag and the `threshold` setting, | |
| 221 > you can create a buffer that initially starts with a small capacity, grows up to a certain threshold, | |
| 222 > and starts flushing only when that threshold is exceeded. | |
| 223 | |
| 224 Flushing happens by invoking the `wfunc` up to `blkmax` times, writing up to `blksize` bytes from the buffer to the `target` with each call. | |
| 225 The target might not accept all bytes (i.e. the `wfunc` return value indicates that fewer items have been written than requested), | |
| 226 in which case the remaining data remains in the buffer. | |
| 227 That means, the buffer is effectively [shifted](#shift-contents) left by the number of successfully flushed bytes. | |
| 228 | |
| 229 > When you write large amounts of data to a buffer, multiple flush cycles might happen. | |
| 230 > After the first flush operations completed, the reclaimed space in the buffer is filled first, but if that | |
| 231 > is not sufficient, another flush may be triggered within the same invocation of the write operation. | |
| 232 > | |
| 233 > That means, as much data is written to the buffer and/or flushed as possible, until neither the flush target, nor the buffer accept more data. | |
| 234 >{style="note"} | |
| 235 | |
| 236 > The function `cxBufferFlush()` simply returns zero when flushing was not enabled via `cxBufferEnableFlushing()`. | |
| 216 | 237 |
| 217 <seealso> | 238 <seealso> |
| 218 <category ref="apidoc"> | 239 <category ref="apidoc"> |
| 219 <a href="https://ucx.sourceforge.io/api/buffer_8h.html">buffer.h</a> | 240 <a href="https://ucx.sourceforge.io/api/buffer_8h.html">buffer.h</a> |
| 220 </category> | 241 </category> |
