Mercurial > hg > ucx / changeset

--- 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);
 ```
 
-<warning>
-TODO: document
-</warning>
+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()`.
 
 <seealso>
 <category ref="apidoc">