Scheduling events for future execution. More...

Macros

#define __EVENT_H__
 
#define emberEventControlSetInactive(control)   do { (control).status = EMBER_EVENT_INACTIVE; } while (0)
 Set this EmberEventControl as inactive (no pending event). More...
 
#define emberEventControlGetActive(control)   ((control).status != EMBER_EVENT_INACTIVE)
 Check whether this EmberEventControl is currently active. An event is considered active if it is set to run some time in the future (activated by emberEventControlSetActive(), emberEventControlSetDelayMS() or any other emberEventControlSetDelay* functions) More...
 
#define emberEventControlSetActive(control)   do { emEventControlSetActive(&(control)); } while (0)
 Set this EmberEventControl to run at the next available opportunity. More...
 
#define EMBER_MAX_EVENT_CONTROL_DELAY_MS   (HALF_MAX_INT32U_VALUE - 1)
 The maximum delay that may be passed to emberEventControlSetDelayMS(). More...
 
#define emberEventControlSetDelayMS(control, delay)   do { emEventControlSetDelayMS(&(control), (delay)); } while (0)
 Set this EmberEventControl to run some milliseconds in the future. More...
 
#define EMBER_MAX_EVENT_CONTROL_DELAY_QS   (EMBER_MAX_EVENT_CONTROL_DELAY_MS >> 8)
 The maximum delay that may be passed to emberEventControlSetDelayQS(). More...
 
#define emberEventControlSetDelayQS(control, delay)   do { emEventControlSetDelayMS(&(control), (delay) << 8); } while (0)
 Set this EmberEventControl to run some quarter seconds in the future. More...
 
#define EMBER_MAX_EVENT_CONTROL_DELAY_MINUTES   (EMBER_MAX_EVENT_CONTROL_DELAY_MS >> 16)
 The maximum delay that may be passed to emberEventControlSetDelayMinutes(). More...
 
#define emberEventControlSetDelayMinutes(control, delay)   do { emEventControlSetDelayMS(&(control), (delay) << 16); } while (0)
 Set this EmberEventControl to run some minutes in the future. More...
 
#define emberEventControlGetRemainingMS(control)   (emEventControlGetRemainingMS(&(control)))
 Check when the event is scheduled to run. More...
 
#define emberTaskEnableIdling(allow)   do { emTaskEnableIdling((allow)); } while (0)
 Enable or disable idling. More...
 
#define emberMarkTaskActive(taskid)   do { emMarkTaskActive((taskid)); } while (0)
 Calling it indicates that a task has something to do, so it should prevent the CPU from idling until emberMarkTaskIdle is next called on this task. More...
 

Functions

void emEventControlSetActive (EmberEventControl *event)
 
void emEventControlSetDelayMS (EmberEventControl *event, uint32_t delay)
 
uint32_t emEventControlGetRemainingMS (EmberEventControl *event)
 
void emberRunEvents (EmberEventData *events)
 Start an event handler if there is anything scheduled at the moment this function is called. More...
 
void emberRunTask (EmberTaskId taskid)
 Start an event handler if there is anything scheduled at the moment this function is called. More...
 
uint32_t emberMsToNextEvent (EmberEventData *events, uint32_t maxMs)
 Check when the next event is scheduled to run. More...
 
uint32_t emberMsToNextEventExtended (EmberEventData *events, uint32_t maxMs, uint8_t *returnIndex)
 
uint32_t emberMsToNextStackEvent (void)
 Check when the next stack event is scheduled to run. More...
 
EmberTaskId emberTaskInit (EmberEventData *events)
 Initialize a task for managing events and processor idling state. More...
 
bool emberMarkTaskIdle (EmberTaskId taskid)
 Try to idle the CPU, unless any events in any tasks are pending. More...
 
void emTaskEnableIdling (bool allow)
 Enable or disable idling. More...
 
void emMarkTaskActive (EmberTaskId taskid)
 Calling it indicates that a task has something to do, so it should prevent the CPU from idling until emberMarkTaskIdle is next called on this task. More...
 

Detailed Description

Scheduling events for future execution.

See Event Scheduling for documentation. These macros implement an event abstraction that allows the application to schedule code to run after a specified time interval. An event consists of a procedure to be called at some point in the future and a control object that determines which procedure should be called. Events are also useful when an ISR needs to initiate an action that should run outside the ISR context.

See event.h for source code.

Note that, while not required, it is recommended that the event-handling procedure explicitly define the recurrence of the next event, either by rescheduling via some kind of emberEventControlSetDelayXX() call or by deactivating via a call to emberEventControlSetInactive().

When the handler does not explicitly reschedule or cancel the event, the default behavior of the event control system is to keep the event immediately active as if the handler function had called emberEventControlSetActive(someEvent) or emberEventControlSetDelayMS(someEvent, 0).

The base time units for events are ticks. A tick equals 1us on every platform supported by Connect. Note, however, that the accuracy of the base tick depends on the timer source, which by default is the LF RC oscillator on EFR32 platforms.

Furthermore, the scheduled delay is the minimum delay. If emberRunEvents() or emberRunTask() are not called frequently enough, the actual delay may be longer than the scheduled delay.

Additionally, the APIs for quarter second and minute delays (emberEventControlSetDelayQS() and emberEventControlSetDelayMinutes()) use "binary" units. One quarter second is 256 ticks and one minute is 65536 ticks. These APIs are therefore doesn't actually mean a quarter of second or a minute on platforms supported by Connect.

However, in the future, Connect support might become available on platforms where one tick is not exactly 1us. For example,. on the EM357 SoC, 1ms is 1024 ticks, so each tick is 1000 / 1024 = ~0.98 milliseconds. If you need platform independent accurate delays, use the macros ::MILLISECOND_TICKS_PER_SECOND and ::MILLISECOND_TICKS_PER_MINUTE. For example, calling emberEventControlSetDelayMS(someEvent, 3 * MILLISECOND_TICKS_PER_MINUTE) will delay for 3 minutes on any platform.

The following are brief usage examples.

EmberEventControl delayEvent;
EmberEventControl signalEvent;
EmberEventControl periodicEvent;
void delayEventHandler(void)
{
// Disable this event until its next use.
emberEventControlSetInactive(delayEvent);
}
void signalEventHandler(void)
{
// Disable this event until its next use.
emberEventControlSetInactive(signalEvent);
// Sometimes an action has to occur 100 ms later.
if (somethingIsExpected)
emberEventControlSetDelayMS(delayEvent, 100);
}
void periodicEventHandler(void)
{
emberEventControlSetDelayQS(periodicEvent, 4);
}
void someIsr(void)
{
// Set the signal event to run at the first opportunity.
emberEventControlSetActive(signalEvent);
}
// Put the controls and handlers in an array. They will be run in
// this order (this is usually generated)
EmberEventData events[] =
{
{ &delayEvent, delayEventHandler },
{ &signalEvent, signalEentHandler },
{ &periodicEvent, periodicEventHandler },
{ NULL, NULL } // terminator
};
void main(void)
{
// Cause the periodic event to occur once a second.
emberEventControlSetDelayQS(periodicEvent, 4);
while (TRUE) {
emberRunEvents(events);
}
}

Macro Definition Documentation

◆ __EVENT_H__

#define __EVENT_H__

Definition at line 166 of file event.h.

◆ EMBER_MAX_EVENT_CONTROL_DELAY_MINUTES

#define EMBER_MAX_EVENT_CONTROL_DELAY_MINUTES   (EMBER_MAX_EVENT_CONTROL_DELAY_MS >> 16)

The maximum delay that may be passed to emberEventControlSetDelayMinutes().

Definition at line 252 of file event.h.

◆ EMBER_MAX_EVENT_CONTROL_DELAY_MS

#define EMBER_MAX_EVENT_CONTROL_DELAY_MS   (HALF_MAX_INT32U_VALUE - 1)

The maximum delay that may be passed to emberEventControlSetDelayMS().

Definition at line 210 of file event.h.

◆ EMBER_MAX_EVENT_CONTROL_DELAY_QS

#define EMBER_MAX_EVENT_CONTROL_DELAY_QS   (EMBER_MAX_EVENT_CONTROL_DELAY_MS >> 8)

The maximum delay that may be passed to emberEventControlSetDelayQS().

Definition at line 235 of file event.h.

◆ emberEventControlGetActive

#define emberEventControlGetActive (   control)    ((control).status != EMBER_EVENT_INACTIVE)

Check whether this EmberEventControl is currently active. An event is considered active if it is set to run some time in the future (activated by emberEventControlSetActive(), emberEventControlSetDelayMS() or any other emberEventControlSetDelay* functions)

Parameters
[in]controlControl of the event in question.
Returns
Returns true if the event is active false otherwise

Definition at line 187 of file event.h.

◆ emberEventControlGetRemainingMS

#define emberEventControlGetRemainingMS (   control)    (emEventControlGetRemainingMS(&(control)))

Check when the event is scheduled to run.

Parameters
[in]controlControl of the event in question.
Returns
Returns the amount of milliseconds remaining before the event is scheduled to run. If the event is inactive, MAX_INT32U_VALUE is returned.

Definition at line 271 of file event.h.

◆ emberEventControlSetActive

#define emberEventControlSetActive (   control)    do { emEventControlSetActive(&(control)); } while (0)

Set this EmberEventControl to run at the next available opportunity.

Parameters
[in]controlControl of the event to set active.

Definition at line 196 of file event.h.

◆ emberEventControlSetDelayMinutes

#define emberEventControlSetDelayMinutes (   control,
  delay 
)    do { emEventControlSetDelayMS(&(control), (delay) << 16); } while (0)

Set this EmberEventControl to run some minutes in the future.

Parameters
[in]controlControl of the event to run.
[in]delayThe delay in minute. One minute is actually 65536 ms. Must be less than EMBER_MAX_EVENT_CONTROL_DELAY_MINUTES

Definition at line 261 of file event.h.

◆ emberEventControlSetDelayMS

#define emberEventControlSetDelayMS (   control,
  delay 
)    do { emEventControlSetDelayMS(&(control), (delay)); } while (0)

Set this EmberEventControl to run some milliseconds in the future.

Parameters
[in]controlControl of the event to run.
[in]delayThe delay in milliseconds. Must be less than EMBER_MAX_EVENT_CONTROL_DELAY_MS

Definition at line 219 of file event.h.

◆ emberEventControlSetDelayQS

#define emberEventControlSetDelayQS (   control,
  delay 
)    do { emEventControlSetDelayMS(&(control), (delay) << 8); } while (0)

Set this EmberEventControl to run some quarter seconds in the future.

Parameters
[in]controlControl of the event to run.
[in]delayThe delay in quarter seconds. One quarter second is actually 256 ms. Must be less than EMBER_MAX_EVENT_CONTROL_DELAY_QS
Warning
Applications should use emberEventControlSetDelayQS() instead.

Definition at line 246 of file event.h.

◆ emberEventControlSetInactive

#define emberEventControlSetInactive (   control)    do { (control).status = EMBER_EVENT_INACTIVE; } while (0)

Set this EmberEventControl as inactive (no pending event).

Parameters
[in]controlControl of the event to set inactive.

Definition at line 173 of file event.h.

◆ emberMarkTaskActive

#define emberMarkTaskActive (   taskid)    do { emMarkTaskActive((taskid)); } while (0)

Calling it indicates that a task has something to do, so it should prevent the CPU from idling until emberMarkTaskIdle is next called on this task.

Parameters
[in]taskidThe task to mark active.

Definition at line 397 of file event.h.

◆ emberTaskEnableIdling

#define emberTaskEnableIdling (   allow)    do { emTaskEnableIdling((allow)); } while (0)

Enable or disable idling.

Parameters
[in]allowSetting it to true will enable, while setting it to false will disable idling.

Definition at line 382 of file event.h.

Function Documentation

◆ emberMarkTaskIdle()

bool emberMarkTaskIdle ( EmberTaskId  taskid)

Try to idle the CPU, unless any events in any tasks are pending.

Parameters
[in]taskidthe task which should handle the idling.
Returns
Returns true if the processor was idled false if idling wasn't permitted because a task has something to do.
Note
This API should always be called with interrupts disabled. It will forcibly re-enable interrupts before returning.

◆ emberMsToNextEvent()

uint32_t emberMsToNextEvent ( EmberEventData events,
uint32_t  maxMs 
)

Check when the next event is scheduled to run.

Parameters
[in]eventsAn array of events to check.
[in]maxMsIf no event is scheduled before maxMs, maxMs will be returned
Returns
Returns the number of milliseconds before the next event is scheduled to expire, or maxMs if no event is scheduled to expire within that time.
Note
If any events are modified within an interrupt, to guarantee the accuracy of this API, it must be called with interrupts disabled.
See also
emberMsToNextEventExtended()

◆ emberMsToNextEventExtended()

uint32_t emberMsToNextEventExtended ( EmberEventData events,
uint32_t  maxMs,
uint8_t *  returnIndex 
)

Check when the next event is scheduled to run.

Parameters
[in]eventsAn array of events to check.
[in]maxMsIf no event is scheduled before maxMs, maxMs will be returned
[out]returnIndexIf not NULL pointer was passed, the index of the next event will be returned here, or 0xFF if no event is scheduled before maxMs.
Returns
Returns the number of milliseconds before the next event is scheduled to expire, or maxMs if no event is scheduled to expire within that time.
Note
If any events are modified within an interrupt, to guarantee the accuracy of this API, it must be called with interrupts disabled.
See also
emberMsToNextEvent()

◆ emberMsToNextStackEvent()

uint32_t emberMsToNextStackEvent ( void  )

Check when the next stack event is scheduled to run.

Returns
Returns the number of milliseconds before the next stack event is scheduled to run.

◆ emberRunEvents()

void emberRunEvents ( EmberEventData events)

Start an event handler if there is anything scheduled at the moment this function is called.

An application typically creates an array of events along with their handlers. This function should be called in the main loop to run those events.

Parameters
[in]eventsPointer to the array of events.
Warning
This is normally handled by emberRunTask() in the main plugin.

◆ emberRunTask()

void emberRunTask ( EmberTaskId  taskid)

Start an event handler if there is anything scheduled at the moment this function is called.

If an application has initialized a task via emberTaskInit(), to run the events associated with that task, it should call emberRunTask() instead of emberRunEvents().

Warning
This is normally handled by the main plugin.

◆ emberTaskInit()

EmberTaskId emberTaskInit ( EmberEventData events)

Initialize a task for managing events and processor idling state.

Parameters
[in]eventsPointer to the array of events to manage
Returns
Returns the EmberTaskId which represents the newly created task.
Note
After the task is created emberRunTask() should be called periodically.

◆ emEventControlGetRemainingMS()

uint32_t emEventControlGetRemainingMS ( EmberEventControl event)

Check when the event is scheduled to run.

Parameters
[in]eventPointer to the control of the event in question.
Returns
Return the amount of milliseconds remaining before the event is scheduled to run. If the event is inactive, MAX_INT32U_VALUE is returned.
Warning
Applications should use emberEventControlGetRemainingMS() instead.

◆ emEventControlSetActive()

void emEventControlSetActive ( EmberEventControl event)

Set this EmberEventControl to run at the next available opportunity.

Parameters
[in]eventPointer to the control of the event to set active
Warning
Applications should use emberEventControlSetActive() instead.

◆ emEventControlSetDelayMS()

void emEventControlSetDelayMS ( EmberEventControl event,
uint32_t  delay 
)

Set this EmberEventControl to run some milliseconds in the future.

Parameters
[in]eventPointer to the control of the event to run.
[in]delayThe delay in milliseconds. Must be less than EMBER_MAX_EVENT_CONTROL_DELAY_MS
Warning
Applications should use emberEventControlSetDelayMS() instead.

◆ emMarkTaskActive()

void emMarkTaskActive ( EmberTaskId  taskid)

Calling it indicates that a task has something to do, so it should prevent the CPU from idling until emberMarkTaskIdle is next called on this task.

Parameters
[in]taskidThe task to mark active.
Warning
Applications should use emberMarkTaskActive() instead.

◆ emTaskEnableIdling()

void emTaskEnableIdling ( bool  allow)

Enable or disable idling.

Parameters
[in]allowSetting it to true will enable, while setting it to false will disable idling.
Warning
Applications should use emberTaskEnableIdling() instead.