Event Scheduling
Scheduling events for future execution. See Event Scheduling for documentation. More...
Macros | |
#define | __EVENT_H__ |
#define | emberEventControlSetInactive(control) |
Sets this EmberEventControl as inactive (no pending event). More... | |
#define | emberEventControlGetActive(control) |
Returns TRUE if the event is active, FALSE otherwise. More... | |
#define | emberEventControlSetActive(control) |
Sets this EmberEventControl to run at the next available opportunity. More... | |
#define | EMBER_MAX_EVENT_CONTROL_DELAY_MS |
The maximum delay that may be passed to emberEventControlSetDelayMS. More... | |
#define | emberEventControlSetDelayMS(control, delay) |
Sets this EmberEventControl to run "delay" milliseconds in the future. NOTE: To avoid rollover errors in event calculation, the delay must be less than EMBER_MAX_EVENT_CONTROL_DELAY_MS. More... | |
#define | EMBER_MAX_EVENT_CONTROL_DELAY_QS |
The maximum delay that may be passed to emberEventControlSetDelayQS. More... | |
#define | emberEventControlSetDelayQS(control, delay) |
Sets this EmberEventControl to run "delay" quarter seconds in the future. The 'quarter seconds' are actually 256 milliseconds long. NOTE: To avoid rollover errors in event calculation, the delay must be less than EMBER_MAX_EVENT_CONTROL_DELAY_QS. More... | |
#define | EMBER_MAX_EVENT_CONTROL_DELAY_MINUTES |
The maximum delay that may be passed to emberEventControlSetDelayMinutes. More... | |
#define | emberEventControlSetDelayMinutes(control, delay) |
Sets this EmberEventControl to run "delay" minutes in the future. The 'minutes' are actually 65536 (0x10000) milliseconds long. NOTE: To avoid rollover errors in event calculation, the delay must be less than EMBER_MAX_EVENT_CONTROL_DELAY_MINUTES. More... | |
#define | emberEventControlGetRemainingMS(control) |
Returns the amount of milliseconds remaining before the event is scheduled to run. If the event is inactive, MAX_INT32U_VALUE is returned. More... | |
#define | emberTaskEnableIdling(allow) |
Indicates that an application supports processor idling. More... | |
#define | emberMarkTaskActive(taskid) |
Indicates that a task has something to do, so the CPU should not be idled until emberMarkTaskIdle is next called on this task. More... | |
Functions | |
void | emEventControlSetActive (EmberEventControl *event) |
Sets this EmberEventControl to run at the next available opportunity. More... | |
void | emEventControlSetDelayMS (EmberEventControl *event, uint32_t delay) |
Sets this EmberEventControl to run "delay" milliseconds in the future. NOTE: To avoid rollover errors in event calculation, the delay must be less than EMBER_MAX_EVENT_CONTROL_DELAY_MS. More... | |
uint32_t | emEventControlGetRemainingMS (EmberEventControl *event) |
Returns the amount of milliseconds remaining before the event is scheduled to run. If the event is inactive, MAX_INT32U_VALUE is returned. More... | |
void | emberRunEvents (EmberEventData *events) |
An application typically creates an array of events along with their handlers. More... | |
void | emberRunTask (EmberTaskId taskid) |
If an application has initialized a task via emberTaskInit, to run the events associated with that task, it should call emberRunTask() instead of emberRunEvents(). More... | |
uint32_t | emberMsToNextEvent (EmberEventData *events, uint32_t maxMs) |
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 or from within an ATOMIC() block. More... | |
uint32_t | emberMsToNextEventExtended (EmberEventData *events, uint32_t maxMs, uint8_t *returnIndex) |
Does the same as emberMsToNextEvent() with the following addition. If the returnIndex is non-NULL, it sets the value pointed to by the pointer to equal the index of the event that is ready to fire next. If no events are active, it returns 0xFF. More... | |
uint32_t | emberMsToNextStackEvent (void) |
Returns the number of milliseconds before the next stack event is scheduled to expire. More... | |
EmberTaskId | emberTaskInit (EmberEventData *events) |
Initializes a task for managing events and processor idling state. Returns the EmberTaskId which represents the newly created task. More... | |
bool | emberMarkTaskIdle (EmberTaskId taskid) |
Indicates that a task has nothing to do, unless any events are pending, and that it would be safe to idle the CPU if all other tasks also have nothing to do. This API should always be called with interrupts disabled. It will forcibly re-enable interrupts before returning. Returns TRUE if the processor was idled, FALSE if idling wasn't permitted because a task has something to do. More... | |
void | emTaskEnableIdling (bool allow) |
void | emMarkTaskActive (EmberTaskId taskid) |
Detailed Description
Scheduling events for future execution. See Event Scheduling for documentation.
License
Copyright 2018 Silicon Laboratories Inc. www.silabs.com
The licensor of this software is Silicon Laboratories Inc. Your use of this software is governed by the terms of Silicon Labs Master Software License Agreement (MSLA) available at www.silabs.com/about-us/legal/master-software-license-agreement. This software is distributed to you in Source Code format and is governed by the sections of the MSLA applicable to Source Code.
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. Each tick is approximately equal to a millisecond, but the true duration depends on the platform. The duration of a tick is 1000 / ::MILLISECOND_TICKS_PER_SECOND, where 1000 is the number of milliseconds per second and ::MILLISECOND_TICKS_PER_SECOND is the platform-specific number of ticks per second. For example, ::MILLISECOND_TICKS_PER_SECOND on the EM357 SoC is 1024, so each tick is 1000 / 1024 = ~0.98 milliseconds. Calling emberEventControlSetDelayMS(someEvent, 100) on the EM357 SoC will schedule the event for 100 ticks * (1000 milliseconds / 1024 ticks) = ~97.7 milliseconds. Note, however, that the accuracy of the base tick depends on the timer source. 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. Calling emberEventControlSetDelayMinutes(someEvent, 3) on the EM357 SoC will schedule the event for 3 minutes * (65536 ticks / minute) * (1000 milliseconds / 1024 ticks) = ~3.2 minutes. It is possible to avoid these binary units by using emberEventControlSetDelayMS and the various MILLISECOND_TICKS_PER_XXX multipliers. For example, calling emberEventControlSetDelayMS(someEvent, 3 * MILLISECOND_TICKS_PER_MINUTE) will delay for 3 minutes on any platform. Be aware of EMBER_MAX_EVENT_CONTROL_DELAY_MS when using this approach.
The following are brief usage examples.
Macro Definition Documentation
#define __EVENT_H__ |
Definition at line 133
of file event.h
.
#define EMBER_MAX_EVENT_CONTROL_DELAY_MINUTES |
The maximum delay that may be passed to emberEventControlSetDelayMinutes.
Definition at line 192
of file event.h
.
#define EMBER_MAX_EVENT_CONTROL_DELAY_MS |
The maximum delay that may be passed to emberEventControlSetDelayMS.
Definition at line 159
of file event.h
.
#define EMBER_MAX_EVENT_CONTROL_DELAY_QS |
The maximum delay that may be passed to emberEventControlSetDelayQS.
Definition at line 179
of file event.h
.
#define emberEventControlGetActive | ( | control | ) |
Returns TRUE if the event is active, FALSE otherwise.
Definition at line 142
of file event.h
.
#define emberEventControlGetRemainingMS | ( | control | ) |
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 205
of file event.h
.
#define emberEventControlSetActive | ( | control | ) |
Sets this EmberEventControl to run at the next available opportunity.
Definition at line 148
of file event.h
.
#define emberEventControlSetDelayMinutes | ( | control, |
|
delay |
|||
) |
Sets this EmberEventControl to run "delay" minutes in the future. The 'minutes' are actually 65536 (0x10000) milliseconds long. NOTE: To avoid rollover errors in event calculation, the delay must be less than EMBER_MAX_EVENT_CONTROL_DELAY_MINUTES.
Definition at line 199
of file event.h
.
#define emberEventControlSetDelayMS | ( | control, |
|
delay |
|||
) |
Sets this EmberEventControl to run "delay" milliseconds in the future. NOTE: To avoid rollover errors in event calculation, the delay must be less than EMBER_MAX_EVENT_CONTROL_DELAY_MS.
Definition at line 166
of file event.h
.
#define emberEventControlSetDelayQS | ( | control, |
|
delay |
|||
) |
Sets this EmberEventControl to run "delay" quarter seconds in the future. The 'quarter seconds' are actually 256 milliseconds long. NOTE: To avoid rollover errors in event calculation, the delay must be less than EMBER_MAX_EVENT_CONTROL_DELAY_QS.
Definition at line 186
of file event.h
.
#define emberEventControlSetInactive | ( | control | ) |
Sets this EmberEventControl as inactive (no pending event).
Definition at line 137
of file event.h
.
#define emberMarkTaskActive | ( | taskid | ) |
Indicates that a task has something to do, so the CPU should not be idled until emberMarkTaskIdle is next called on this task.
Definition at line 277
of file event.h
.
#define emberTaskEnableIdling | ( | allow | ) |
Indicates that an application supports processor idling.
Definition at line 269
of file event.h
.
Function Documentation
bool emberMarkTaskIdle | ( | EmberTaskId | taskid | ) |
Indicates that a task has nothing to do, unless any events are pending, and that it would be safe to idle the CPU if all other tasks also have nothing to do. This API should always be called with interrupts disabled. It will forcibly re-enable interrupts before returning. Returns TRUE if the processor was idled, FALSE if idling wasn't permitted because a task has something to do.
uint32_t emberMsToNextEvent | ( | EmberEventData * | events, |
uint32_t | maxMs |
||
) |
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 or from within an ATOMIC() block.
uint32_t emberMsToNextEventExtended | ( | EmberEventData * | events, |
uint32_t | maxMs, |
||
uint8_t * | returnIndex |
||
) |
Does the same as emberMsToNextEvent() with the following addition. If the returnIndex is non-NULL, it sets the value pointed to by the pointer to equal the index of the event that is ready to fire next. If no events are active, it returns 0xFF.
uint32_t emberMsToNextStackEvent | ( | void |
| ) |
Returns the number of milliseconds before the next stack event is scheduled to expire.
void emberRunEvents | ( | EmberEventData * | events | ) |
An application typically creates an array of events along with their handlers.
The main loop passes the array to emberRunEvents() to call the handlers of any events whose time has arrived.
void emberRunTask | ( | EmberTaskId | taskid | ) |
If an application has initialized a task via emberTaskInit, to run the events associated with that task, it should call emberRunTask() instead of emberRunEvents().
EmberTaskId emberTaskInit | ( | EmberEventData * | events | ) |
Initializes a task for managing events and processor idling state. Returns the EmberTaskId which represents the newly created task.
uint32_t emEventControlGetRemainingMS | ( | EmberEventControl * | event | ) |
Returns the amount of milliseconds remaining before the event is scheduled to run. If the event is inactive, MAX_INT32U_VALUE is returned.
void emEventControlSetActive | ( | EmberEventControl * | event | ) |
Sets this EmberEventControl to run at the next available opportunity.
void emEventControlSetDelayMS | ( | EmberEventControl * | event, |
uint32_t | delay |
||
) |
Sets this EmberEventControl to run "delay" milliseconds in the future. NOTE: To avoid rollover errors in event calculation, the delay must be less than EMBER_MAX_EVENT_CONTROL_DELAY_MS.
void emMarkTaskActive | ( | EmberTaskId | taskid | ) |
void emTaskEnableIdling | ( | bool | allow | ) |