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]	rb	pointer to ring buffer structure
[in]	event	event 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]

rb

pointer 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]	rb	pointer to the ring buffer structure
[in]	size	number 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]	rb	pointer to ring buffer structure
[out]	event	is 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]

rb

pointer to ring buffer structure

Returns:

number of events in the ring buffer