ringbuffer.h File Reference

#include <stddef.h>

Go to the source code of this file.

Data Structures
struct	ringbuffer_t
	Ring buffer structure. More...

Typedefs
typedef void	free_func_t(void *ptr)
	prototype for a "free" function (used as ringbuffer_t member)

Functions
void	ringbuffer_init (ringbuffer_t *rb, size_t capacity, free_func_t free_func)
	"constructor", prepare a ringbuffer_t before usage More...
void	ringbuffer_done (ringbuffer_t *rb)
	"destructor", free up a ringbuffer_t's resources after you're done
void	ringbuffer_push (ringbuffer_t *rb, void *element)
	push an element pointer to the ring buffer (new "head" entry)
void	ringbuffer_push_copy (ringbuffer_t *rb, void *buffer, size_t size)
	push a copy of a (temporary) memory buffer. More...
void	ringbuffer_pop (ringbuffer_t *rb)
	discard the oldest entry ("tail" element) from the buffer. More...
void	ringbuffer_clear (ringbuffer_t *rb)
	remove (pop) all entries from the buffer, until it's empty again (count == 0)
void	ringbuffer_resize (ringbuffer_t *rb, size_t new_capacity)
	resize the ring buffer (assign a new capacity). More...
void *	ringbuffer_element (ringbuffer_t *rb, size_t index)
	Retrieve the n-th entry (element pointer) from the ring buffer. More...
void *	ringbuffer_tail (ringbuffer_t *rb)
	shortcut to retrieve "tail" element More...
void *	ringbuffer_head (ringbuffer_t *rb)
	shortcut to retrieve "head" element

Function Documentation

void* ringbuffer_element	(	ringbuffer_t *	rb,
		size_t	index
	)

Retrieve the n-th entry (element pointer) from the ring buffer.

Any invalid index will result in a NULL return value. Specifically, with an empty buffer you'll always get back NULL (for any value of index).

Note

Here the index parameter is relative to the current buffer position - meaning ringbuffer_element(rb, 0) will always refer to the "tail", and ringbuffer_element(rb, count - 1) is the "head" entry.

void ringbuffer_init	(	ringbuffer_t *	rb,
		size_t	capacity,
		free_func_t	free_func
	)

"constructor", prepare a ringbuffer_t before usage

Parameters

rb	the ring buffer to use
capacity	maximum number of elements (pointers) the buffer can hold
free_func	free function to use on an element before discarding it. optional, may be NULL

void ringbuffer_pop

(

ringbuffer_t *

rb

)

discard the oldest entry ("tail" element) from the buffer.

This decrements count (i.e. frees up one 'slot'), and moves the tail pointer.

void ringbuffer_push_copy	(	ringbuffer_t *	rb,
		void *	buffer,
		size_t	size
	)

push a copy of a (temporary) memory buffer.

This is a helper function that will first do a malloc(size) and then copy the buffer contents. You may use this if you wish to ringbuffer_push() some "volatile" data, where the buffer pointer gets invalidated afterwards.

void ringbuffer_resize	(	ringbuffer_t *	rb,
		size_t	new_capacity
	)

resize the ring buffer (assign a new capacity).

This is done by allocating some new "entries" memory, copying over all existing pointers using ringbuffer_element() and then replacing the old "entries" with the new pointers memory. "position" gets reset to 0. With sufficient new capacity the buffer count stays unchanged, otherwise an appropriate amount will be discarded ("pop"ping the oldest elements).

void* ringbuffer_tail ( ringbuffer_t *  rb )

inline

shortcut to retrieve "tail" element

Note

non-destructive, i.e. this does not pop the element!

See also

ringbuffer_pop