NAME¶
vrb - virtual ring buffer
LIBRARY¶
-lvrb
#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)