libqb

NAME¶

qbrb.h - This implements a ring buffer that works in 'chunks', not bytes.

SYNOPSIS¶

#include <sys/types.h>
#include <stdint.h>

Macros¶

#define QB_RB_FLAG_CREATE 0x01
Create a ring buffer (rather than open and existing one). #define QB_RB_FLAG_OVERWRITE 0x02
New calls to qb_rb_chunk_write() will call qb_rb_chunk_reclaim() if there is not enough space. #define QB_RB_FLAG_SHARED_THREAD 0x04
The ringbuffer will be shared between pthreads not processes. #define QB_RB_FLAG_SHARED_PROCESS 0x08
The ringbuffer will be shared between processes. #define QB_RB_FLAG_NO_SEMAPHORE 0x10
Don't use semaphores, only atomic ops.

Typedefs¶

typedef struct qb_ringbuffer_s qb_ringbuffer_t

Functions¶

qb_ringbuffer_t * qb_rb_open (const char *name, size_t size, uint32_t flags, size_t shared_user_data_size)
Create the ring buffer with the given type. void qb_rb_close (qb_ringbuffer_t *rb)
Dereference the ringbuffer and, if we are the last user, destroy it. char * qb_rb_name_get (qb_ringbuffer_t *rb)
Get the name of the ringbuffer. void * qb_rb_shared_user_data_get (qb_ringbuffer_t *rb)
Get a point to user shared data area. ssize_t qb_rb_chunk_write (qb_ringbuffer_t *rb, const void *data, size_t len)
Write a chunk to the ring buffer. void * qb_rb_chunk_alloc (qb_ringbuffer_t *rb, size_t len)
Allocate space for a chunk of the given size. int32_t qb_rb_chunk_commit (qb_ringbuffer_t *rb, size_t len)
Finalize the chunk. ssize_t qb_rb_chunk_peek (qb_ringbuffer_t *rb, void **data_out, int32_t ms_timeout)
Read (without reclaiming) the last chunk. void qb_rb_chunk_reclaim (qb_ringbuffer_t *rb)
Reclaim the oldest chunk. ssize_t qb_rb_chunk_read (qb_ringbuffer_t *rb, void *data_out, size_t len, int32_t ms_timeout)
Read the oldest chunk into data_out. int32_t qb_rb_refcount_get (qb_ringbuffer_t *rb)
Get the reference count. ssize_t qb_rb_space_free (qb_ringbuffer_t *rb)
The amount of free space in the ring buffer. ssize_t qb_rb_space_used (qb_ringbuffer_t *rb)
The total amount of data in the buffer. ssize_t qb_rb_chunks_used (qb_ringbuffer_t *rb)
The total number of chunks in the buffer. ssize_t qb_rb_write_to_file (qb_ringbuffer_t *rb, int32_t fd)
Write the contents of the Ring Buffer to file. qb_ringbuffer_t * qb_rb_create_from_file (int32_t fd, uint32_t flags)
Load the saved ring buffer from file into tempory memory. int32_t qb_rb_chown (qb_ringbuffer_t *rb, uid_t owner, gid_t group)
Like 'chown', it changes the owner and group of the ringbuffer's resources. int32_t qb_rb_chmod (qb_ringbuffer_t *rb, mode_t mode)
Like 'chmod', it changes the mode of the ringbuffer's resources.

Detailed Description¶

This implements a ring buffer that works in 'chunks', not bytes.

So you write/read a complete chunk or not at all. There are two types of ring buffer: normal and overwrite. Overwrite will reclaim the oldest chunks inorder to make way for new ones, the normal version will refuse to write a new chunk if the ring buffer is full.

This implementation is capable of working across processes, but one process must only write and the other process read.

The read process will do the following:



     rb = qb_rb_open("test2", 2000, QB_RB_FLAG_SHARED_PROCESS|QB_RB_FLAG_CREATE);


     for (i = 0; i < 200; i++) {
try_read_again:


        l = qb_rb_chunk_read(rb, (void *)out, 32, 1000);


        if (l < 0) {


                goto try_read_again;


        }


     }


     ...


     qb_rb_close(rb);

The write process will do the following:



     rb = qb_rb_open("test2", 2000, QB_RB_FLAG_SHARED_PROCESS);


     for (i = 0; i < 200; i++) {
try_write_again:


        l = qb_rb_chunk_write(rb, &v, sizeof(v));


        if (l < sizeof(v)) {


                goto try_write_again;


        }


     }


     ...


     qb_rb_close(rb);

Author:

Angus Salkeld asalkeld@redhat.com

Macro Definition Documentation¶

#define QB_RB_FLAG_CREATE 0x01¶

Create a ring buffer (rather than open and existing one).

See also:

qb_rb_open()

#define QB_RB_FLAG_NO_SEMAPHORE 0x10¶

Don't use semaphores, only atomic ops. This mean that the timeout passed into qb_rb_chunk_read() will be ignored.

#define QB_RB_FLAG_OVERWRITE 0x02¶

New calls to qb_rb_chunk_write() will call qb_rb_chunk_reclaim() if there is not enough space. If this is not set then new writes will be refused.

See also:

qb_rb_open()

#define QB_RB_FLAG_SHARED_PROCESS 0x08¶

The ringbuffer will be shared between processes. This effects the type of locks/semaphores that are used.

See also:

qb_rb_open()

#define QB_RB_FLAG_SHARED_THREAD 0x04¶

The ringbuffer will be shared between pthreads not processes. This effects the type of locks/semaphores that are used.

See also:

qb_rb_open()

Typedef Documentation¶

typedef struct qb_ringbuffer_s qb_ringbuffer_t¶

Function Documentation¶

int32_t qb_rb_chmod (qb_ringbuffer_t * rb, mode_t mode)¶

Like 'chmod', it changes the mode of the ringbuffer's resources.

Parameters:

mode mode to change to
rb ringbuffer instance

Return values:

0 == ok
-errno for error

int32_t qb_rb_chown (qb_ringbuffer_t * rb, uid_t owner, gid_t group)¶

Like 'chown', it changes the owner and group of the ringbuffer's resources.

Parameters:

owner uid of the owner to change to
group gid of the group to change to
rb ringbuffer instance

Returns:

status (0 = ok, -errno for error)

void* qb_rb_chunk_alloc (qb_ringbuffer_t * rb, size_t len)¶

Allocate space for a chunk of the given size. If type == QB_RB_FLAG_OVERWRITE and NULL is returned, memory corruption of the memory file has occurred. The ringbuffer should be destroyed. If type == QB_RB_NORMAL then when there is not enough space it will return NULL.

Parameters:

rb ringbuffer instance
len (in) the size to allocate.

Returns:

pointer to chunk to write to, or NULL (if no space).

See also:

qb_rb_chunk_alloc()

int32_t qb_rb_chunk_commit (qb_ringbuffer_t * rb, size_t len)¶

Finalize the chunk.

Parameters:

rb ringbuffer instance
len (in) the size of the chunk.

ssize_t qb_rb_chunk_peek (qb_ringbuffer_t * rb, void ** data_out, int32_t ms_timeout)¶

Read (without reclaiming) the last chunk. This function is a way of accessing the next chunk without a memcpy(). You can read the chunk data in place.

Note:

This function will not 'pop' the chunk, you will need to call qb_rb_chunk_reclaim().

Parameters:

rb ringbuffer instance
data_out (out) a pointer to the next chunk to read (not copied).
ms_timeout (in) time to wait for new data.

Returns:

the size of the chunk (0 if buffer empty).

ssize_t qb_rb_chunk_read (qb_ringbuffer_t * rb, void * data_out, size_t len, int32_t ms_timeout)¶

Read the oldest chunk into data_out. This is the same as qb_rb_chunk_peek() memcpy() and qb_rb_chunk_reclaim().

Parameters:

rb ringbuffer instance
data_out (in/out) the chunk will be memcpy'ed into this.
len (in) the size of data_out.
ms_timeout the amount od time to wait for new data.

Returns:

the size of the chunk, or error.

void qb_rb_chunk_reclaim (qb_ringbuffer_t * rb)¶

Reclaim the oldest chunk. You will need to call this if using qb_rb_chunk_peek().

Parameters:

rb ringbuffer instance

ssize_t qb_rb_chunk_write (qb_ringbuffer_t * rb, const void * data, size_t len)¶

Write a chunk to the ring buffer. This simply calls qb_rb_chunk_alloc() and then qb_rb_chunk_commit().

Parameters:

rb ringbuffer instance
data (in) the data to write
len (in) the size of the chunk.

Returns:

the amount of bytes actually buffered (either len or -1).

See also:

qb_rb_chunk_alloc()

qb_rb_chunk_commit()

ssize_t qb_rb_chunks_used (qb_ringbuffer_t * rb)¶

The total number of chunks in the buffer.

Parameters:

rb ringbuffer instance

void qb_rb_close (qb_ringbuffer_t * rb)¶

Dereference the ringbuffer and, if we are the last user, destroy it. All files, mmaped memory, semaphores and locks will be destroyed.

Parameters:

rb ringbuffer instance

qb_ringbuffer_t* qb_rb_create_from_file (int32_t fd, uint32_t flags)¶

Load the saved ring buffer from file into tempory memory.

Parameters:

fd file with saved ringbuffer data.
flags same flags as passed into qb_rb_open()

Returns:

new ringbuffer instance

See also:

qb_rb_write_to_file()

char* qb_rb_name_get (qb_ringbuffer_t * rb)¶

Get the name of the ringbuffer.

Parameters:

rb ringbuffer instance

Returns:

name.

qb_ringbuffer_t* qb_rb_open (const char * name, size_t size, uint32_t flags, size_t shared_user_data_size)¶

Create the ring buffer with the given type. This creates allocates a ring buffer in shared memory.

Parameters:

name the unique name of this ringbuffer.
size the requested size.
flags or'ed flags
shared_user_data_size size for a shared data area.

Note:

the actual size will be rounded up to the next page size.

Returns:

a new ring buffer or NULL if there was a problem.

See also:

QB_RB_FLAG_CREATE, QB_RB_FLAG_OVERWRITE, QB_RB_FLAG_SHARED_THREAD, QB_RB_FLAG_SHARED_PROCESS

int32_t qb_rb_refcount_get (qb_ringbuffer_t * rb)¶

Get the reference count.

Parameters:

rb ringbuffer instance

Returns:

the number of references

void* qb_rb_shared_user_data_get (qb_ringbuffer_t * rb)¶

Get a point to user shared data area.

Note:

this is of size 'shared_user_data_size' passed into qb_rb_open()

Parameters:

rb ringbuffer instance

Returns:

pointer to shared data.

ssize_t qb_rb_space_free (qb_ringbuffer_t * rb)¶

The amount of free space in the ring buffer.

Note:

Some of this space will be consumed by the chunk headers.

Parameters:

rb ringbuffer instance

ssize_t qb_rb_space_used (qb_ringbuffer_t * rb)¶

The total amount of data in the buffer.

Note:

This includes the chunk headers (8 bytes per chunk).

Parameters:

rb ringbuffer instance

ssize_t qb_rb_write_to_file (qb_ringbuffer_t * rb, int32_t fd)¶

Write the contents of the Ring Buffer to file.

Parameters:

fd open file to write the ringbuffer data to.
rb ringbuffer instance

See also:

qb_rb_create_from_file()

Author¶

Generated automatically by Doxygen for libqb from the source code.

Fri Jan 13 2023

Version 1.0.3

Source file:	qbrb.h.3.en.gz (from libqb-devel 1.0.3-13.el8_7)
Source last updated:	2023-01-15 15:55:48
Converted to HTML:	2024-06-22 22:07:20