Crate embassy_time

source ·
Expand description

embassy-time

Timekeeping, delays and timeouts.

Timekeeping is done with elapsed time since system boot. Time is represented in ticks, where the tick rate is defined by the current driver, usually to match the tick rate of the hardware.

Tick counts are 64 bits. At the highest supported tick rate of 1Mhz this supports representing time spans of up to ~584558 years, which is big enough for all practical purposes and allows not having to worry about overflows.

Instant represents a given instant of time (relative to system boot), and Duration represents the duration of a span of time. They implement the math operations you’d expect, like addition and substraction.

Delays and timeouts

Timer allows performing async delays. Ticker allows periodic delays without drifting over time.

An implementation of the embedded-hal delay traits is provided by Delay, for compatibility with libraries from the ecosystem.

Wall-clock time

The time module deals exclusively with a monotonically increasing tick count. Therefore it has no direct support for wall-clock time (“real life” datetimes like 2021-08-24 13:33:21).

If persistence across reboots is not needed, support can be built on top of embassy_time by storing the offset between “seconds elapsed since boot” and “seconds since unix epoch”.

Time driver

The time module is backed by a global “time driver” specified at build time. Only one driver can be active in a program.

All methods and structs transparently call into the active driver. This makes it possible for libraries to use embassy_time in a driver-agnostic way without requiring generic parameters.

For more details, check the driver module.

Modules

  • driver
    Time driver interface
  • queue
    Timer queue implementation

Macros

Structs

  • Delay
    Type implementing async delays and blocking embedded-hal delays.
  • Duration
    Represents the difference between two Instants
  • Instant
    An Instant in time, based on the MCU’s clock ticks since startup.
  • Ticker
    Asynchronous stream that yields every Duration, indefinitely.
  • TimeoutError
    Error returned by with_timeout on timeout.
  • Timer
    A future that completes at a specified Instant.

Constants

  • TICK_HZ
    Ticks per second of the global timebase.

Functions