# HG changeset patch # User Mike Becker # Date 1743528064 -7200 # Node ID e15ca477d448b4d2120d8a70644ff4b0d24c0e00 # Parent a84403b0a5037994305fc6f60272bfcede3b120b document the flushing feature for the buffer relates #451 diff -r a84403b0a503 -r e15ca477d448 docs/Writerside/topics/buffer.h.md --- a/docs/Writerside/topics/buffer.h.md Mon Mar 31 19:39:42 2025 +0200 +++ b/docs/Writerside/topics/buffer.h.md Tue Apr 01 19:21:04 2025 +0200 @@ -210,9 +210,30 @@ size_t cxBufferFlush(CxBuffer *buffer); ``` - -TODO: document - +With the function `cxBufferEnableFlushing()` you can configure a flushing strategy for the contents of the buffer. + +Flushing, once enabled, may happen in the following cases: +1. when data is written to the buffer, the capacity is insufficient, and `CX_BUFFER_AUTO_EXTEND` is _not_ enabled +2. when data is written to the buffer, and the required capacity exceeds the `threshold` configuration +3. when `cxBufferFlush()` is called explicitly + +> By combining the `CX_BUFFER_AUTO_EXTEND` flag and the `threshold` setting, +> you can create a buffer that initially starts with a small capacity, grows up to a certain threshold, +> and starts flushing only when that threshold is exceeded. + +Flushing happens by invoking the `wfunc` up to `blkmax` times, writing up to `blksize` bytes from the buffer to the `target` with each call. +The target might not accept all bytes (i.e. the `wfunc` return value indicates that fewer items have been written than requested), +in which case the remaining data remains in the buffer. +That means, the buffer is effectively [shifted](#shift-contents) left by the number of successfully flushed bytes. + +> When you write large amounts of data to a buffer, multiple flush cycles might happen. +> After the first flush operations completed, the reclaimed space in the buffer is filled first, but if that +> is not sufficient, another flush may be triggered within the same invocation of the write operation. +> +> 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. +>{style="note"} + +> The function `cxBufferFlush()` simply returns zero when flushing was not enabled via `cxBufferEnableFlushing()`.