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_talarm_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_talarm_pool_create (uint hardware_alarm_num, uint max_timers)
 Create an alarm pool. More...
 
uint alarm_pool_hardware_alarm_num (alarm_pool_t *pool)
 Return the hardware alarm used by an alarm pool. 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...
 
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
idthe alarm_id as returned when the alarm was added
user_datathe 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
timethe timestamp when (after which) the callback should fire
callbackthe callback function
user_datauser data to pass to the callback function
fire_if_pastif 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
msthe delay (from now) in milliseconds when (after which) the callback should fire
callbackthe callback function
user_datauser data to pass to the callback function
fire_if_pastif 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
usthe delay (from now) in microseconds when (after which) the callback should fire
callbackthe callback function
user_datauser data to pass to the callback function
fire_if_pastif 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
poolthe alarm pool to use for scheduling the callback (this determines which hardware alarm is used, and which core calls the callback)
timethe timestamp when (after which) the callback should fire
callbackthe callback function
user_datauser data to pass to the callback function
fire_if_pastif 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_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
poolthe alarm pool to use for scheduling the callback (this determines which hardware alarm is used, and which core calls the callback)
msthe delay (from now) in milliseconds when (after which) the callback should fire
callbackthe callback function
user_datauser data to pass to the callback function
fire_if_pastif 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
poolthe alarm pool to use for scheduling the callback (this determines which hardware alarm is used, and which core calls the callback)
usthe delay (from now) in microseconds when (after which) the callback should fire
callbackthe callback function
user_datauser data to pass to the callback function
fire_if_pastif 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
poolthe alarm_pool containing the alarm
alarm_idthe 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_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_numthe hardware alarm to use to back this pool
max_timersthe 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
poolthe pool
Returns
the hardware alarm used by 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
poolthe 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_idthe 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