Event System#
A publish/subscribe inter-process communication system.
The source files for the event system software module are present under platform/common.
Overview#
The event system is a software component enabling the development of event-driven software systems for Simplicity SDK based firmware's by managing publisher creation, event dispatching/filtering and event listening.
The event system has multiple types of event classes that subscribers can listen to. Event classes identify the event source from which the event originates such as Bluetooth or Zigbee. See sl_event_class_t.
Subclasses further refine the event by offering information related to a particular functionality. A unique bit is assigned to each subclass which will have a specific meaning for each event publisher.
Initialization#
The initialization of the event system occurs during the general system initialization. This happens when the application calls the sl_system_init() function. All the basic event system data structures will be initialized along with every publisher available in your project.
Event subscription#
The event subscription takes place when the user establishes a communication pipeline between the listener and the publisher by calling sl_event_subscribe. The user shall provide the type of event class that he wants to listen to, an event mask to further refine the set of events that he wants to listen to. Finally, an event queue must be created and initialized by the event listening code by using sl_event_queue_create which will allocate the necessary memory and initialize an event system event queue. This queue is the main communication channel between the publisher and the listener.
Event notification#
When a new event is generated, the publisher will enqueue it in the event listener provided queue. At this point, the listener will be able to recover this event by calling sl_event_queue_get function. In the case where no event is ready for processing the calling process will pend on the message queue for a predetermined amount of time. After consuming the event, the @sl_event_process function must be called for each event instance. This will ensure that the memory and resources used by the event data structure is properly deallocated.
Modules#
Enumerations#
Typedefs#
TYPEDEFS ***********************************.
Functions#
PROTOTYPES ***********************************.
Initialize a publisher context and register it in the event system with a given event class.
Publish an event, with data, within the event class of the publisher.
Subscribe to one or more events for a given event class.
Signal to the event system that a subscriber has processed an event.
Create an event queue.
Get an event from an event queue.
Get the size of the event publisher structure.
Allocate the publisher structure to the heap using the common memory manager with a long-term lifespan.
Enumeration Documentation#
sl_event_class_t#
sl_event_class_t
| Enumerator | |
|---|---|
| SL_EVENT_CLASS_IRQ | |
| SL_EVENT_CLASS_BLUETOOTH | |
| SL_EVENT_CLASS_ZIGBEE | |
| SL_EVENT_CLASS_MAX | |
98 of file platform/common/inc/sl_event_system.hTypedef Documentation#
sl_event_queue_t#
typedef osMessageQueueId_t sl_event_queue_t
TYPEDEFS ***********************************.
95 of file platform/common/inc/sl_event_system.hsl_event_free_data_cb_t#
typedef void(* sl_event_free_data_cb_t) (void *data) )(void *data)
96 of file platform/common/inc/sl_event_system.hFunction Documentation#
sl_event_system_init#
void sl_event_system_init (void )
PROTOTYPES ***********************************.
| N/A |
Initialize the event system.
133 of file platform/common/inc/sl_event_system.hsl_event_publisher_register#
sl_status_t sl_event_publisher_register (sl_event_publisher_t * publisher, sl_event_class_t event_class, sl_event_free_data_cb_t free_data_callback)
Initialize a publisher context and register it in the event system with a given event class.
| [in] | publisher | Pointer to a publisher context. |
| [in] | event_class | The class of events published by the publisher. |
| [in] | free_data_callback | Callback to free the publisher's event data. |
@description Only one publisher context is allowed per event class.
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
150 of file platform/common/inc/sl_event_system.hsl_event_publish#
sl_status_t sl_event_publish (sl_event_publisher_t * publisher, uint32_t event_mask, uint8_t event_prio, void * event_data)
Publish an event, with data, within the event class of the publisher.
| [in] | publisher | Pointer to a publisher context. |
| [in] | event_mask | Event mask corresponding to the type of event. |
| [in] | event_prio | The priority of the event published. |
| [in] | event_data | The event data. |
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
166 of file platform/common/inc/sl_event_system.hsl_event_subscribe#
sl_status_t sl_event_subscribe (sl_event_class_t event_class, uint32_t event_mask, sl_event_queue_t event_queue)
Subscribe to one or more events for a given event class.
| [in] | event_class | The class of events to subscribe to. |
| [in] | event_mask | The event(s) to subscribe to. |
| [in] | event_queue | The identifier of an event queue. |
@description The subscribed event(s) is/are placed in the queue identified by event_queue.
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
185 of file platform/common/inc/sl_event_system.hsl_event_process#
sl_status_t sl_event_process (sl_event_t ** event)
Signal to the event system that a subscriber has processed an event.
| [in] | event | Pointer to an event reference. |
@description This must be called by subscribers after consuming an event so that the event data may eventually be freed. The event reference passed to this function is nullified before returning.
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
203 of file platform/common/inc/sl_event_system.hsl_event_queue_create#
sl_status_t sl_event_queue_create (uint32_t event_count, sl_event_queue_t * event_queue)
Create an event queue.
| [in] | event_count | The maximum number of events in the event queue. |
| [out] | event_queue | The event queue that is created. |
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
215 of file platform/common/inc/sl_event_system.hsl_event_queue_get#
sl_status_t sl_event_queue_get (sl_event_queue_t event_queue, uint8_t * event_prio, uint32_t timeout, sl_event_t ** event)
Get an event from an event queue.
| [in] | event_queue | The identifier of an event queue. |
| [in] | event_prio | The priority of event(s) to get. |
| [in] | timeout | Maximum time to pend on the event queue. |
| [out] | event | The event reference retrieved from the event queue. |
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
230 of file platform/common/inc/sl_event_system.hsl_event_publisher_get_size#
size_t sl_event_publisher_get_size (void )
Get the size of the event publisher structure.
| N/A |
Returns
Size of the event publisher structure.
241 of file platform/common/inc/sl_event_system.hsl_event_publisher_alloc#
sl_status_t sl_event_publisher_alloc (sl_event_publisher_t ** publisher)
Allocate the publisher structure to the heap using the common memory manager with a long-term lifespan.
| [in] | publisher | address of a pointer to a publisher context |
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
253 of file platform/common/inc/sl_event_system.h