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.
Supervisor Mode#
Supervisor mode allows users to subscribe to all events from all classes. There is an internal queue that will receive all events published by any publisher. When a publisher is registered, the supervisor queue will subscribe to it automatically. To get an event from the supervisor queue, the user must call the function sl_event_supervisor_queue_get.
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 current number of events in 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.
Initialize the IRQ event system.
De-initialize the IRQ event system.
Publish an event from an interrupt service routine (ISR).
Decode the IRQ event from a given event structure.
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 | |
Typedef Documentation#
sl_event_queue_t#
typedef osMessageQueueId_t sl_event_queue_t
TYPEDEFS ***********************************.
Function Documentation#
sl_event_system_init#
void sl_event_system_init (void )
PROTOTYPES ***********************************.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| void | N/A |
Initialize the event system.
sl_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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_event_publisher_t * | [in] | publisher | Pointer to a publisher context. |
| sl_event_class_t | [in] | event_class | The class of events published by the publisher. |
| sl_event_free_data_cb_t | [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.
sl_event_publisher_unregister#
sl_status_t sl_event_publisher_unregister (sl_event_publisher_t * publisher)
Unregister a publisher context from its event class.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_event_publisher_t * | [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.
sl_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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_event_publisher_t * | [in] | publisher | Pointer to a publisher context. |
| uint32_t | [in] | event_mask | Event mask corresponding to the type of event. |
| uint8_t | [in] | event_prio | The priority of the event published. |
| void * | [in] | event_data | The event data. |
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
sl_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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_event_publisher_t * | [in] | publisher | Pointer to a publisher context. |
| uint32_t | [in] | event_mask | Event mask corresponding to the type of event. |
| uint8_t | [in] | event_prio | The priority of the event published. |
| sl_event_t * | [in] | event | The pre-allocated event structure handle |
| void * | [in] | event_data | The event data. |
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
sl_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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_event_class_t | [in] | event_class | The class of events to subscribe to. |
| uint32_t | [in] | event_mask | The event(s) to subscribe to. |
| sl_event_queue_t | [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.
sl_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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_event_class_t | [in] | event_class | The class of events to subscribe to. |
| uint32_t | [in] | event_mask | The event(s) to subscribe to. |
| sl_event_queue_t | [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.
sl_event_process#
sl_status_t sl_event_process (sl_event_t ** event)
Signal to the event system that a subscriber has processed an event.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_event_t ** | [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.
sl_event_queue_create#
sl_status_t sl_event_queue_create (uint32_t event_count, sl_event_queue_t * event_queue)
Create an event queue.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint32_t | [in] | event_count | The maximum number of events in the event queue. |
| sl_event_queue_t * | [out] | event_queue | The event queue that is created. |
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
sl_event_queue_delete#
sl_status_t sl_event_queue_delete (sl_event_queue_t event_queue)
Delete an event queue.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_event_queue_t | [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.
sl_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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_event_queue_t | [in] | event_queue | The identifier of an event queue. |
| uint8_t * | [in] | event_prio | The priority of event(s) to get. |
| uint32_t | [in] | timeout | Maximum time to pend on the event queue. |
| sl_event_t ** | [out] | event | The event reference retrieved from the event queue. |
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
sl_event_queue_get_count#
uint32_t sl_event_queue_get_count (sl_event_queue_t event_queue)
Get the current number of events in queue.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_event_queue_t | [in] | event_queue | The identifier of an event queue. |
Returns
The current number of events in the queue.
sl_event_publisher_get_size#
size_t sl_event_publisher_get_size (void )
Get the size of the event publisher structure.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| void | N/A |
Returns
Size of the event publisher structure.
sl_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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_event_publisher_t ** | [in] | publisher | address of a pointer to a publisher context |
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
sl_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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_event_publisher_t * | [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.
sl_event_get_size#
size_t sl_event_get_size (void )
Get the size of the event structure.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| void | N/A |
Returns
Size of the event structure.
sl_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.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_event_t ** | [in] | event | address of a pointer to an event struct |
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
sl_event_free#
sl_status_t sl_event_free (sl_event_t * event)
Free an event structure from the heap using the common memory manager.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_event_t * | [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 result in undefined behavior.
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
sl_event_irq_publisher_init#
sl_status_t sl_event_irq_publisher_init (void )
Initialize the IRQ event system.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| void | [in] | Event queue to use for IRQ events. |
@description This function initializes the IRQ event publisher to allow publishing events from interrupt service routines. This must be called after sl_event_system_init().
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
sl_event_irq_publisher_deinit#
sl_status_t sl_event_irq_publisher_deinit (void )
De-initialize the IRQ event system.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| void | N/A |
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
sl_event_irq_publish#
sl_status_t sl_event_irq_publish (uint32_t irq_number)
Publish an event from an interrupt service routine (ISR).
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint32_t | [in] | irq_number | The IRQ number associated with the event. |
This function should only be called from IRQ contexts to publish IRQ events to subscribers of the IRQ event class.
Returns
SL_STATUS_OK if successful, otherwise an error code is returned.
Note
This function must only be called from IRQ contexts. For non-IRQ contexts, use the standard event publishing mechanisms.
sl_event_irq_decode#
uint32_t sl_event_irq_decode (sl_event_t * event)
Decode the IRQ event from a given event structure.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_event_t * | [in] | event | Pointer to the event structure. |
Returns
The decoded IRQ event, or 0xFFFFFFFF if the event is invalid.