NAME
vrb - virtual ring buffer
LIBRARY
-lvrb
HEADERS
#include <vrb.h>
DESCRIPTION
A virtual ring buffer is a character FIFO queue with the special
property that any sequence of characters, either the data present in
the buffer, or any empty space, may be accessed as a single contiguous
block of memory, eliminating the need to deal with breaks in string
continuity to test for wraparounds or splits, and allowing the direct
use of string construction or parsing tools, such as snprintf(3), or
sscanf(3).
As a character FIFO queue, data comes out in the same order as it was
put it. Unlike other FIFO queues and ring buffers, which have to chop
up the data into pieces, and/or copy the data between caller space and
buffer space, the virtual ring buffer allows the calling program to
access the buffer space directly because the data to be accessed to get
from the buffer, or the space to be accessed to put data into the
buffer, is always addressesable as a single linear contiguous range of
addresses. When the caller is going to have data to place into the
buffer, it obtains the pointer and length of available space, and can
place the data directly into the buffer, usually eliminating one step
of copying. For example, the caller can use the pointer to read data
directly into the buffer. Or it can call functions, such as
snprintf(3), to make conversions directly. Likewise, when the caller
is going to extract data from the buffer, it obtains the pointer and
length of the data, and can directly address it in place.
Once data has been placed into empty space, or extracted from a data
space, the caller indicates how much was put in or taken out, and
pointers are then updated accordingly.
The VRB functions never copy data around within the buffer. The
property of always have a linear range of memory for both all the data
in the buffer as well as all the empty space in the buffer is
implemented by memory mapping two virtual memory ranges to the same
memory object, and making those two ranges immediately adjacent. Thus
anything in the first range is seen identically in the second range. A
span of data or empty space that would wrap around is now simply
extended from the first range into the second range.
FUNCTIONS
vrb_new
Create a new virtual ring buffer.
vrb_new_opt
Create a new virtual ring buffer with options.
vrb_destroy
Destroy an allocated virtual ring buffer.
vrb_init
Initialize a virtual ring buffer in a static struct.
vrb_init_opt
Initialize a virtual ring buffer in a static struct with
options.
vrb_uninit
Uninitialize a virtual ring buffer in a static struct.
vrb_capacity
Obtain the total buffer capacity of a VRB.
vrb_data_len
Obtain the length of data in the buffer.
vrb_data_ptr
Obtain the pointer to the data in the buffer.
vrb_space_len
Obtain the length of empty space in the buffer.
vrb_space_ptr
Obtain the pointer to the empty space in the buffer.
vrb_is_empty
Determine if the buffer is currently empty.
vrb_is_full
Determine if the buffer is currently full.
vrb_is_not_empty
Determine if there is at least some data in the buffer.
vrb_is_not_full
Determine if there is at least some empty space in the buffer.
vrb_give
Indicate how much empty space had data put in by the caller.
vrb_take
Indicate how much data in the buffer was used by the caller.
vrb_get
Copy data from the virtual ring buffer to a caller location.
vrb_get_min
Copy a minimum amount of data from the VRB only if it will fit.
vrb_put
Copy data from a caller location to the virtual ring buffer.
vrb_put_all
Copy data to the VRB only if all of it will fit.
vrb_read
read(2) data into a VRB until EOF or full, or I/O would block.
vrb_read_min
read(2) a minimum amount of data into a VRB until EOF or full,
or I/O would block.
vrb_write
write(2) data from a VRB until empty, or I/O would block.
vrb_resize
Change the size of a VRB while keeping any data in the buffer.
vrb_move
Move data from one VRB to another.
SEE ALSO
vrb_capacity(3), vrb_data_len(3), vrb_data_ptr(3), vrb_destroy(3),
vrb_get(3), vrb_get_min(3), vrb_give(3), vrb_init(3), vrb_init_opt(3),
vrb_is_empty(3), vrb_is_full(3), vrb_is_not_empty(3),
vrb_is_not_full(3), vrb_move(3), vrb_new(3), vrb_new_opt(3),
vrb_put(3), vrb_put_all(3), vrb_read(3), vrb_read_min(3),
vrb_resize(3), vrb_space_len(3), vrb_space_ptr(3), vrb_take(3),
vrb_uninit(3), vrb_write(3), vrb_write_min(3)