|
 |
|
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. | |
Ring buffer for objects storage.
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.
| 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.
| [in] | rb | pointer to ring buffer structure |
| [in] | item | item to 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.
| [in] | rb | pointer to ring buffer structure, will be filled by the function |
| [in] | size | number of items in ring buffer, the buffer can hold maximum size-1 items |
| 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.
| [in] | rb | pointer to ring buffer structure |
| [out] | item | pointer to variable where pointer to the item is 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.
| [in] | rb | pointer to ring buffer structure |
