Provided by: libqb-dev_1.0.1-1ubuntu1_amd64 
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 ringbuffers resources.
int32_t qb_rb_chmod (qb_ringbuffer_t *rb, mode_t mode)
Like 'chmod' it changes the mode of the ringbuffers 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 prrocess 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 ringbuffers 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 ringbuffers 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 occured. 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.