| qbrb.h(3) | libqb | qbrb.h(3) |
qbrb.h - This implements a ring buffer that works in 'chunks', not bytes.
#include <sys/types.h>
#include <stdint.h>
#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.
typedef struct qb_ringbuffer_s qb_ringbuffer_t
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.
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:
Create a ring buffer (rather than open and existing one).
See also:
Don't use semaphores, only atomic ops. This mean that the timeout passed into qb_rb_chunk_read() will be ignored.
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:
The ringbuffer will be shared between processes. This effects the type of locks/semaphores that are used.
See also:
The ringbuffer will be shared between pthreads not processes. This effects the type of locks/semaphores that are used.
See also:
Like 'chmod', it changes the mode of the ringbuffer's resources.
Parameters:
Return values:
Like 'chown', it changes the owner and group of the ringbuffer's resources.
Parameters:
Returns:
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:
Returns:
See also:
Finalize the chunk.
Parameters:
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:
Parameters:
Returns:
Read the oldest chunk into data_out. This is the same as qb_rb_chunk_peek() memcpy() and qb_rb_chunk_reclaim().
Parameters:
Returns:
Reclaim the oldest chunk. You will need to call this if using qb_rb_chunk_peek().
Parameters:
Write a chunk to the ring buffer. This simply calls qb_rb_chunk_alloc() and then qb_rb_chunk_commit().
Parameters:
Returns:
See also:
qb_rb_chunk_commit()
The total number of chunks in the buffer.
Parameters:
Dereference the ringbuffer and, if we are the last user, destroy it. All files, mmaped memory, semaphores and locks will be destroyed.
Parameters:
Load the saved ring buffer from file into tempory memory.
Parameters:
Returns:
See also:
Get the name of the ringbuffer.
Parameters:
Returns:
Create the ring buffer with the given type. This creates allocates a ring buffer in shared memory.
Parameters:
Note:
Returns:
See also:
Get the reference count.
Parameters:
Returns:
Get a point to user shared data area.
Note:
Parameters:
Returns:
The amount of free space in the ring buffer.
Note:
Parameters:
The total amount of data in the buffer.
Note:
Parameters:
Write the contents of the Ring Buffer to file.
Parameters:
See also:
Generated automatically by Doxygen for libqb from the source code.
| Fri Apr 26 2019 | Version 1.0.5 |