Evented timers

Timers whose callbacks run on the registering task's event loop. More...

Macros
#define	EVENTED_TIMER_INVALID_ID   0
	Invalid timer handle.

Typedefs
typedef uintptr_t	EventedTimerID
	Evented timer handle.
typedef void(*	EventedTimerCallback) (void *data)
	Timer callback, run on the task that registered the timer.

Functions
void	evented_timer_init (void)
	Initialize the evented timer service, once at startup.
void	evented_timer_clear_process_timers (PebbleTask task)
	Cancel all timers of a task, without calling their callbacks.
EventedTimerID	evented_timer_register (uint32_t timeout_ms, bool repeating, EventedTimerCallback callback, void *callback_data)
	Start a timer.
bool	evented_timer_reschedule (EventedTimerID timer, uint32_t new_timeout_ms)
	Restart a pending timer with a new timeout.
EventedTimerID	evented_timer_register_or_reschedule (EventedTimerID timer_id, uint32_t timeout_ms, EventedTimerCallback callback, void *data)
	Reschedule a timer, or register a new one-shot timer if that is not possible.
void	evented_timer_cancel (EventedTimerID timer)
	Cancel a timer.
bool	evented_timer_exists (EventedTimerID timer)
	Check whether a timer exists.
bool	evented_timer_is_current_task (EventedTimerID timer)
	Check whether a timer belongs to the current task.
void	evented_timer_reset (void)
	Forget all timers, without freeing them.
void *	evented_timer_get_data (EventedTimerID timer)
	Get the callback data of a timer.

Detailed Description

Timers whose callbacks run on the registering task's event loop.

Callbacks run as events on the task that registered the timer (KernelMain, App or Worker), so they need no locking against the rest of that task's code. Timers are backed by new timers; when they fire, a callback event is posted to the owning task. A one-shot timer is freed right before its callback runs.

static EventedTimerID s_timer = EVENTED_TIMER_INVALID_ID;
 
static void prv_timeout(void *data) {
  s_timer = EVENTED_TIMER_INVALID_ID;
  // runs on the task that registered the timer
}
 
// Start, or push back if already running.
s_timer = evented_timer_register_or_reschedule(s_timer, 500, prv_timeout, NULL);
 
// Stop it.
evented_timer_cancel(s_timer);
s_timer = EVENTED_TIMER_INVALID_ID;

Macro Definition Documentation

EVENTED_TIMER_INVALID_ID

#define EVENTED_TIMER_INVALID_ID   0

Invalid timer handle.

Typedef Documentation

EventedTimerCallback

typedef void(* EventedTimerCallback) (void *data)

Timer callback, run on the task that registered the timer.

Parameters

data	Data given when registering the timer.

EventedTimerID

typedef uintptr_t EventedTimerID

Evented timer handle.

Function Documentation

evented_timer_cancel()

void evented_timer_cancel

(

EventedTimerID

timer

)

Cancel a timer.

The callback will not run, even if the timer has already fired. No-op if timer is EVENTED_TIMER_INVALID_ID or no longer exists.

Parameters

timer

Timer to cancel.

evented_timer_clear_process_timers()

void evented_timer_clear_process_timers

(

PebbleTask

task

)

Cancel all timers of a task, without calling their callbacks.

Called by the kernel on KernelMain when a process exits.

Parameters

task	Task whose timers are cancelled.

evented_timer_exists()

bool evented_timer_exists

(

EventedTimerID

timer

)

Check whether a timer exists.

Parameters

timer

Timer to check.

Returns

true if the timer is pending or its callback has not run yet.

evented_timer_get_data()

void * evented_timer_get_data

(

EventedTimerID

timer

)

Get the callback data of a timer.

Parameters

timer

Timer.

Returns

Data given when registering the timer, or NULL if the timer does not exist.

evented_timer_init()

void evented_timer_init

(

void

)

Initialize the evented timer service, once at startup.

evented_timer_is_current_task()

bool evented_timer_is_current_task

(

EventedTimerID

timer

)

Check whether a timer belongs to the current task.

Parameters

timer

Existing timer; asserts otherwise.

Returns

true if the timer was registered by the current task.

evented_timer_register()

EventedTimerID evented_timer_register	(	uint32_t	timeout_ms,
		bool	repeating,
		EventedTimerCallback	callback,
		void *	callback_data
	)

Start a timer.

Must be called from KernelMain, App or Worker.

Parameters

timeout_ms	Delay in milliseconds; 0 is treated as 1.
repeating	true to fire every timeout_ms until cancelled.
callback	Callback to run.
callback_data	Data passed to callback.

Returns

Timer handle.

evented_timer_register_or_reschedule()

EventedTimerID evented_timer_register_or_reschedule	(	EventedTimerID	timer_id,
		uint32_t	timeout_ms,
		EventedTimerCallback	callback,
		void *	data
	)

Reschedule a timer, or register a new one-shot timer if that is not possible.

Parameters

timer_id	Timer to reschedule, or EVENTED_TIMER_INVALID_ID.
timeout_ms	Delay in milliseconds.
callback	Callback of the new timer.
data	Data passed to callback by the new timer.

Returns

timer_id if it was rescheduled, else the handle of the new timer.

evented_timer_reschedule()

bool evented_timer_reschedule	(	EventedTimerID	timer,
		uint32_t	new_timeout_ms
	)

Restart a pending timer with a new timeout.

Must be called from the task that registered the timer.

Parameters

timer	Timer to reschedule.
new_timeout_ms	New delay in milliseconds, from now; 0 is treated as 1.

Returns

true on success, false if the timer does not exist or has already fired.

evented_timer_reset()

void evented_timer_reset

(

void

)

Forget all timers, without freeing them.

Only for unit tests.