Ring_Buffer

Description

ring buffer implementation for double-precision floats

<rc/math/ring_buffer.h>

Ring buffers are FIFO (first in first out) buffers of fixed length which efficiently boot out the oldest value when full. They are particularly well suited for storing the last n values in a discrete time filter.

The user creates their own instance of a buffer and passes a pointer to the these ring_buf functions to perform normal operations.

Author

James Strawson

Date

2016

Data Structures
struct	rc_ringbuf_t
	Struct containing state of a ringbuffer and pointer to dynamically allocated memory. More...

Macros
#define	RC_RINGBUF_INITIALIZER

Typedefs
typedef struct rc_ringbuf_t	rc_ringbuf_t
	Struct containing state of a ringbuffer and pointer to dynamically allocated memory. More...

Functions
rc_ringbuf_t	rc_ringbuf_empty (void)
	Returns an rc_ringbuf_t struct which is completely zero'd out with no memory allocated for it. More...
int	rc_ringbuf_alloc (rc_ringbuf_t *buf, int size)
	Allocates memory for a ring buffer and initializes an rc_ringbuf_t struct. More...
int	rc_ringbuf_free (rc_ringbuf_t *buf)
	Frees the memory allocated for buffer buf. More...
int	rc_ringbuf_reset (rc_ringbuf_t *buf)
	Sets all values in the buffer to 0.0f and sets the buffer index back to 0. More...
int	rc_ringbuf_insert (rc_ringbuf_t *buf, double val)
	Puts a new float into the ring buffer and updates the index accordingly. More...
double	rc_ringbuf_get_value (rc_ringbuf_t *buf, int position)
	Fetches the float which is 'position' steps behind the last value added to the buffer. More...
double	rc_ringbuf_std_dev (rc_ringbuf_t buf)
	Returns the standard deviation of all values in the ring buffer. More...

Macro Definition Documentation

RC_RINGBUF_INITIALIZER

#define RC_RINGBUF_INITIALIZER

Value:

{\
        .d = NULL,\
        .size = 0,\
        .index = 0,\
        .initialized = 0}

Function Documentation

rc_ringbuf_empty()

rc_ringbuf_t rc_ringbuf_empty

(

void

)

Returns an rc_ringbuf_t struct which is completely zero'd out with no memory allocated for it.

This is essential for declaring new ring buffers since structs declared inside of functions are not necessarily zero'd out which can cause the struct to contain problematic contents leading to segfaults. New ring buffers should be initialized with this before calling rc_ringbuf_alloc.

Returns

empty and ready-to-allocate rc_ringbuf_t

rc_ringbuf_alloc()

int rc_ringbuf_alloc	(	rc_ringbuf_t *	buf,
		int	size
	)

Allocates memory for a ring buffer and initializes an rc_ringbuf_t struct.

If buf is already the right size then it is left untouched. Otherwise any existing memory allocated for buf is freed to avoid memory leaks and new memory is allocated.

Parameters

	buf	Pointer to user's buffer
[in]	size	Number of elements to allocate space for

Returns

Returns 0 on success or -1 on failure.

rc_ringbuf_free()

int rc_ringbuf_free

(

rc_ringbuf_t *

buf

)

Frees the memory allocated for buffer buf.

Also set the initialized flag to 0 so other functions don't try to access unallocated memory.

Parameters

buf	Pointer to user's buffer

Returns

Returns 0 on success or -1 on failure.

rc_ringbuf_reset()

int rc_ringbuf_reset

(

rc_ringbuf_t *

buf

)

Sets all values in the buffer to 0.0f and sets the buffer index back to 0.

Parameters

buf	Pointer to user's buffer

Returns

Returns 0 on success or -1 on failure.

rc_ringbuf_insert()

int rc_ringbuf_insert	(	rc_ringbuf_t *	buf,
		double	val
	)

Puts a new float into the ring buffer and updates the index accordingly.

If the buffer was full then the oldest value in the buffer is automatically removed.

Parameters

	buf	Pointer to user's buffer
[in]	val	The value to be inserted

Returns

Returns 0 on success or -1 on failure.

rc_ringbuf_get_value()

double rc_ringbuf_get_value	(	rc_ringbuf_t *	buf,
		int	position
	)

Fetches the float which is 'position' steps behind the last value added to the buffer.

If 'position' is given as 0 then the most recent value is returned. The position obviously can't be larger than (buffer size - 1).

Parameters

	buf	Pointer to user's buffer
[in]	position	steps back in the buffer to fetch the value from

Returns

Returns the requested float. Prints an error message and returns -1.0f on error.

rc_ringbuf_std_dev()

double rc_ringbuf_std_dev

(

rc_ringbuf_t

buf

)

Returns the standard deviation of all values in the ring buffer.

Note that if the buffer has not yet been filled completely before calling this, then the starting values of 0.0f in the unfilled portion of the buffer will still be part of the calculation.

Parameters

[in]

buf

Pointer to user's buffer

Returns

Returns the standard deviation of all values in the ring buffer.