Skip to content

DS_CAP_TIMERS

Jump to bottom
Denis Stepanov edited this page Apr 26, 2021 · 15 revisions

DS_CAP_TIMERS — Timer Support

Description

This capability add support for timers, used to execute certain actions in future. The way to define future event is determined by the timer type. Grossly, there are two ways of designating future time: absolute — when system has notion of system time and can be programmed for a future timestamp — and relative — when system does not have notion of time but can be programmed for some point in future using some time counting technique relative to the original time point. The library supports several classes of timers:

  • Absolute timer — fires at a given time in future
  • Solar timer — fires on sun-related event (sunrise or sunset)
  • Countdown timer — fires after some time period from now

Timer actions are specified using a string called "action". When a timer event fires, the library calls a user-defined callback function, which can check the timer "action" property in order to decide which code to execute.

This capability defines an abstract timer interface (ds::Timer class); in order to actually use a timer, user has to select one of the timer implementations listed below. ds::Timer class has the following fields implemented:

Field Type Description Default Value
id int Timer identifier (optional) -1
type ds::timer_type_t Timer type (none)
action String Timer action "undefined"
armed bool True if timer is armed (will fire); false if ignored with no action true
recurrent bool True if timer should be auto-rearmed after firing; false otherwise true
transient bool True if timer should be disposed of after firing false

Timer ID is not required for correct functioning of the library, but it could be useful to store some external identifier (e.g., order of display on a web page).

Timer type could be one of the following constants:

Timer Type Description
TIMER_ABSOLUTE Timer fires at a given absolute time
TIMER_SUNRISE Timer fires at sunrise
TIMER_SUNSET Timer fires at sunset
TIMER_COUNTDOWN_ABS Timer fires at some moment from now, counted via absolute time
TIMER_COUNTDOWN_TICK Timer fires at some moment from now, counted via Ticker function
TIMER_INVALID Unsupported timer type or misconfigured timer

Timers are declared invalid if incorrect or contradictory information is passed to a timer constructor. Invalid timers are ignored during processing.

Marking timer as transient will render it unusable (destroy) after firing once. This normally only has meaning in the context of collection of timers, in which case the timer will be excluded from collection.

To operate these fields, the following methods are implemented:

int Timer::getID() const;                      // Return timer identifier
void Timer::setID(const int new_id);           // Set timer identifier
timer_type_t Timer::getType() const;           // Get timer type
const String& Timer::getAction() const;        // Return timer action
void Timer::setAction(const String& new_action); // Set timer action
bool Timer::isArmed() const;                   // Return true if timer is armed
void Timer::arm();                             // Arm the timer (default)
void Timer::disarm();                          // Disarm the timer
bool Timer::isRecurrent() const;               // Return true if timer is recurrent
void Timer::repeatForever();                   // Make timer repetitive (default)
void Timer::repeatOnce();                      // Make timer a one-time shot
bool Timer::isTransient() const;               // Return true if timer is transient (i.e., will be dead after firing)
void Timer::keep();                            // Keep the timer around (default)
void Timer::forget();                          // Mark the timer for disposal

There is no public method to set timer type. Normally, timer type should be known by the time of timer construction.

One can compare abstract timers. Two abstract timers are considered equal when their types, IDs and actions match.

Requires

None.

Cooperates With

None.

Conflicts With

None.

Usage

None. See the corresponding timer implementations.

Mandatory Calls

System::begin() Not required
System::update() Not required

Note that while this capability per se does not these calls, the underlying implementations, like absolute timer, would most likely need them to work correctly. Check their respective pages for details.

Examples

Bugs

None.

See Also

Home

Capabilities

Clone this wiki locally