Alarm functions for scheduling future execution. More...

Macros
#define	PICO_TIME_DEFAULT_ALARM_POOL_DISABLED 0
	If 1 then the default alarm pool is disabled (so no hardware alarm is claimed for the pool) More...

#define	PICO_TIME_DEFAULT_ALARM_POOL_HARDWARE_ALARM_NUM 3
	Selects which hardware alarm is used for the default alarm pool. More...

#define	PICO_TIME_DEFAULT_ALARM_POOL_MAX_TIMERS 16
	Selects the maximum number of concurrent timers in the default alarm pool. More...

Typedefs
typedef int32_t	alarm_id_t
	The identifier for an alarm. More...

typedef int64_t(*	alarm_callback_t) (alarm_id_t id, void *user_data)
	User alarm callback. More...

Functions
void	alarm_pool_init_default (void)
	Create the default alarm pool (if not already created or disabled)

alarm_pool_t *	alarm_pool_get_default (void)
	The default alarm pool used when alarms are added without specifying an alarm pool, and also used by the SDK to support lower power sleeps and timeouts. More...

alarm_pool_t *	alarm_pool_create (uint hardware_alarm_num, uint max_timers)
	Create an alarm pool. More...

alarm_pool_t *	alarm_pool_create_with_unused_hardware_alarm (uint max_timers)
	Create an alarm pool, claiming an used hardware alarm to back it. More...

uint	alarm_pool_hardware_alarm_num (alarm_pool_t *pool)
	Return the hardware alarm used by an alarm pool. More...

uint	alarm_pool_core_num (alarm_pool_t *pool)
	Return the core number the alarm pool was initialized on (and hence callbacks are called on) More...

void	alarm_pool_destroy (alarm_pool_t *pool)
	Destroy the alarm pool, cancelling all alarms and freeing up the underlying hardware alarm. More...

alarm_id_t	alarm_pool_add_alarm_at (alarm_pool_t pool, absolute_time_t time, alarm_callback_t callback, void user_data, bool fire_if_past)
	Add an alarm callback to be called at a specific time. More...

alarm_id_t	alarm_pool_add_alarm_at_force_in_context (alarm_pool_t pool, absolute_time_t time, alarm_callback_t callback, void user_data)
	Add an alarm callback to be called at or after a specific time. More...

static alarm_id_t	alarm_pool_add_alarm_in_us (alarm_pool_t pool, uint64_t us, alarm_callback_t callback, void user_data, bool fire_if_past)
	Add an alarm callback to be called after a delay specified in microseconds. More...

static alarm_id_t	alarm_pool_add_alarm_in_ms (alarm_pool_t pool, uint32_t ms, alarm_callback_t callback, void user_data, bool fire_if_past)
	Add an alarm callback to be called after a delay specified in milliseconds. More...

bool	alarm_pool_cancel_alarm (alarm_pool_t *pool, alarm_id_t alarm_id)
	Cancel an alarm. More...

static alarm_id_t	add_alarm_at (absolute_time_t time, alarm_callback_t callback, void *user_data, bool fire_if_past)
	Add an alarm callback to be called at a specific time. More...

static alarm_id_t	add_alarm_in_us (uint64_t us, alarm_callback_t callback, void *user_data, bool fire_if_past)
	Add an alarm callback to be called after a delay specified in microseconds. More...

static alarm_id_t	add_alarm_in_ms (uint32_t ms, alarm_callback_t callback, void *user_data, bool fire_if_past)
	Add an alarm callback to be called after a delay specified in milliseconds. More...

static bool	cancel_alarm (alarm_id_t alarm_id)
	Cancel an alarm from the default alarm pool. More...

Detailed Description

Alarm functions for scheduling future execution.

Alarms are added to alarm pools, which may hold a certain fixed number of active alarms. Each alarm pool utilizes one of four underlying hardware alarms, thus you may have up to four alarm pools. An alarm pool calls (except when the callback would happen before or during being set) the callback on the core from which the alarm pool was created. Callbacks are called from the hardware alarm IRQ handler, so care must be taken in their implementation.

A default pool is created the core specified by PICO_TIME_DEFAULT_ALARM_POOL_HARDWARE_ALARM_NUM on core 0, and may be used by the method variants that take no alarm pool parameter.

See also: struct alarm_pool; hardware_timer

Macro Definition Documentation

◆ PICO_TIME_DEFAULT_ALARM_POOL_DISABLED

#define PICO_TIME_DEFAULT_ALARM_POOL_DISABLED 0

If 1 then the default alarm pool is disabled (so no hardware alarm is claimed for the pool)

Note: Setting to 1 may cause some code not to compile as default timer pool related methods are removed; When the default alarm pool is disabled, sleep_ methods and timeouts are no longer lower powered (they become busy_wait_)

See also: PICO_TIME_DEFAULT_ALARM_POOL_HARDWARE_ALARM_NUM; alarm_pool_get_default()

◆ PICO_TIME_DEFAULT_ALARM_POOL_HARDWARE_ALARM_NUM

#define PICO_TIME_DEFAULT_ALARM_POOL_HARDWARE_ALARM_NUM 3

Selects which hardware alarm is used for the default alarm pool.

See also: alarm_pool_get_default()

◆ PICO_TIME_DEFAULT_ALARM_POOL_MAX_TIMERS

#define PICO_TIME_DEFAULT_ALARM_POOL_MAX_TIMERS 16

Selects the maximum number of concurrent timers in the default alarm pool.

Note: For implementation reasons this is limited to PICO_PHEAP_MAX_ENTRIES which defaults to 255

See also: PICO_TIME_DEFAULT_ALARM_POOL_HARDWARE_ALARM_NUM; alarm_pool_get_default()

Typedef Documentation

◆ alarm_callback_t

typedef int64_t(* alarm_callback_t) (alarm_id_t id, void *user_data)

User alarm callback.

Parameters

id	the alarm_id as returned when the alarm was added
user_data	the user data passed when the alarm was added

Returns: <0 to reschedule the same alarm this many us from the time the alarm was previously scheduled to fire; >0 to reschedule the same alarm this many us from the time this method returns; 0 to not reschedule the alarm

◆ alarm_id_t

typedef int32_t alarm_id_t

The identifier for an alarm.

Note: this identifier is signed because -1 is used as an error condition when creating alarms; alarm ids may be reused, however for convenience the implementation makes an attempt to defer reusing as long as possible. You should certainly expect it to be hundreds of ids before one is reused, although in most cases it is more. Nonetheless care must still be taken when cancelling alarms or other functionality based on alarms when the alarm may have expired, as eventually the alarm id may be reused for another alarm.

Function Documentation

◆ add_alarm_at()

static alarm_id_t add_alarm_at	(	absolute_time_t	time,
		alarm_callback_t	callback,
		void *	user_data,
		bool	fire_if_past
	)

inlinestatic

Add an alarm callback to be called at a specific time.

Generally the callback is called as soon as possible after the time specified from an IRQ handler on the core of the default alarm pool (generally core 0). If the callback is in the past or happens before the alarm setup could be completed, then this method will optionally call the callback itself and then return a return code to indicate that the target time has passed.

Note: It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.

Parameters

time	the timestamp when (after which) the callback should fire
callback	the callback function
user_data	user data to pass to the callback function
fire_if_past	if true, and the alarm time falls before or during this call before the alarm can be set, then the callback should be called during (by) this function instead

Returns: >0 the alarm id; 0 if the alarm time passed before or during the call AND there is no active alarm to return the id of. The latter can either happen because fire_if_past was false (i.e. no timer was ever created), or if the callback was called during this method but the callback cancelled itself by returning 0; -1 if there were no alarm slots available

◆ add_alarm_in_ms()

static alarm_id_t add_alarm_in_ms	(	uint32_t	ms,
		alarm_callback_t	callback,
		void *	user_data,
		bool	fire_if_past
	)

inlinestatic

Add an alarm callback to be called after a delay specified in milliseconds.

Generally the callback is called as soon as possible after the time specified from an IRQ handler on the core of the default alarm pool (generally core 0). If the callback is in the past or happens before the alarm setup could be completed, then this method will optionally call the callback itself and then return a return code to indicate that the target time has passed.

Note: It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.

Parameters

ms	the delay (from now) in milliseconds when (after which) the callback should fire
callback	the callback function
user_data	user data to pass to the callback function
fire_if_past	if true, and the alarm time falls during this call before the alarm can be set, then the callback should be called during (by) this function instead

Returns: >0 the alarm id; 0 if the alarm time passed before or during the call AND there is no active alarm to return the id of. The latter can either happen because fire_if_past was false (i.e. no timer was ever created), or if the callback was called during this method but the callback cancelled itself by returning 0; -1 if there were no alarm slots available

◆ add_alarm_in_us()

static alarm_id_t add_alarm_in_us	(	uint64_t	us,
		alarm_callback_t	callback,
		void *	user_data,
		bool	fire_if_past
	)

inlinestatic

Add an alarm callback to be called after a delay specified in microseconds.

Generally the callback is called as soon as possible after the time specified from an IRQ handler on the core of the default alarm pool (generally core 0). If the callback is in the past or happens before the alarm setup could be completed, then this method will optionally call the callback itself and then return a return code to indicate that the target time has passed.

Note: It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.

Parameters

us	the delay (from now) in microseconds when (after which) the callback should fire
callback	the callback function
user_data	user data to pass to the callback function
fire_if_past	if true, and the alarm time falls during this call before the alarm can be set, then the callback should be called during (by) this function instead

Returns: >0 the alarm id; 0 if the alarm time passed before or during the call AND there is no active alarm to return the id of. The latter can either happen because fire_if_past was false (i.e. no timer was ever created), or if the callback was called during this method but the callback cancelled itself by returning 0; -1 if there were no alarm slots available

◆ alarm_pool_add_alarm_at()

alarm_id_t alarm_pool_add_alarm_at	(	alarm_pool_t *	pool,
		absolute_time_t	time,
		alarm_callback_t	callback,
		void *	user_data,
		bool	fire_if_past
	)

Add an alarm callback to be called at a specific time.

Generally the callback is called as soon as possible after the time specified from an IRQ handler on the core the alarm pool was created on. If the callback is in the past or happens before the alarm setup could be completed, then this method will optionally call the callback itself and then return a return code to indicate that the target time has passed.

Note: It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.

Parameters

pool	the alarm pool to use for scheduling the callback (this determines which hardware alarm is used, and which core calls the callback)
time	the timestamp when (after which) the callback should fire
callback	the callback function
user_data	user data to pass to the callback function
fire_if_past	if true, and the alarm time falls before or during this call before the alarm can be set, then the callback should be called during (by) this function instead

Returns: >0 the alarm id for an active (at the time of return) alarm; 0 if the alarm time passed before or during the call AND there is no active alarm to return the id of. The latter can either happen because fire_if_past was false (i.e. no timer was ever created), or if the callback was called during this method but the callback cancelled itself by returning 0; -1 if there were no alarm slots available

◆ alarm_pool_add_alarm_at_force_in_context()

alarm_id_t alarm_pool_add_alarm_at_force_in_context	(	alarm_pool_t *	pool,
		absolute_time_t	time,
		alarm_callback_t	callback,
		void *	user_data
	)

Add an alarm callback to be called at or after a specific time.

The callback is called as soon as possible after the time specified from an IRQ handler on the core the alarm pool was created on. Unlike alarm_pool_add_alarm_at, this method guarantees to call the callback from that core even if the time is during this method call or in the past.

Note: It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.

Parameters

pool	the alarm pool to use for scheduling the callback (this determines which hardware alarm is used, and which core calls the callback)
time	the timestamp when (after which) the callback should fire
callback	the callback function
user_data	user data to pass to the callback function

Returns: >0 the alarm id for an active (at the time of return) alarm; -1 if there were no alarm slots available

◆ alarm_pool_add_alarm_in_ms()

static alarm_id_t alarm_pool_add_alarm_in_ms	(	alarm_pool_t *	pool,
		uint32_t	ms,
		alarm_callback_t	callback,
		void *	user_data,
		bool	fire_if_past
	)

inlinestatic

Add an alarm callback to be called after a delay specified in milliseconds.

Generally the callback is called as soon as possible after the time specified from an IRQ handler on the core the alarm pool was created on. If the callback is in the past or happens before the alarm setup could be completed, then this method will optionally call the callback itself and then return a return code to indicate that the target time has passed.

Note: It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.

Parameters

pool	the alarm pool to use for scheduling the callback (this determines which hardware alarm is used, and which core calls the callback)
ms	the delay (from now) in milliseconds when (after which) the callback should fire
callback	the callback function
user_data	user data to pass to the callback function
fire_if_past	if true, and the alarm time falls before or during this call before the alarm can be set, then the callback should be called during (by) this function instead

Returns: >0 the alarm id; 0 if the alarm time passed before or during the call AND there is no active alarm to return the id of. The latter can either happen because fire_if_past was false (i.e. no timer was ever created), or if the callback was called during this method but the callback cancelled itself by returning 0; -1 if there were no alarm slots available

◆ alarm_pool_add_alarm_in_us()

static alarm_id_t alarm_pool_add_alarm_in_us	(	alarm_pool_t *	pool,
		uint64_t	us,
		alarm_callback_t	callback,
		void *	user_data,
		bool	fire_if_past
	)

inlinestatic

Add an alarm callback to be called after a delay specified in microseconds.

Generally the callback is called as soon as possible after the time specified from an IRQ handler on the core the alarm pool was created on. If the callback is in the past or happens before the alarm setup could be completed, then this method will optionally call the callback itself and then return a return code to indicate that the target time has passed.

Note: It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.

Parameters

pool	the alarm pool to use for scheduling the callback (this determines which hardware alarm is used, and which core calls the callback)
us	the delay (from now) in microseconds when (after which) the callback should fire
callback	the callback function
user_data	user data to pass to the callback function
fire_if_past	if true, and the alarm time falls during this call before the alarm can be set, then the callback should be called during (by) this function instead

Returns: >0 the alarm id; 0 if the alarm time passed before or during the call AND there is no active alarm to return the id of. The latter can either happen because fire_if_past was false (i.e. no timer was ever created), or if the callback was called during this method but the callback cancelled itself by returning 0; -1 if there were no alarm slots available

◆ alarm_pool_cancel_alarm()

bool alarm_pool_cancel_alarm	(	alarm_pool_t *	pool,
		alarm_id_t	alarm_id
	)

Cancel an alarm.

Parameters

pool	the alarm_pool containing the alarm
alarm_id	the alarm

Returns: true if the alarm was cancelled, false if it didn't exist

See also: alarm_id_t for a note on reuse of IDs

◆ alarm_pool_core_num()

uint alarm_pool_core_num ( alarm_pool_t * pool )

Return the core number the alarm pool was initialized on (and hence callbacks are called on)

Parameters

pool the pool

Returns: the core used by the pool

◆ alarm_pool_create()

alarm_pool_t* alarm_pool_create	(	uint	hardware_alarm_num,
		uint	max_timers
	)

Create an alarm pool.

The alarm pool will call callbacks from an alarm IRQ Handler on the core of this function is called from.

In many situations there is never any need for anything other than the default alarm pool, however you might want to create another if you want alarm callbacks on core 1 or require alarm pools of different priority (IRQ priority based preemption of callbacks)

Note: This method will hard assert if the hardware alarm is already claimed.

Parameters

hardware_alarm_num	the hardware alarm to use to back this pool
max_timers	the maximum number of timers

Note: For implementation reasons this is limited to PICO_PHEAP_MAX_ENTRIES which defaults to 255

See also: alarm_pool_get_default(); hardware_claiming

◆ alarm_pool_create_with_unused_hardware_alarm()

alarm_pool_t* alarm_pool_create_with_unused_hardware_alarm ( uint max_timers )

Create an alarm pool, claiming an used hardware alarm to back it.

The alarm pool will call callbacks from an alarm IRQ Handler on the core of this function is called from.

In many situations there is never any need for anything other than the default alarm pool, however you might want to create another if you want alarm callbacks on core 1 or require alarm pools of different priority (IRQ priority based preemption of callbacks)

Note: This method will hard assert if the there is no free hardware to claim.

Parameters

max_timers the maximum number of timers

Note: For implementation reasons this is limited to PICO_PHEAP_MAX_ENTRIES which defaults to 255

See also: alarm_pool_get_default(); hardware_claiming

◆ alarm_pool_destroy()

void alarm_pool_destroy ( alarm_pool_t * pool )

Destroy the alarm pool, cancelling all alarms and freeing up the underlying hardware alarm.

Parameters

pool the pool

◆ alarm_pool_get_default()

alarm_pool_t* alarm_pool_get_default ( void )

The default alarm pool used when alarms are added without specifying an alarm pool, and also used by the SDK to support lower power sleeps and timeouts.

See also: PICO_TIME_DEFAULT_ALARM_POOL_HARDWARE_ALARM_NUM

◆ alarm_pool_hardware_alarm_num()

uint alarm_pool_hardware_alarm_num ( alarm_pool_t * pool )

Return the hardware alarm used by an alarm pool.

Parameters

pool the pool

Returns: the hardware alarm used by the pool

◆ cancel_alarm()

static bool cancel_alarm ( alarm_id_t alarm_id )

inlinestatic

Cancel an alarm from the default alarm pool.

Parameters

alarm_id the alarm

Returns: true if the alarm was cancelled, false if it didn't exist

See also: alarm_id_t for a note on reuse of IDs

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ PICO_TIME_DEFAULT_ALARM_POOL_DISABLED

◆ PICO_TIME_DEFAULT_ALARM_POOL_HARDWARE_ALARM_NUM

◆ PICO_TIME_DEFAULT_ALARM_POOL_MAX_TIMERS

Typedef Documentation

◆ alarm_callback_t

◆ alarm_id_t

Function Documentation

◆ add_alarm_at()

◆ add_alarm_in_ms()

◆ add_alarm_in_us()

◆ alarm_pool_add_alarm_at()

◆ alarm_pool_add_alarm_at_force_in_context()

◆ alarm_pool_add_alarm_in_ms()

◆ alarm_pool_add_alarm_in_us()

◆ alarm_pool_cancel_alarm()

◆ alarm_pool_core_num()

◆ alarm_pool_create()

◆ alarm_pool_create_with_unused_hardware_alarm()

◆ alarm_pool_destroy()

◆ alarm_pool_get_default()

◆ alarm_pool_hardware_alarm_num()

◆ cancel_alarm()