.TH "rb_new" "3" " 5 February 2018 (v3.0.0)" "bofc.pl"
.SH NAME
.PP
.B rb_new
- create new ring buffer
.SH SYNOPSIS
.PP
.BI "#include <librb.h>"
.PP
.BI "struct rb *rb_new(size_t " count ", size_t " object_size ", \
unsigned long " flags ");"
.SH DESCRIPTION
.PP
.BR rb_new (3)
creates new ring buffer object with maximum
.I count
elements, each of
.I object_size
bytes with
.IR flags.
Handle to ring buffer is returned on successfull initalization.
Loosing this pointer will lead to memory leak.
.PP
.I count
and
.I object_size
describes buffer sizes.
Library will allocate on callers heap
.RI ( count
*
.IR object_size )
bytes.
.Icount
must be a power of two number (ie. 4, 64, 1024), as library tries to avoid
unecessary conditional jump to improve performance.
.I object_size
determines how big a single element is.
This value is constant for lifetime of a ring buffer.
.I object_size
might be for example
.B sizeof(uint8_t)
or
.B sizeof(uint32_t)
or even
.BR "sizeof(struct my_msg)" .
In short,
.I 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.
.PP
Function can accept following
.I flags
.TP
.B 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
.B EAGAIN
and number of elements actually commited.
This is default behaviour when
.B O_MULTITHREAD
flag was
.B not
passed and
.B librb
is working in single thread mode.
.TP
.B O_MULTITHREAD
this can be set only when library has been compiled with
.BR ENABLE_THREADS ,
otherwise error will be returned. If set,
.B librb
functions will be using pthreads to provide synchronization of threads accessing
.I rb
object.
.SH RETURN VALUES
.PP
If no errors have been detected, function will return pointer to newly created
ring buffer, otherwise NULL is returned.
.SH ERRORS
.TP
.B EINVAL
.I count
is not a power of two number (like 4, 64, 1024).
.TP
.B ENOSYS
.B O_MULTITHREAD
was set but
.B librb
was not compiled with pthread support.
.TP
.B ENOMEM
couldn't allocate memory for given
.I count
and
.I object_size
.SH SEE ALSO
.PP
.BR rb_overview (7),
.BR rb_destroy (3),
.BR rb_discard (3),
.BR rb_stop (3),
.BR rb_read (3),
.BR rb_recv (3),
.BR rb_write (3),
.BR rb_send (3),
.BR rb_clear (3),
.BR rb_count (3),
.BR rb_space (3),
.BR rb_version (3)