core/include/ring_buffer_ev.h File Reference

Ring buffer for events. More...

Data Structures

struct  os_ring_buffer_ev_s
 Events ring buffer structure. More...

Typedefs

typedef struct os_ring_buffer_ev_s os_ring_buffer_ev_t
 Data type for event ring buffer.

Functions

os_result_t os_ringbuf_create_ev (os_ring_buffer_ev_t *rb, unsigned char size)
 Creation of the ring buffer for events.
os_result_t os_ringbuf_add_ev (os_ring_buffer_ev_t *rb, os_event_t event)
 Adds one event to the ring buffer.
os_result_t os_ringbuf_get_ev (os_ring_buffer_ev_t *rb, os_event_t *event)
 Gets one event from the buffer.
unsigned char os_ringbuf_items_ev (os_ring_buffer_ev_t *rb)
 Reads number of events in the ring buffer.
os_result_t os_ringbuf_clear_ev (os_ring_buffer_ev_t *rb)
 Clears buffer.

Detailed Description

Ring buffer for events.

Author:
Piotr Romaniuk, (c) ELESOFTROM
Version:
1.0 Feb 4, 2011

This type of ring buffer is a variant of ring buffer (ring_buffer.h). The main difference is that this ring buffer is intentended for events (events.h) storage. Due to small and compact form of the events they are stored inside the buffer. This does not add a lot of operations but simplifies event management. The event is copied to buffer when is added and also when is removed. This introduce a separation in management of lifetime event. Here the event can be created and destroyed in the same part, while general ring buffer requires creation at one size (when is added) and freeing at the other one (when is removed from ring buffer).

Other properties are inherited from ring_buffer (ring_buffer.h), refer there for more information.

Note:
User need to provide a management for extra data attached to the event by a pointer in os_event_t.xdata. The additional data is not copied during operations with the ring buffer only the pointer is copied.

Function Documentation

os_result_t os_ringbuf_add_ev ( os_ring_buffer_ev_t rb,
os_event_t  event 
)

Adds one event to the ring buffer.

Event is copied to ring buffer, so event instance that is an input may be deleted. The function uses critical section, so is thread safe and can be called from ISR.

Parameters:
[in]rbpointer to ring buffer structure
[in]eventevent to be added
Returns:
OS_STATUS_OK if the vent has been added successfully,
OS_FULL - when failed to add the event because the buffer is full
os_result_t os_ringbuf_clear_ev ( os_ring_buffer_ev_t rb)

Clears buffer.

Parameters:
[in]rbpointer to ring buffer structure
Returns:
OS_STATUS_OK
os_result_t os_ringbuf_create_ev ( os_ring_buffer_ev_t rb,
unsigned char  size 
)

Creation of the ring buffer for events.

Ring buffer must be created before it is used.

Parameters:
[in]rbpointer to the ring buffer structure
[in]sizenumber of items in ring buffer (capacity is size-1)
Returns:
OS_STATUS_OK if successfully created
OS_ERROR_NO_MEMORY if failed to allocate internal table for events storage.
os_result_t os_ringbuf_get_ev ( os_ring_buffer_ev_t rb,
os_event_t event 
)

Gets one event from the buffer.

Event is copied to provided location (event argument). The function uses critical section, so is thread safe and can be called from ISR.

Parameters:
[in]rbpointer to ring buffer structure
[out]eventis copied to the event (if rb has been read)
Returns:
OS_STATUS_OK if the event has been read,
OS_EMPTY if the buffer is empty and no event has been read.
unsigned char os_ringbuf_items_ev ( os_ring_buffer_ev_t rb)

Reads number of events in the ring buffer.

The function uses critical section, so is thread safe and can be called from ISR.

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