Ringbuf
A fixed-capacity FIFO of void *. rb_init allocates the slot array once, and a capacity of N holds N pointers.
Usage#
Initialize a caller-owned RingBuffer. Pass NULL for the destroy callback when the buffer does not own the payloads. Pass free, or another deallocator, when it should release payloads still in the buffer.
RingBuffer rb;
int value = 1;
void *data;
if (rb_init(&rb, 16, NULL) == 0) {
if (rb_push(&rb, &value) == 0 && rb_pop(&rb, &data) == 0) {
/* data == &value */
}
rb_destroy(&rb);
}
rb_destroy runs the callback on remaining payloads, frees the slot array, and zeros the handle. It does not free the RingBuffer. Destroy a live buffer before initializing it again. rb_init zeros the handle before allocating, so a second init drops the previous slot pointer. Concurrent use is unsupported. rb_push fails when the buffer is full. rb_force_push drops the oldest pointer instead, calls destroy on it when the callback is non-NULL, and does not return that pointer.
Structs#
RingBuffer#
typedef struct {
void **buf;
size_t capacity;
size_t count;
size_t head;
size_t tail;
void (*destroy)(void *data);
} RingBuffer;
The caller owns the handle and may read count and capacity. buf, head, tail, and destroy are the ring's storage. Change the ring through the functions.
Functions#
rb_init#
Allocates a slot array of capacity pointers and, on success, stores destroy. Returns 0 on success. Returns -1 if rb is NULL, if capacity is 0, or if allocation fails, including a size overflow in lf_reallocarray. A NULL rb writes nothing. Any other failure leaves a zeroed handle, does not store destroy, and is safe to pass to rb_destroy. Do not initialize a live buffer.
int rb_init(RingBuffer *rb, size_t capacity, void (*destroy)(void *));rb_destroy#
Calls destroy on remaining payloads when the callback is non-NULL, frees the slot array, and zeros the handle. Does not free the handle. A NULL handle is a no-op. A second destroy on a zeroed handle is a no-op.
void rb_destroy(RingBuffer *rb);rb_push#
Stores data at the tail. data may be NULL. Returns 0 on success. Returns -1 if rb is NULL, the slot array is NULL, or the buffer is full. On failure the buffer is unchanged.
int rb_push(RingBuffer *rb, void *data);rb_force_push#
Stores data at the tail. data may be NULL. If the buffer is full, drops the oldest pointer first and calls destroy on it when the callback is non-NULL. The dropped pointer is not returned. Returns 0 on success. Returns -1 if rb is NULL, the slot array is NULL, or capacity is 0. On failure the buffer is unchanged.
int rb_force_push(RingBuffer *rb, void *data);rb_pop#
Removes the front pointer and stores it in *data. Does not call destroy. The caller owns the popped pointer. Returns 0 on success. Returns -1 if rb or data is NULL or the buffer is empty. On failure the buffer is unchanged.
int rb_pop(RingBuffer *rb, void **data);rb_peek#
Returns the front pointer without removing it. Returns NULL if rb is NULL, the buffer is empty, or the front payload is NULL. A NULL return does not by itself mean the buffer is empty.
void *rb_peek(RingBuffer *rb);rb_clear#
Calls destroy on each remaining payload when the callback is non-NULL, then sets the buffer empty. Does not free the slot array, and capacity is unchanged. Pointers are discarded when destroy is NULL. A NULL handle is a no-op. The buffer can be reused.
void rb_clear(RingBuffer *rb);Macros#
These read fields of an initialized ring. They do not check for NULL.
rb_count#
#define rb_count(rb) ((rb)->count)rb_capacity#
#define rb_capacity(rb) ((rb)->capacity)rb_is_empty#
#define rb_is_empty(rb) ((rb)->count == 0)rb_is_full#
#define rb_is_full(rb) ((rb)->count == (rb)->capacity)