Regular timers

Callbacks run every N seconds or every N minutes. More...

Data Structures
struct	RegularTimerInfo
	Regular timer registration, owned by the caller. More...

Typedefs
typedef void(*	RegularTimerCallback) (void *data)
	Regular timer callback.

Functions
void	regular_timer_init (void)
	Initialize the service and start the shared timer.
void	regular_timer_add_seconds_callback (RegularTimerInfo *cb)
	Run a callback every second.
void	regular_timer_add_multisecond_callback (RegularTimerInfo *cb, uint16_t seconds)
	Run a callback every seconds seconds.
void	regular_timer_add_minutes_callback (RegularTimerInfo *cb)
	Run a callback every minute.
void	regular_timer_add_multiminute_callback (RegularTimerInfo *cb, uint16_t minutes)
	Run a callback every minutes minutes.
bool	regular_timer_remove_callback (RegularTimerInfo *cb)
	Unregister a seconds or minutes timer.
bool	regular_timer_is_scheduled (RegularTimerInfo *cb)
	Check whether a timer is registered.
bool	regular_timer_pending_deletion (RegularTimerInfo *cb)
	Check whether a timer is pending deletion.
void	regular_timer_deinit (void)
	Stop the shared timer, for tests.
void	regular_timer_fire_seconds (uint8_t secs)
	Fire the seconds timers whose period is a multiple of secs, for tests.
void	regular_timer_fire_minutes (uint8_t mins)
	Fire the minutes timers whose period is a multiple of mins, for tests.
uint32_t	regular_timer_seconds_count (void)
	Count the registered seconds timers, for tests.
uint32_t	regular_timer_minutes_count (void)
	Count the registered minutes timers, for tests.

Detailed Description

Callbacks run every N seconds or every N minutes.

All regular timers share one timer aligned to the RTC second boundary, so periodic work wakes the system at the same time. Second callbacks run shortly after each second boundary, minute callbacks when the wall-clock minute changes. Callbacks run on the NewTimers task and must not block for long.

The caller owns the RegularTimerInfo, which must stay valid while registered:

static void prv_tick(void *data) {
  // Runs on the NewTimers task every 5 seconds.
}
 
static RegularTimerInfo s_timer = {
  .cb = prv_tick,
};
 
regular_timer_add_multisecond_callback(&s_timer, 5);
...
regular_timer_remove_callback(&s_timer);

---

Data Structure Documentation

RegularTimerInfo

struct RegularTimerInfo

Regular timer registration, owned by the caller.

Data Fields
RegularTimerCallback	cb	Callback to run.
void *	cb_data	Context passed to the callback.

Typedef Documentation

RegularTimerCallback

typedef void(* RegularTimerCallback) (void *data)

Regular timer callback.

Parameters

data	RegularTimerInfo::cb_data.

Function Documentation

regular_timer_add_minutes_callback()

void regular_timer_add_minutes_callback

(

RegularTimerInfo *

cb

)

Run a callback every minute.

Parameters

cb	Timer to register.

regular_timer_add_multiminute_callback()

void regular_timer_add_multiminute_callback	(	RegularTimerInfo *	cb,
		uint16_t	minutes
	)

Run a callback every minutes minutes.

Can also change the period of a registered minutes timer, from inside or outside its callback. Re-adding a timer pending deletion cancels the deletion. A timer cannot be both a seconds and a minutes timer.

Parameters

cb	Timer to register.
minutes	Period in minutes.

regular_timer_add_multisecond_callback()

void regular_timer_add_multisecond_callback	(	RegularTimerInfo *	cb,
		uint16_t	seconds
	)

Run a callback every seconds seconds.

Can also change the period of a registered seconds timer, from inside or outside its callback. Re-adding a timer pending deletion cancels the deletion. A timer cannot be both a seconds and a minutes timer.

Parameters

cb	Timer to register.
seconds	Period in seconds.

regular_timer_add_seconds_callback()

void regular_timer_add_seconds_callback

(

RegularTimerInfo *

cb

)

Run a callback every second.

Parameters

cb	Timer to register.

regular_timer_deinit()

void regular_timer_deinit

(

void

)

Stop the shared timer, for tests.

regular_timer_fire_minutes()

void regular_timer_fire_minutes

(

uint8_t

mins

)

Fire the minutes timers whose period is a multiple of mins, for tests.

Parameters

mins	Period divisor.

regular_timer_fire_seconds()

void regular_timer_fire_seconds

(

uint8_t

secs

)

Fire the seconds timers whose period is a multiple of secs, for tests.

Parameters

secs	Period divisor.

regular_timer_init()

void regular_timer_init

(

void

)

Initialize the service and start the shared timer.

regular_timer_is_scheduled()

bool regular_timer_is_scheduled

(

RegularTimerInfo *

cb

)

Check whether a timer is registered.

Parameters

cb	Timer to check.

Returns

True if registered, including when pending deletion.

regular_timer_minutes_count()

uint32_t regular_timer_minutes_count

(

void

)

Count the registered minutes timers, for tests.

Returns

Number of timers.

regular_timer_pending_deletion()

bool regular_timer_pending_deletion

(

RegularTimerInfo *

cb

)

Check whether a timer is pending deletion.

A timer is pending deletion when it was removed while its callback was running.

Parameters

cb	Timer to check.

Returns

True if pending deletion.

regular_timer_remove_callback()

bool regular_timer_remove_callback

(

RegularTimerInfo *

cb

)

Unregister a seconds or minutes timer.

If the callback is running, the timer is only marked for deletion and is removed when the callback returns. When called from the callback itself, the RegularTimerInfo must not be freed until the callback has returned.

Parameters

cb	Timer to unregister.

Return values

true	The timer was removed.
false	The timer was not registered, or is running and was marked for deletion.

regular_timer_seconds_count()

uint32_t regular_timer_seconds_count

(

void

)

Count the registered seconds timers, for tests.

Returns

Number of timers.