About
This is library that provides fast, easy to use ring buffer. It's interface is very similar to read/write interface from POSIX. It also provides optional thread awarness and thread safety for concurrent access. If used without threads there are 0 (zero) syscalls, everything is done in user's process without kernel interfering and steeling precious cpu cycles. Altough librb provides some more functions, it can be operated using 4 basic functions
- rb_new - creates new ring buffer
- rb_read - reads from the ring buffer
- rb_write - writes to the ring buffer
- rb_destroy - destroys ring buffer
Additional functions are:
- rb_init - initializes new ring buffer but does not use dynamic allocation
- rb_cleanup - cleans up whatever has been initialized with rb_init
- rb_recv - reads from the ring buffer but also accepts flags
- rb_send - writes to the ring buffer but also accepts flags
- rb_clear - removes all elements from the buffer
- rb_count - returns number of elements in the buffer
- rb_space - returns number of free space for number of elements
- rb_stop - forces all threads to exit rb_write and rb_read functions
- rb_discard - allows to quickly discard part of buffers data
- rb_header_size - get size of internal struct with buffer information
- rb_version - get version of library that is used
Extra functions enabled on POSIX compliant systems. These functions are provided for convenience, but can also be used to limit copying operations from socket to rb:
- rb_posix_read - reads from the ring buffer directly to provided socket
- rb_posix_write - writes to the ring buffer directly from socket
- rb_posix_recv - reads from the ring buffer directly to provided socket but also accepts flags
- rb_posix_send - writes to the ring buffer directly from socket but also accepts flags
Downloads
Released binary packages and source tarballs can be downloaded from https://librb.bofc.pl/downloads.html
Dependencies
Library is C89 complaint and will work under any POSIX environment that implements pthreads and libc. If target system doesn't have POSIX, no worries. in such case the only requirenment is C89 compiler and libc (no threads then though. To build without threads, add --disable-threads to configure script.
Test results
Note: tests are done on master branch, on release tags, all tests always pass.
operating system tests
- parisc-polarhome-hpux-11.11
- power4-polarhome-aix-7.1
- i686-bofc-freebsd-11.1
- i686-bofc-netbsd-8.0
- i686-bofc-openbsd-6.2
- x86_64-bofc-solaris-11.3
- i686-bofc-linux-gnu-4.9
- i686-bofc-linux-musl-4.9
- i686-bofc-linux-uclibc-4.9
- x86_64-bofc-linux-gnu-4.9
- x86_64-bofc-linux-musl-4.9
- x86_64-bofc-linux-uclibc-4.9
- x86_64-bofc-debian-9
- x86_64-bofc-centos-7
- x86_64-bofc-fedora-28
- x86_64-bofc-opensuse-15
- x86_64-bofc-rhel-7
- x86_64-bofc-slackware-14.2
- x86_64-bofc-ubuntu-18.04
machine tests
- aarch64-bofc-linux-gnu
- armv5te926-bofc-linux-gnueabihf
- armv6j1136-bofc-linux-gnueabihf
- armv7a15-bofc-linux-gnueabihf
- armv7a9-bofc-linux-gnueabihf
- mips-bofc-linux-gnu
sanitizers
- -fsanitize=address
- -fsanitize=leak
- -fsanitize=thread
- -fsanitize=undefined
License
Library is licensed under BSD 2-clause license. See LICENSE file for details
Compiling and installing
Project uses standard automake so to build you need to
$ ./autogen.sh
$ ./configure
$ make
# make install
./autogen.sh must be called only when ./configure is not available - like when cloning from git. If you downloaded tar.gz tarbal, this can be ommited.
for tests run:
$ make check
to build examples, simply run, compiled examples will be shows in ./examples directory
$ make examples
Examples
Example codes can be found here: https://git.bofc.pl/librb/tree/examples
Build time options
Some fatures can be disabled to save some code size or when particular feature is not available on target system. All options are passed to configure script in common way ./configure --enable-feature. Run ./configure --help to see help on that matter. For every --enable option it is also valid to use --disable-feature. Enabling option here does not mean it will be hard enabled in runtime, this will just give you an option to enable these settings later in runtime.
--enable-threads (default: enable)
When set, you will be able to create rb object with O_MULTITHREAD flag, which will enable multi-thread safety for that rb object. This needs your system to support pthreads.
--enable-posix-calls (default: enable)
When enabled, you will be able to read/write data directly from/into posix file descriptor (which may be a file on disk, serial device or network socket).
--enable-trace (default: disable)
When enabled, library will print tons of logs, use this only when debugging this library. When disabled, rb will be totally silent.
Functions description
For detailed functions description please check man pages
Contact
Michał Łyszczek michal.lyszczek@bofc.pl
See also
- mtest unit test framework librb uses
- git repository to browse code online
- continous integration for project
- polarhome nearly free shell accounts for virtually any unix there is.