Click here for the API Reference documentation.

Creating/Deleting Timer Objects
Using Timers
Fatal Errors
Troubleshooting

This module provides an API for managing and using timers.

Note: This is an initial version of the API that only provides support for relative timers (e.g., expires in 10 seconds). Absolute timers allow a specific time/date to be used, and will be supported in a future version of this API.

Creating/Deleting Timer Objects

Timers are created using le_timer_Create. The timer name is used for logging purposes only.

The following attributes of the timer can be set:

The repeat count defaults to 1, so that the timer is initially a one-shot timer. All the other attributes must be explicitly set. At a minimum, the interval must be set before the timer can be used. Note that these attributes can only be set if the timer is not currently running; otherwise, an error will be returned.

A timer is deleted using le_timer_Delete. If the timer is currently running, then it will be stopped first, before being deleted.

Using Timers

A timer can be started using le_timer_Start. If it's already running, then it won't be modified; instead an error will be returned. To restart a currently running timer, use le_timer_Restart.

A timer can be stopped using le_timer_Stop. If it is not currently running, an error will be returned, and nothing more will be done.

To determine if the timer is currently running, use le_timer_IsRunning.

When a timer expires, if the timer expiry handler was set by le_timer_SetHandler, the handler will be called with a reference to the expired timer. If additional data is required in the handler, le_timer_SetContextPtr can be used to set the appropriate context before starting the timer, and le_timer_GetContextPtr can be used to retrieve the context while in the handler.

The number of times that a timer has expired can be retrieved by le_timer_GetExpiryCount. This count is independent of whether there is an expiry handler for the timer.

Fatal Errors

The process will exit under any of the following conditions:

If an invalid timer object is given to:

Troubleshooting

Timers can be traced by enabling the log trace keyword "timers" in the "framework" component.

See Log Controls for more information.