Timers

Lightweight callback-based scheduling for periodic work and one-shot delays. More...

Collaboration diagram for Timers:

Macros
#define	SYS_TIMER_CAPACITY   8
	Maximum number of timers available in static-pool implementations.

Typedefs
typedef struct sys_timer_t	sys_timer_t
	Timer.

Lifecycle
sys_timer_t *	sys_timer_init (uint32_t interval_ms, void(*callback)(sys_timer_t *), void *userdata)
	Allocate and configure a timer from the pool. More...
void	sys_timer_deinit (sys_timer_t *timer)
	Stop and release a timer back to the pool. More...

Methods
bool	sys_timer_start (sys_timer_t *timer)
	Start a timer. More...
void *	sys_timer_userdata (sys_timer_t *timer)
	Return user data associated with a timer. More...

Detailed Description

Lightweight callback-based scheduling for periodic work and one-shot delays.

The timer module provides lightweight callback-based scheduling for periodic work and one-shot delays.

Timers are allocated from an implementation-defined pool. After sys_timer_init(), timers are configured but idle; work begins only after sys_timer_start() succeeds.

Callback model:

• The callback receives the owning sys_timer_t * handle.
• The timer userdata pointer is retrievable via sys_timer_userdata().
• One-shot behavior is implemented by calling sys_timer_deinit() from within the callback.

Lifecycle summary:

1. Create with sys_timer_init(interval_ms, callback, userdata).
2. Start with sys_timer_start().
3. Release with sys_timer_deinit().

Platform note:

• On Pico, the timer callback will always execute on the same core that started the timer, within an interrupt context.

Function Documentation

sys_timer_deinit()

void sys_timer_deinit

(

sys_timer_t *

timer

)

Stop and release a timer back to the pool.

Parameters

timer

Timer to release.

Stops the timer if it is running and returns its pool slot. If a callback is currently executing on another thread or core, this call waits for it to finish before returning. The pointer becomes invalid after this call. Safe to call from within the timer callback to implement one-shot behaviour.

sys_timer_init()

sys_timer_t* sys_timer_init	(	uint32_t	interval_ms,
		void(*)(sys_timer_t *)	callback,
		void *	userdata
	)

Allocate and configure a timer from the pool.

Parameters

interval_ms	Interval at which the timer fires, in milliseconds.
callback	Function called each time the timer fires.
userdata	Optional pointer passed to the callback on each fire.

Returns

Pointer to an initialized timer, or NULL if the pool is exhausted.

The timer is not started until sys_timer_start() is called. Release the timer with sys_timer_deinit() when it is no longer needed. Implementations that use a static pool will return NULL after SYS_TIMER_CAPACITY timers have been allocated.

To implement a one-shot timer, call sys_timer_deinit() from inside the callback.

sys_timer_start()

bool sys_timer_start

(

sys_timer_t *

timer

)

Start a timer.

Parameters

timer

Timer to start.

Returns

true on success, false if the timer is invalid or already running.

sys_timer_userdata()

void* sys_timer_userdata

(

sys_timer_t *

timer

)

Return user data associated with a timer.

Parameters

timer

Timer to query.

Returns

User data pointer provided to sys_timer_init, or NULL.