v2.0.0
Macros | Typedefs | Functions
alarm
High Level APIs » pico_time

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 timer_alarm is claimed for the pool) More...
#define | PICO_TIME_DEFAULT_ALARM_POOL_HARDWARE_ALARM_NUM 3
| Selects which timer_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...
static alarm_pool_t * | alarm_pool_create (uint timer_alarm_num, uint max_timers)
| Create an alarm pool. More...
static alarm_pool_t * | alarm_pool_create_with_unused_hardware_alarm (uint max_timers)
| Create an alarm pool, claiming an used timer_alarm to back it. More...
uint | alarm_pool_timer_alarm_num (alarm_pool_t *pool)
| Return the timer 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 timer_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...
int64_t | alarm_pool_remaining_alarm_time_us (alarm_pool_t *pool, alarm_id_t alarm_id)
| Return the time remaining before the next trigger of an alarm. More...
int32_t | alarm_pool_remaining_alarm_time_ms (alarm_pool_t *pool, alarm_id_t alarm_id)
| Return the time remaining before the next trigger of an alarm. 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...
int64_t | remaining_alarm_time_us (alarm_id_t alarm_id)
| Return the time remaining before the next trigger of an alarm. More...
int32_t | remaining_alarm_time_ms (alarm_id_t alarm_id)
| Return the time remaining before the next trigger of an alarm. 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 timer_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 timer_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 timer_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 timer_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 <0 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.

See also
  pico_error_codes

## 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 fire_if_past was false
  <0 if there were no alarm slots available, or other error occurred

## ◆ 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 fire_if_past was false
  <0 if there were no alarm slots available, or other error occurred

## ◆ 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 fire_if_past was false
  <0 if there were no alarm slots available, or other error occurred

## ◆ 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 timer_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 fire_if_past was false
  <0 if there were no alarm slots available, or other error occurred

## ◆ 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 timer_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
  <0 if there were no alarm slots available, or other error occurred

## ◆ 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 timer_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 fire_if_past was false
  <0 if there were no alarm slots available, or other error occurred

## ◆ 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 timer_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 fire_if_past was false
  <0 if there were no alarm slots available, or other error occurred

## ◆ 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()

static alarm_pool_t * alarm_pool_create | ( | uint | timer_alarm_num,
|  | uint | max_timers
| ) |  |
| inlinestatic

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 timer_alarm is already claimed.

Parameters

  timer_alarm_num | the timer_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()

static alarm_pool_t * alarm_pool_create_with_unused_hardware_alarm | ( | uint | max_timers | ) |
| inlinestatic

Create an alarm pool, claiming an used timer_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 timer_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_remaining_alarm_time_ms()

int32_t alarm_pool_remaining_alarm_time_ms | ( | alarm_pool_t * | pool,
|  | alarm_id_t | alarm_id
| ) |  |

Return the time remaining before the next trigger of an alarm.

Parameters

  pool | the alarm_pool containing the alarm
  alarm_id | the alarm

Returns
  >=0 the number of microseconds before the next trigger (INT32_MAX if the number of ms is higher than can be represented0
  <0 if either the given alarm is not in progress or it has passed

## ◆ alarm_pool_remaining_alarm_time_us()

int64_t alarm_pool_remaining_alarm_time_us | ( | alarm_pool_t * | pool,
|  | alarm_id_t | alarm_id
| ) |  |

Return the time remaining before the next trigger of an alarm.

Parameters

  pool | the alarm_pool containing the alarm
  alarm_id | the alarm

Returns
  >=0 the number of microseconds before the next trigger
  <0 if either the given alarm is not in progress or it has passed

## ◆ alarm_pool_timer_alarm_num()

uint alarm_pool_timer_alarm_num | ( | alarm_pool_t * | pool | ) |

Return the timer alarm used by an alarm pool.

Parameters

  pool | the pool

Returns
  the timer_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

## ◆ remaining_alarm_time_ms()

int32_t remaining_alarm_time_ms | ( | alarm_id_t | alarm_id | ) |

Return the time remaining before the next trigger of an alarm.

Parameters

  alarm_id | the alarm

Returns
  >=0 the number of microseconds before the next trigger (INT32_MAX if the number of ms is higher than can be represented0
  <0 if either the given alarm is not in progress or it has passed

## ◆ remaining_alarm_time_us()

int64_t remaining_alarm_time_us | ( | alarm_id_t | alarm_id | ) |

Return the time remaining before the next trigger of an alarm.

Parameters

  pool | the alarm_pool containing the alarm
  alarm_id | the alarm

Returns
  >=0 the number of microseconds before the next trigger
  <0 if either the given alarm is not in progress or it has passed