ucx: comparison docs/Writerside/topics/buffer.h.md

-:8fd491bc2940
+:25ead2ffb9b5
 This allows the use of `cx_stream_copy()` (see [](streams.h.md)) to copy contents from one buffer to another,
 or from a file or network stream to the buffer and vice versa.
 More features for convenient use of the buffer can be enabled, like automatic memory management,
-automatic resizing of the buffer space, or automatic flushing of contents.
+or automatic resizing of the buffer space.
 The functions `cxBufferRead()` and `cxBufferWrite()` are `cx_read_func` and `cx_write_func` compatible,
 which in turn have a compatible signature to `fread()` and `fwrite()`.
 However, due to the different pointer type the function pointers do not type check out of the box.
 For convenience, the macros `cxBufferReadFunc` and `cxBufferWriteFunc` are defined, which perform the necessary cast.
 ## Capacity Management
 ```C
 #include <cx/buffer.h>
+int cxBufferMaximumCapacity(CxBuffer *buffer, size_t capacity);
+int cxBufferMinimumCapacity(CxBuffer *buffer, size_t capacity);
 int cxBufferReserve(CxBuffer *buffer, size_t capacity);
-int cxBufferMinimumCapacity(CxBuffer *buffer, size_t capacity);
 void cxBufferShrink(CxBuffer *buffer, size_t reserve);
 ```
+The function `cxBufferMaximumCapacity()` specifies an upper limit for auto-growing the buffer's capacity.
+If the new threshold is smaller than the current capacity, this function fails and returns non-zero.
 The function `cxBufferMinimumCapacity()` guarantees a buffer capacity of _at least_ `capacity`.
 It will grow the capacity in powers of two until the system's page size is reached.
 Then, the new capacity will be a multiple of the page size.
-The function returns non-zero if increasing the capacity was attempted unsuccessfully.
+The function returns non-zero if increasing the capacity was attempted unsuccessfully;
+that includes attempts to specify a minimum capacity that exceeds the maximum capacity.
 The function `cxBufferReserve()`, on the other hand, will reallocate the buffer's space to match exactly the requested `capacity`
 and the contents are truncated if required.
 You should use `cxBufferReserve()` when you know precisely the required capacity beforehand
 If the current capacity is not larger than the size plus the reserve bytes, the function will do nothing.
 > If the buffer is in a copy-on-write state, `cxBufferMinimumCapacity()` will perform the copy-on-write action
 > before reallocating the space.
 > The function `cxBufferShrink()` on the other hand does _nothing_ when the buffer is in a copy-on-write state,
-> because it does not make much sense to copy the memory just to have it in a smaller memory region.
+> because it makes little sense to copy the memory just to have it in a smaller memory region.
 ## Write
 ```C
 #include <cx/buffer.h>
 The primary function for writing to a buffer is `cxBufferWrite()`
 which writes up to `nitems` with `size` bytes each from the memory pointed to by `ptr` to the buffer.
 When the capacity of the buffer is not sufficient and the `CX_BUFFER_AUTO_EXTEND` is not set in the buffer,
 items that do not fit into the buffer are discarded.
-The function always returns the actual number of items successfully written.
+The function then returns the actual number of items successfully written.
 This equals the number of bytes if and only if `size=1`.
+If `CX_BUFFER_AUTO_EXTEND` is set, the buffer is grown to it's maximum capacity
+(see `cxBufferMaximumCapacity()` in [](#capacity-management)).
+In case the allocation for auto-extension fails, the function immediately returns zero and does not write any data.
 The function `cxBufferPut()` is a `putc()`-like wrapper for `cxBufferWrite()` which writes the character `c`,
 converted to an `unsigned char` to the buffer.
 Just like `putc()` this function returns the written character on success, and `EOF` on failure,
 but it does _not_ set `errno` on failure.
 On the other hand, `cxBufferTerminate()` writes a zero-byte at the current position,
 effectively creating a zero-terminated string whose size equals the buffer size.
 The function `cxBufferAppend()` writes the data to the end of the buffer (given by its size) regardless of the current position,
 and it also does _not_ advance the position.
-If the write operation triggered a [flush](#flushing), however, the position will be shifted left alongside the shifted buffer contents.
-In case the data at which the current position points gets flushed, the new position will be zero.
 ## Read
 ```C
 #include <cx/buffer.h>
 (which means, `cxBufferEof()` returns `true` after the operation).
 The functions `cxBufferShiftRight()` and `cxBufferShiftLeft()` accept a larger (but in both cases positive) shift offset,
 which usually makes little sense on a 64-bit platform where `off_t` is already large enough to represent any reasonable offset.
 You may, however, still use those functions to express more explicitly in your code in which direction you want the contents to be shifted.
-## Flushing
-```C
-#include <cx/buffer.h>
-typedef struct cx_buffer_flush_config_s {
-size_t threshold;
-size_t blksize;
-size_t blkmax;
-void *target;
-cx_write_func wfunc;
-} CxBufferFlushConfig;
-int cxBufferEnableFlushing(CxBuffer *buffer,
-CxBufferFlushConfig config);
-size_t cxBufferFlush(CxBuffer *buffer);
-```
-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 are completed, the reclaimed space in the buffer is filled first, but if that
-> is not enough, 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">
 <a href="https://ucx.sourceforge.io/api/buffer_8h.html">buffer.h</a>
 </category>

Mercurial > hg > ucx / file comparison

comparison: docs/Writerside/topics/buffer.h.md

docs/Writerside/topics/buffer.h.md