System Ring buffer API

Module for declaring System Ring buffer API. More...

Data Structures
struct	sys_ringbuffer_t

Functions
void	sys_ringbuffer_init (sys_ringbuffer_t *buffer, const void *memory, const size_t length)
	Function for initializing an empty ring buffer over passed memory. More...
void	sys_ringbuffer_init_over (sys_ringbuffer_t *buffer, const void *memory, const size_t pre_init_length, const size_t length)
	Function for initializing a ring buffer over passed memory and marking all pre_init_length elements as inserted. More...
uint8_t	sys_ringbuffer_remove (sys_ringbuffer_t *buf)
	Function for removing an element from a ring buffer and returning it. More...
void	sys_ringbuffer_remove_multiple (sys_ringbuffer_t *buffer, const size_t chunk_size)
	Function for quickly removing up to chunk_size elements from a ring buffer and marking those elements as available in the ring buffer. More...
void	sys_ringbuffer_insert (sys_ringbuffer_t *buffer, const uint8_t data)
	Function for inserting a new element into a ring buffer. More...
void	sys_ringbuffer_clear (sys_ringbuffer_t *buffer)
	Function for clearing an instance of sys_ringbuffer_t, making it empty. More...
size_t	sys_ringbuffer_size_get (const sys_ringbuffer_t *buf)
	Function for returning the number of used elements in a ring buffer instance. More...
void	sys_ringbuffer_chunk_get (sys_ringbuffer_t *buffer, void **chunk, size_t *chunk_size)
	Function for returning the biggest, available to read, continuous chunk from a ring buffer array. More...
static bool	sys_ringbuffer_is_empty (const sys_ringbuffer_t *buf)
	Function for checking whether a ring buffer is empty. More...
static bool	sys_ringbuffer_is_full (const sys_ringbuffer_t *buf)
	Function for checking whether a ring buffer is full. More...
static size_t	sys_ringbuffer_max_size_get (const sys_ringbuffer_t *buf)
	Function for returning number of elements that can be potentially put into the buffer. More...

Detailed Description

Module for declaring System Ring buffer API.

The Ring Buffer module implements routines to deal with the ring buffer. The following routines are supported: sys_ringbuffer_insert(), sys_ringbuffer_remove() to operate with single element. The sys_ringbuffer_remove_multiple() can be used to remove (read) several elements at once. The sys_ringbuffer_clear(), sys_ringbuffer_init(), and sys_ringbuffer_init_over() functions are used to clean up and initialize the ring buffer. Some information about the initialized ring buffer is available via the following routines: sys_ringbuffer_size_get() to get the number of used elements, sys_ringbuffer_chunk_get() to return the biggest, available to read, continuous chunk of elements, sys_ringbuffer_is_empty() and sys_ringbuffer_is_full() to check if the ring buffer is empty/full, and sys_ringbuffer_max_size_get() to get the ring buffer capacity. One of the samples for ring buffer usage is the UART implementation.

Function Documentation

void sys_ringbuffer_chunk_get	(	sys_ringbuffer_t *	buffer,
		void **	chunk,
		size_t *	chunk_size
	)

Function for returning the biggest, available to read, continuous chunk from a ring buffer array.

Parameters

[in,out]	buffer	Instance of sys_ringbuffer_t.
[out]	chunk	Pointer to a memory chunk removed from the ring buffer.
[out]	chunk_size	Size of the removed chunk.

Warning

The returned chunk is still part of the ring buffer. To make the chunk elements available for write, call sys_ringbuffer_remove_multiple() after the chunk is processed.

void sys_ringbuffer_clear

(

sys_ringbuffer_t *

buffer

)

Function for clearing an instance of sys_ringbuffer_t, making it empty.

Parameters

[in,out]

buffer

Instance of sys_ringbuffer_t.

void sys_ringbuffer_init	(	sys_ringbuffer_t *	buffer,
		const void *	memory,
		const size_t	length
	)

Function for initializing an empty ring buffer over passed memory.

Parameters

[in,out]	buffer	Instance of sys_ringbuffer_t that will be initialized.
[in]	memory	Start address of the memory region used as a ring buffer.
[in]	length	Size in bytes of the memory region used as a ring buffer.

void sys_ringbuffer_init_over	(	sys_ringbuffer_t *	buffer,
		const void *	memory,
		const size_t	pre_init_length,
		const size_t	length
	)

Function for initializing a ring buffer over passed memory and marking all pre_init_length elements as inserted.

This function may be used to initialize a buffer with some pre-initialized data in it. Passed memory region is interpreted by this function as an already filled (partly or fully) ring buffer so that pre_init_length elements are marked as inserted.

Parameters

[in,out]	buffer	Instance of sys_ringbuffer_t that will be initialized.
[in]	memory	Start address of the memory region used as a ring buffer.
[in]	pre_init_length	Number of elements (bytes) that had already been in memory. They would be inserted into the newly-initialized ring buffer in a FIFO manner.
[in]	length	Size of the memory region used as a ring buffer.

void sys_ringbuffer_insert	(	sys_ringbuffer_t *	buffer,
		const uint8_t	data
	)

Function for inserting a new element into a ring buffer.

Parameters

[in,out]	buffer	Instance of sys_ringbuffer_t.
[in]	data	Element value to insert.

Warning

In case of overflow, this buffer will overwrite the oldest element and the number of available elements will remain unchanged.

static bool sys_ringbuffer_is_empty ( const sys_ringbuffer_t *  buf )

inlinestatic

Function for checking whether a ring buffer is empty.

Parameters

[in,out]

buf

Instance of sys_ringbuffer_t.

Returns

True if the ring buffer is empty.

static bool sys_ringbuffer_is_full ( const sys_ringbuffer_t *  buf )

inlinestatic

Function for checking whether a ring buffer is full.

Parameters

[in,out]

buf

Instance of sys_ringbuffer_t.

Returns

True if number of items in the buffer equals to (length - 1).

static size_t sys_ringbuffer_max_size_get ( const sys_ringbuffer_t *  buf )

inlinestatic

Function for returning number of elements that can be potentially put into the buffer.

Parameters

[in,out]

buf

Instance of sys_ringbuffer_t.

Returns

Number of elements.

uint8_t sys_ringbuffer_remove

(

sys_ringbuffer_t *

buf

)

Function for removing an element from a ring buffer and returning it.

Parameters

[in,out]

buf

Instance of sys_ringbuffer_t.

Returns

Value of the removed element.

Warning

This buffer has no underflow control except assert.

void sys_ringbuffer_remove_multiple	(	sys_ringbuffer_t *	buffer,
		const size_t	chunk_size
	)

Function for quickly removing up to chunk_size elements from a ring buffer and marking those elements as available in the ring buffer.

Parameters

[in,out]	buffer	Instance of sys_ringbuffer_t.
[in]	chunk_size	Number of elements to release.

size_t sys_ringbuffer_size_get

(

const sys_ringbuffer_t *

buf

)

Function for returning the number of used elements in a ring buffer instance.

Parameters

[in,out]

buf

Instance of sys_ringbuffer_t.

Returns

Number of elements.