core/include/ring_buffer.h File Reference

Ring buffer for objects storage. More...

Data Structures

struct  os_ring_buffer_s
 Ring buffer structure. More...

Typedefs

typedef struct os_ring_buffer_s os_ring_buffer_t
 Data type of ring buffer.

Functions

os_result_t os_ringbuf_create (os_ring_buffer_t *rb, unsigned char size)
 Creation of the ring buffer.
os_result_t os_ringbuf_add (os_ring_buffer_t *rb, void *item)
 Adds one item to the ring buffer.
os_result_t os_ringbuf_get (os_ring_buffer_t *rb, void **item)
 Gets one item from buffer.
unsigned char os_ringbuf_items (os_ring_buffer_t *rb)
 Reads number of items in ring buffer.

Detailed Description

Ring buffer for objects storage.

Author:
Piotr Romaniuk, (c) ELESOFTROM
Version:
1.1 Nov 8, 2013

The buffer is communication object and can serve the function of intermediate link that connects parts that work with different speed. As long as average input stream is not larger than output one, the buffer prevents from data lost, even if the reader cannot process data as fast as they come from writer. This is possible because the pending data are collected in the buffer and processed later when the reader is available.

The buffer can be used as a collector that gathers some items coming from many sources, stores them in temporal order and provides for processing by one reader. In this function the buffer can perform synchronization role.

Ring buffer is a variant of the buffer. Like generic buffer it can store ordered set of items (or references to items) and perform an access in FIFO (first in first out) fashion. It can perform regular buffer functions (i.e. add, get) but using the ring version provides better performance because avoids copying data. The cost of this feature is a need of constant size of the ring buffer specified at creation time.

This ring buffer is intended to store items of unknown size (unknown from the buffer perspective). It can also handle objects of different size. These properties are achieved by identification the objects by a pointer. Of course, object lifetime must be managed by external code and is outside of the ring buffer scope.

The ring buffer is protected from concurrent access and can be used in communication between threads as well as between thread and ISR. The functions are non-blocking, but if you need to add waiting property on empty buffer for thread, just add semaphore. Perform post on each addition to the buffer and wait when you succesfully got the item from the buffer.

Because of constant and limited capacity, the ring buffer can return OS_FULL when addition is impossible.

Note:
that the ring buffer can store size-1 items, this is due to implementation, so always take it into account if exact capacity is important.

Function Documentation

os_result_t os_ringbuf_add ( os_ring_buffer_t rb,
void *  item 
)

Adds one item to the ring buffer.

The function is protected from concurrent access from different threads. It uses critical sections, so can be also called from ISR.

Note:
The item is attached to the internal table, but it must still exists, until it is read from the buffer. Only pointer is copied to ring buffer.
Objects in this ring buffer may have different size.
Parameters:
[in]rbpointer to ring buffer structure
[in]itemitem to be added
Returns:
OS_STATUS_OK if the item has been added
OS_FULL if buffer is full and item cannot be added
os_result_t os_ringbuf_create ( os_ring_buffer_t rb,
unsigned char  size 
)

Creation of the ring buffer.

Ring buffer must be created before it is used.

Parameters:
[in]rbpointer to ring buffer structure, will be filled by the function
[in]sizenumber of items in ring buffer, the buffer can hold maximum size-1 items
Returns:
OS_STATUS_OK - if successful creation,
OS_ERROR_NO_MEMORY - if it cannot allocate memory for the internal table.
os_result_t os_ringbuf_get ( os_ring_buffer_t rb,
void **  item 
)

Gets one item from buffer.

The function is protected from concurrent access from different threads. It uses critical sections, so can be also called from ISR.

Note:
The item is attached to the internal table, and still exists until it is read from the buffer. When it is read it should be freed if has been allocated dynamically. Only pointer is read from ring buffer.
Objects in this ring buffer may have different size depending on usage.
Parameters:
[in]rbpointer to ring buffer structure
[out]itempointer to variable where pointer to the item is read
Returns:
OS_STATUS_OK if item is read,
OS_EMPTY - if the buffer is empty and no item has been read
unsigned char os_ringbuf_items ( os_ring_buffer_t rb)

Reads number of items in ring buffer.

The function is protected from concurrent access from different threads. It uses critical sections, so can be also called from ISR.

Parameters:
[in]rbpointer to ring buffer structure
Returns:
number of items stored in the ring buffer