qbrb.h File Reference

This implements a ring buffer that works in "chunks" not bytes. More...

#include <sys/types.h>
#include <stdint.h>
Include dependency graph for qbrb.h:

Defines

#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_tqb_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_tqb_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>

Define 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()
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines

Generated on 18 Mar 2016 for libqb by  doxygen 1.6.1