v2.0.0
Typedefs | Functions | Variables
timestamp
High Level APIs » pico_time

Timestamp functions relating to points in time (including the current time). More...

## Typedefs
typedef uint64_t | absolute_time_t
| An opaque 64 bit timestamp in microseconds. More...

## Functions
static uint64_t | to_us_since_boot (absolute_time_t t)
| convert an absolute_time_t into a number of microseconds since boot. More...
static void | update_us_since_boot (absolute_time_t *t, uint64_t us_since_boot)
| update an absolute_time_t value to represent a given number of microseconds since boot More...
static absolute_time_t | from_us_since_boot (uint64_t us_since_boot)
| convert a number of microseconds since boot to an absolute_time_t More...
static absolute_time_t | get_absolute_time (void)
| Return a representation of the current time. More...
static uint32_t | to_ms_since_boot (absolute_time_t t)
| Convert a timestamp into a number of milliseconds since boot. More...
static absolute_time_t | delayed_by_us (const absolute_time_t t, uint64_t us)
| Return a timestamp value obtained by adding a number of microseconds to another timestamp. More...
static absolute_time_t | delayed_by_ms (const absolute_time_t t, uint32_t ms)
| Return a timestamp value obtained by adding a number of milliseconds to another timestamp. More...
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. More...
static absolute_time_t | make_timeout_time_ms (uint32_t ms)
| Convenience method to get the timestamp a number of milliseconds from the current time. More...
static int64_t | absolute_time_diff_us (absolute_time_t from, absolute_time_t to)
| Return the difference in microseconds between two timestamps. More...
static absolute_time_t | absolute_time_min (absolute_time_t a, absolute_time_t b)
| Return the earlier of two timestamps. More...
static bool | is_at_the_end_of_time (absolute_time_t t)
| Determine if the given timestamp is "at_the_end_of_time". More...
static bool | is_nil_time (absolute_time_t t)
| Determine if the given timestamp is nil. More...

## Variables
const absolute_time_t | at_the_end_of_time
| The timestamp representing the end of time; this is actually not the maximum possible timestamp, but is set to 0x7fffffff_ffffffff microseconds to avoid sign overflows with time arithmetic. This is almost 300,000 years, so should be sufficient.
const absolute_time_t | nil_time
| The timestamp representing a null timestamp.

## Detailed Description

Timestamp functions relating to points in time (including the current time).

These are functions for dealing with timestamps (i.e. instants in time) represented by the type absolute_time_t. This opaque type is provided to help prevent accidental mixing of timestamps and relative time values.

## Typedef Documentation

## ◆ absolute_time_t

absolute_time_t

An opaque 64 bit timestamp in microseconds.

The type is used instead of a raw uint64_t to prevent accidentally passing relative times or times in the wrong time units where an absolute time is required.

note: As of SDK 2.0.0 this type defaults to being a uin64_t (i.e. no protection); it is enabled by setting PICO_OPAQUE_ABSOLUTE_TIME_T to 1

See also
  to_us_since_boot()
  update_us_since_boot()

## Function Documentation

## ◆ absolute_time_diff_us()

static int64_t absolute_time_diff_us | ( | absolute_time_t | from,
|  | absolute_time_t | to
| ) |  |
| inlinestatic

Return the difference in microseconds between two timestamps.

Note
  be careful when diffing against large timestamps (e.g. at_the_end_of_time) as the signed integer may overflow.

Parameters

  from | the first timestamp
  to | the second timestamp

Returns
  the number of microseconds between the two timestamps (positive if `to` is after `from` except in case of overflow)

## ◆ absolute_time_min()

static absolute_time_t absolute_time_min | ( | absolute_time_t | a,
|  | absolute_time_t | b
| ) |  |
| inlinestatic

Return the earlier of two timestamps.

Parameters

  a | the first timestamp
  b | the second timestamp

Returns
  the earlier of the two timestamps

## ◆ delayed_by_ms()

static absolute_time_t delayed_by_ms | ( | const absolute_time_t | t,
|  | uint32_t | ms
| ) |  |
| inlinestatic

Return a timestamp value obtained by adding a number of milliseconds to another timestamp.

Parameters

  t | the base timestamp
  ms | the number of milliseconds to add

Returns
  the timestamp representing the resulting time

## ◆ delayed_by_us()

static absolute_time_t delayed_by_us | ( | const absolute_time_t | t,
|  | uint64_t | us
| ) |  |
| inlinestatic

Return a timestamp value obtained by adding a number of microseconds to another timestamp.

Parameters

  t | the base timestamp
  us | the number of microseconds to add

Returns
  the timestamp representing the resulting time

## ◆ from_us_since_boot()

static absolute_time_t from_us_since_boot | ( | uint64_t | us_since_boot | ) |
| inlinestatic

convert a number of microseconds since boot to an absolute_time_t

fn from_us_since_boot

Parameters

  us_since_boot | number of microseconds since boot

Returns
  an absolute time equivalent to us_since_boot

## ◆ get_absolute_time()

static absolute_time_t get_absolute_time | ( | void |  | ) |
| inlinestatic

Return a representation of the current time.

Returns an opaque high fidelity representation of the current time sampled during the call.

Returns
  the absolute time (now) of the hardware timer

See also
  absolute_time_t
  sleep_until()
  time_us_64()

## ◆ is_at_the_end_of_time()

static bool is_at_the_end_of_time | ( | absolute_time_t | t | ) |
| inlinestatic

Determine if the given timestamp is "at_the_end_of_time".

Parameters

  t | the timestamp

Returns
  true if the timestamp is at_the_end_of_time

See also
  at_the_end_of_time

## ◆ is_nil_time()

static bool is_nil_time | ( | absolute_time_t | t | ) |
| inlinestatic

Determine if the given timestamp is nil.

Parameters

  t | the timestamp

Returns
  true if the timestamp is nil

See also
  nil_time

## ◆ make_timeout_time_ms()

static absolute_time_t make_timeout_time_ms | ( | uint32_t | ms | ) |
| inlinestatic

Convenience method to get the timestamp a number of milliseconds from the current time.

Parameters

  ms | the number of milliseconds to add to the current timestamp

Returns
  the future timestamp

## ◆ make_timeout_time_us()

static absolute_time_t make_timeout_time_us | ( | uint64_t | us | ) |
| inlinestatic

Convenience method to get the timestamp a number of microseconds from the current time.

Parameters

  us | the number of microseconds to add to the current timestamp

Returns
  the future timestamp

## ◆ to_ms_since_boot()

static uint32_t to_ms_since_boot | ( | absolute_time_t | t | ) |
| inlinestatic

Convert a timestamp into a number of milliseconds since boot.

fn to_ms_since_boot

Parameters

  t | an absolute_time_t value to convert

Returns
  the number of milliseconds since boot represented by t

See also
  to_us_since_boot()

## ◆ to_us_since_boot()

static uint64_t to_us_since_boot | ( | absolute_time_t | t | ) |
| inlinestatic

convert an absolute_time_t into a number of microseconds since boot.

fn to_us_since_boot

Parameters

  t | the absolute time to convert

Returns
  a number of microseconds since boot, equivalent to t

## ◆ update_us_since_boot()

static void update_us_since_boot | ( | absolute_time_t * | t,
|  | uint64_t | us_since_boot
| ) |  |
| inlinestatic

update an absolute_time_t value to represent a given number of microseconds since boot

fn update_us_since_boot

Parameters

  t | the absolute time value to update
  us_since_boot | the number of microseconds since boot to represent. Note this should be representable as a signed 64 bit integer