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.
Unregister a publisher context from its event class.
Publish an event, with data, within the event class of the publisher.
Publish an event, with data, with a pre-allocated event handle, within the event class of the publisher.
Subscribe to one or more events for a given event class.
Unsubscribe from 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.
Delete 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.
Free a publisher context structure from the heap, as well as its list of subscriber entries using the common memory manager.
Get the size of the event structure.
Allocate the event structure to the heap using the common memory manager with a long-term lifespan.
Free an event structure from the heap using the common memory manager.
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_BLUETOOTH_MESH | |
| 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.
136 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.
153 of file platform/common/inc/sl_event_system.hsl_event_publisher_unregister#
sl_status_t sl_event_publisher_unregister (sl_event_publisher_t * publisher)
Unregister a publisher context from its event class.
| [in] | publisher | Pointer to a publisher context. |
@description When a publisher context is unregistered, it can no longer publish messages until it is registered again. After a publisher context is unregistered, the event class it was registered with can be reused.
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
171 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.
185 of file platform/common/inc/sl_event_system.hsl_event_publish_static#
sl_status_t sl_event_publish_static (sl_event_publisher_t * publisher, uint32_t event_mask, uint8_t event_prio, sl_event_t * event, void * event_data)
Publish an event, with data, with a pre-allocated event handle, 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 | The pre-allocated event structure handle |
| [in] | event_data | The event data. |
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
204 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.
224 of file platform/common/inc/sl_event_system.hsl_event_unsubscribe#
sl_status_t sl_event_unsubscribe (sl_event_class_t event_class, uint32_t event_mask, sl_event_queue_t event_queue)
Unsubscribe from 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 unsubscribed event(s) will no longer be placed in the queue identified by event_queue.
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
243 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.
261 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.
273 of file platform/common/inc/sl_event_system.hsl_event_queue_delete#
sl_status_t sl_event_queue_delete (sl_event_queue_t event_queue)
Delete an event queue.
| [in] | event_queue | The event queue to delete. |
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
Note
In the process of deleting an event queue, all events that the queue was subscribed to will be unsubscribed from.
289 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.
303 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.
314 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.
326 of file platform/common/inc/sl_event_system.hsl_event_publisher_free#
sl_status_t sl_event_publisher_free (sl_event_publisher_t * publisher)
Free a publisher context structure from the heap, as well as its list of subscriber entries using the common memory manager.
| [in] | publisher | address of a pointer to a publisher context |
@description Using this function to free a publisher context will also free its list of subscribers, which will cause subscribers to no longer receive events from the publisher context's event class.
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
343 of file platform/common/inc/sl_event_system.hsl_event_get_size#
size_t sl_event_get_size (void )
Get the size of the event structure.
| N/A |
Returns
Size of the event structure.
351 of file platform/common/inc/sl_event_system.hsl_event_alloc#
sl_status_t sl_event_alloc (sl_event_t ** event)
Allocate the event structure to the heap using the common memory manager with a long-term lifespan.
| [in] | event | address of a pointer to an event struct |
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
363 of file platform/common/inc/sl_event_system.hsl_event_free#
sl_status_t sl_event_free (sl_event_t * event)
Free an event structure from the heap using the common memory manager.
| [in] | event | address of a pointer to an event struct |
Note
Freeing an event structure that has not yet been processed by all subscribers will
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
378 of file platform/common/inc/sl_event_system.h