v2.0.0
Functions
sleep
High Level APIs » pico_time

Sleep functions for delaying execution in a lower power state. More...

## Functions
void | sleep_until (absolute_time_t target)
| Wait until after the given timestamp to return. More...
void | sleep_us (uint64_t us)
| Wait for the given number of microseconds before returning. More...
void | sleep_ms (uint32_t ms)
| Wait for the given number of milliseconds before returning. More...
bool | best_effort_wfe_or_timeout (absolute_time_t timeout_timestamp)
| Helper method for blocking on a timeout. More...

## Detailed Description

Sleep functions for delaying execution in a lower power state.

These functions allow the calling core to sleep. This is a lower powered sleep; waking and re-checking time on every processor event (WFE)

Note
  These functions should not be called from an IRQ handler.
  Lower powered sleep requires use of the default alarm pool which may be disabled by the PICO_TIME_DEFAULT_ALARM_POOL_DISABLED #define or currently full in which case these functions become busy waits instead.
  Whilst sleep_ functions are preferable to busy_wait functions from a power perspective, the busy_wait equivalent function may return slightly sooner after the target is reached.

See also
  busy_wait_until()
  busy_wait_us()
  busy_wait_us_32()

## Function Documentation

## ◆ best_effort_wfe_or_timeout()

bool best_effort_wfe_or_timeout | ( | absolute_time_t | timeout_timestamp | ) |

Helper method for blocking on a timeout.

This method will return in response to an event (as per __wfe) or when the target time is reached, or at any point before.

This method can be used to implement a lower power polling loop waiting on some condition signalled by an event (__sev()).

This is called best_effort because under certain circumstances (notably the default timer pool being disabled or full) the best effort is simply to return immediately without a __wfe, thus turning the calling code into a busy wait.

Example usage:

bool my_function_with_timeout_us(uint64_t timeout_us) {
absolute_time_t timeout_time = make_timeout_time_us(timeout_us);
do {
// each time round the loop, we check to see if the condition
// we are waiting on has happened
if (my_check_done()) {
// do something
return true;
}
// will try to sleep until timeout or the next processor event
} while (!best_effort_wfe_or_timeout(timeout_time));
return false; // timed out
}
best_effort_wfe_or_timeout
bool best_effort_wfe_or_timeout(absolute_time_t timeout_timestamp)
Helper method for blocking on a timeout.
Definition: time.c:435
make_timeout_time_us
static absolute_time_t make_timeout_time_us(uint64_t us)
Convenience method to get the timestamp a number of microseconds from the current time.
Definition: time.h:136
absolute_time_t
uint64_t absolute_time_t
An opaque 64 bit timestamp in microseconds.
Definition: types.h:43

Parameters

  timeout_timestamp | the timeout time

Returns
  true if the target time is reached, false otherwise

## ◆ sleep_ms()

void sleep_ms | ( | uint32_t | ms | ) |

Wait for the given number of milliseconds before returning.

Note
  This method attempts to perform a lower power sleep (using WFE) as much as possible.

Parameters

  ms | the number of milliseconds to sleep

## ◆ sleep_until()

void sleep_until | ( | absolute_time_t | target | ) |

Wait until after the given timestamp to return.

Note
  This method attempts to perform a lower power (WFE) sleep

Parameters

  target | the time after which to return

See also
  sleep_us()
  busy_wait_until()

## ◆ sleep_us()

void sleep_us | ( | uint64_t | us | ) |

Wait for the given number of microseconds before returning.

Note
  This method attempts to perform a lower power (WFE) sleep

Parameters

  us | the number of microseconds to sleep

See also
  busy_wait_us()