rb_init(3)

bofc manual pages

rb_init(3)



 

NAME

rb_new, rb_init - initializes new ring buffer  

SYNOPSIS

#include <librb.h>

struct rb *rb_new(size_t count, size_t object_size, unsigned long flags);
struct rb *rb_init(size_t count, size_t object_size, unsigned long flags, void *mem);  

DESCRIPTION

rb_new(3) creates new ring buffer object with maximum count elements, each of object_size bytes with flags. Handle to ring buffer is returned on successfull initalization. Loosing this pointer will lead to memory leak.

count and object_size describes buffer sizes. Library will allocate on callers heap (count * object_size) bytes. count must be a power of two number (ie. 4, 64, 1024), as library tries to avoid unecessary conditional jump to improve performance. object_size determines how big a single element is. This value is constant for lifetime of a ring buffer. object_size might be for example sizeof(uint8_t) or sizeof(uint32_t) or even sizeof(struct my_msg). In short, object_size should be a size of an object, ring buffer will hold. You should not write nor read objects of different size than created one, as this will lead to undefined behaviour or even crashes.

rb_init(3) can be used if dynamic allocation is not supported or it needs to be avoided. Functions works same as rb_new(3) but does not perform any allocation and user is responsible to pass pointer to mem that is big enough to hold rb header and any data that could be inserted into buffer. Information about header size can be read from rb_header_size(3) function, and data length can be calculated with formula (count * object_size). mem can be whatever continous memory like array on stack, or some custom allocation. Check example to see how to use it in practice.

Functions can accept following flags

O_NONBLOCK
if set, all calls to library functions will return immediately even if buffer is full or empty. Proper functions will then return with errno set to EAGAIN and number of elements actually commited. This is default behaviour when O_MULTITHREAD flag was not passed and librb is working in single thread mode.
O_MULTITHREAD
this can be set only when library has been compiled with ENABLE_THREADS, otherwise error will be returned. If set, librb functions will be using pthreads to provide synchronization of threads accessing rb object.
 

RETURN VALUES

If no errors have been detected, function will return pointer to newly created ring buffer, otherwise NULL is returned.  

ERRORS

EINVAL
count is not a power of two number (like 4, 64, 1024).
ENOSYS
O_MULTITHREAD was set but librb was not compiled with pthread support.
ENOMEM
couldn't allocate memory for given count and object_size
 

EXAMPLES


    #include <rb.h>
    #include <stdio.h>


    struct msg
    {
        int a;
        int b;
    };


    int main(void)
    {
        struct msg msg;
        struct rb *rb;
        /* allocate memory on stack for rb header and 8 elements of msg */
        unsigned char buf[rb_header_size() + 8 * sizeof(msg)];


        /* initialize ring buffer with custom allocated memory */
        rb = rb_init(8, sizeof(msg), 0, buf);


        /* rb can be now accessed as usuall */


        /* when work on rb is done, it needs to be cleaned up */
        rb_cleanup(rb);


        return 0;
    }  

NOTES

Algorithm used in this buffer requires one element to be always empty to distinguish situations when buffer is full or empty and as such, rb object can effectively hold count - 1 elements in the buffer.  

SEE ALSO

rb_overview(7), rb_destroy(3), rb_cleanup(3), rb_discard(3), rb_stop(3), rb_stop_signal(3), rb_read(3), rb_recv(3), rb_write(3), rb_send(3), rb_posix_read(3), rb_posix_recv(3), rb_posix_write(3), rb_posix_send(3), rb_clear(3), rb_count(3), rb_space(3), rb_header_size(3), rb_array_size(3), rb_version(3)

bofc.pl

23 October 2018 (v1.1.0)

rb_init(3)