comparison: src/ucx/cx/buffer.h
src/ucx/cx/buffer.h
- changeset 645
- 0c85c4cd0dd8
- parent 621
- 956c03c25edd
equal
deleted
inserted
replaced
| 644:e96e92e3508f | 645:0c85c4cd0dd8 |
|---|---|
| 116 */ | 116 */ |
| 117 size_t blksize; | 117 size_t blksize; |
| 118 /** | 118 /** |
| 119 * The maximum number of blocks to flush in one cycle. | 119 * The maximum number of blocks to flush in one cycle. |
| 120 * | 120 * |
| 121 * @attention while it is guaranteed that cxBufferFlush() will not flush | 121 * @attention While it is guaranteed that cxBufferFlush() will not flush |
| 122 * more blocks, this is not necessarily the case for cxBufferWrite(). | 122 * more blocks, this is not necessarily the case for cxBufferWrite(). |
| 123 * After performing a flush cycle, cxBufferWrite() will retry the write | 123 * After performing a flush cycle, cxBufferWrite() will retry the write |
| 124 * operation and potentially trigger another flush cycle, until the | 124 * operation and potentially trigger another flush cycle, until the |
| 125 * flush target accepts no more data. | 125 * flush target accepts no more data. |
| 126 */ | 126 */ |
| 386 */ | 386 */ |
| 387 cx_attr_nonnull | 387 cx_attr_nonnull |
| 388 CX_EXPORT int cxBufferSeek(CxBuffer *buffer, off_t offset, int whence); | 388 CX_EXPORT int cxBufferSeek(CxBuffer *buffer, off_t offset, int whence); |
| 389 | 389 |
| 390 /** | 390 /** |
| 391 * Discards items from the end of the buffer. | |
| 392 * | |
| 393 * When the current position points to a byte that gets discarded, | |
| 394 * the position is set to the buffer size. | |
| 395 * | |
| 396 * @param buffer the buffer | |
| 397 * @param size the size of one item | |
| 398 * @param nitems the number of items to discard | |
| 399 * @return the actual number of discarded items | |
| 400 */ | |
| 401 cx_attr_nonnull | |
| 402 CX_EXPORT size_t cxBufferPop(CxBuffer *buffer, size_t size, size_t nitems); | |
| 403 | |
| 404 /** | |
| 391 * Clears the buffer by resetting the position and deleting the data. | 405 * Clears the buffer by resetting the position and deleting the data. |
| 392 * | 406 * |
| 393 * The data is deleted by zeroing it with a call to memset(). | 407 * The data is deleted by zeroing it with a call to memset(). |
| 394 * If you do not need that, you can use the faster cxBufferReset(). | 408 * If you do not need that, you can use the faster cxBufferReset(). |
| 395 * | 409 * |
| 423 * @retval false otherwise | 437 * @retval false otherwise |
| 424 */ | 438 */ |
| 425 cx_attr_nonnull cx_attr_nodiscard | 439 cx_attr_nonnull cx_attr_nodiscard |
| 426 CX_EXPORT bool cxBufferEof(const CxBuffer *buffer); | 440 CX_EXPORT bool cxBufferEof(const CxBuffer *buffer); |
| 427 | 441 |
| 442 /** | |
| 443 * Ensures that the buffer has the required capacity. | |
| 444 * | |
| 445 * If the current capacity is not sufficient, the buffer will be extended. | |
| 446 * | |
| 447 * This function will reserve no more bytes than requested, in contrast to | |
| 448 * cxBufferMinimumCapacity(), which may reserve more bytes to improve the | |
| 449 * number of future necessary reallocations. | |
| 450 * | |
| 451 * @param buffer the buffer | |
| 452 * @param capacity the required capacity for this buffer | |
| 453 * @retval zero the capacity was already sufficient or successfully increased | |
| 454 * @retval non-zero on allocation failure | |
| 455 * @see cxBufferShrink() | |
| 456 * @see cxBufferMinimumCapacity() | |
| 457 */ | |
| 458 cx_attr_nonnull | |
| 459 CX_EXPORT int cxBufferReserve(CxBuffer *buffer, size_t capacity); | |
| 428 | 460 |
| 429 /** | 461 /** |
| 430 * Ensures that the buffer has a minimum capacity. | 462 * Ensures that the buffer has a minimum capacity. |
| 431 * | 463 * |
| 432 * If the current capacity is not sufficient, the buffer will be extended. | 464 * If the current capacity is not sufficient, the buffer will be generously |
| 465 * extended. | |
| 433 * | 466 * |
| 434 * The new capacity will be a power of two until the system's page size is reached. | 467 * The new capacity will be a power of two until the system's page size is reached. |
| 435 * Then, the new capacity will be a multiple of the page size. | 468 * Then, the new capacity will be a multiple of the page size. |
| 436 * | 469 * |
| 437 * @param buffer the buffer | 470 * @param buffer the buffer |
| 438 * @param capacity the minimum required capacity for this buffer | 471 * @param capacity the minimum required capacity for this buffer |
| 439 * @retval zero the capacity was already sufficient or successfully increased | 472 * @retval zero the capacity was already sufficient or successfully increased |
| 440 * @retval non-zero on allocation failure | 473 * @retval non-zero on allocation failure |
| 474 * @see cxBufferReserve() | |
| 441 * @see cxBufferShrink() | 475 * @see cxBufferShrink() |
| 442 */ | 476 */ |
| 443 cx_attr_nonnull | 477 cx_attr_nonnull |
| 444 CX_EXPORT int cxBufferMinimumCapacity(CxBuffer *buffer, size_t capacity); | 478 CX_EXPORT int cxBufferMinimumCapacity(CxBuffer *buffer, size_t capacity); |
| 445 | 479 |
| 455 * If the #CX_BUFFER_COPY_ON_WRITE or #CX_BUFFER_COPY_ON_EXTEND flag is set, | 489 * If the #CX_BUFFER_COPY_ON_WRITE or #CX_BUFFER_COPY_ON_EXTEND flag is set, |
| 456 * this function does nothing. | 490 * this function does nothing. |
| 457 * | 491 * |
| 458 * @param buffer the buffer | 492 * @param buffer the buffer |
| 459 * @param reserve the number of bytes that shall remain reserved | 493 * @param reserve the number of bytes that shall remain reserved |
| 494 * @see cxBufferReserve() | |
| 460 * @see cxBufferMinimumCapacity() | 495 * @see cxBufferMinimumCapacity() |
| 461 */ | 496 */ |
| 462 cx_attr_nonnull | 497 cx_attr_nonnull |
| 463 CX_EXPORT void cxBufferShrink(CxBuffer *buffer, size_t reserve); | 498 CX_EXPORT void cxBufferShrink(CxBuffer *buffer, size_t reserve); |
| 464 | 499 |
