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

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

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 test-result-svg
  • power4-polarhome-aix-7.1 test-result-svg
  • i686-bofc-freebsd-11.1 test-result-svg
  • i686-bofc-netbsd-8.0 test-result-svg
  • i686-bofc-openbsd-6.2 test-result-svg
  • x86_64-bofc-solaris-11.3 test-result-svg
  • i686-bofc-linux-gnu-4.9 test-result-svg
  • i686-bofc-linux-musl-4.9 test-result-svg
  • i686-bofc-linux-uclibc-4.9 test-result-svg
  • x86_64-bofc-linux-gnu-4.9 test-result-svg
  • x86_64-bofc-linux-musl-4.9 test-result-svg
  • x86_64-bofc-linux-uclibc-4.9 test-result-svg
  • x86_64-bofc-debian-9 test-result-svg
  • x86_64-bofc-centos-7 test-result-svg
  • x86_64-bofc-fedora-28 test-result-svg
  • x86_64-bofc-opensuse-15 test-result-svg
  • x86_64-bofc-rhel-7 test-result-svg
  • x86_64-bofc-slackware-14.2 test-result-svg
  • x86_64-bofc-ubuntu-18.04 test-result-svg

machine tests

  • aarch64-bofc-linux-gnu test-result-svg
  • armv5te926-bofc-linux-gnueabihf test-result-svg
  • armv6j1136-bofc-linux-gnueabihf test-result-svg
  • armv7a15-bofc-linux-gnueabihf test-result-svg
  • armv7a9-bofc-linux-gnueabihf test-result-svg
  • mips-bofc-linux-gnu test-result-svg

sanitizers

  • -fsanitize=address test-result-svg
  • -fsanitize=leak test-result-svg
  • -fsanitize=thread test-result-svg
  • -fsanitize=undefined test-result-svg

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: http://git.kurwinet.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