2021-08-24 22:46:07 +02:00
|
|
|
//! 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
|
2022-07-29 21:58:35 +02:00
|
|
|
//! `embassy_executor::time` by storing the offset between "seconds elapsed since boot"
|
2021-08-24 22:46:07 +02:00
|
|
|
//! 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
|
2022-07-29 21:58:35 +02:00
|
|
|
//! possible for libraries to use `embassy_executor::time` in a driver-agnostic way without
|
2021-08-24 22:46:07 +02:00
|
|
|
//! requiring generic parameters.
|
|
|
|
//!
|
|
|
|
//! For more details, check the [`driver`] module.
|
2021-08-03 22:08:13 +02:00
|
|
|
|
2021-08-26 00:20:52 +02:00
|
|
|
#![deny(missing_docs)]
|
|
|
|
|
2021-07-12 03:10:01 +02:00
|
|
|
mod delay;
|
2021-08-03 22:08:13 +02:00
|
|
|
pub mod driver;
|
2020-10-19 21:15:24 +02:00
|
|
|
mod duration;
|
|
|
|
mod instant;
|
2021-07-12 03:10:01 +02:00
|
|
|
mod timer;
|
2020-10-19 21:15:24 +02:00
|
|
|
|
2021-08-25 20:34:25 +02:00
|
|
|
#[cfg(feature = "std")]
|
|
|
|
mod driver_std;
|
|
|
|
|
2021-09-13 14:35:40 +02:00
|
|
|
#[cfg(feature = "wasm")]
|
|
|
|
mod driver_wasm;
|
|
|
|
|
2021-07-12 03:10:01 +02:00
|
|
|
pub use delay::{block_for, Delay};
|
2020-10-19 21:15:24 +02:00
|
|
|
pub use duration::Duration;
|
|
|
|
pub use instant::Instant;
|
2021-07-12 03:10:01 +02:00
|
|
|
pub use timer::{with_timeout, Ticker, TimeoutError, Timer};
|
2020-10-19 21:15:24 +02:00
|
|
|
|
2021-07-12 03:29:09 +02:00
|
|
|
#[cfg(feature = "time-tick-1000hz")]
|
2021-08-24 22:46:07 +02:00
|
|
|
const TPS: u64 = 1_000;
|
2021-06-28 18:01:40 -03:00
|
|
|
|
2021-07-12 03:29:09 +02:00
|
|
|
#[cfg(feature = "time-tick-32768hz")]
|
2021-08-24 22:46:07 +02:00
|
|
|
const TPS: u64 = 32_768;
|
2021-06-28 18:01:40 -03:00
|
|
|
|
2021-07-12 03:29:09 +02:00
|
|
|
#[cfg(feature = "time-tick-1mhz")]
|
2021-08-24 22:46:07 +02:00
|
|
|
const TPS: u64 = 1_000_000;
|
|
|
|
|
2022-06-08 14:54:18 +01:00
|
|
|
#[cfg(feature = "time-tick-16mhz")]
|
|
|
|
const TPS: u64 = 16_000_000;
|
|
|
|
|
2021-08-24 22:46:07 +02:00
|
|
|
/// Ticks per second of the global timebase.
|
|
|
|
///
|
|
|
|
/// This value is specified by the `time-tick-*` Cargo features, which
|
|
|
|
/// should be set by the time driver. Some drivers support a fixed tick rate, others
|
|
|
|
/// allow you to choose a tick rate with Cargo features of their own. You should not
|
|
|
|
/// set the `time-tick-*` features for embassy yourself as an end user.
|
|
|
|
pub const TICKS_PER_SECOND: u64 = TPS;
|
2022-02-12 03:19:46 +01:00
|
|
|
|
|
|
|
const fn gcd(a: u64, b: u64) -> u64 {
|
|
|
|
if b == 0 {
|
|
|
|
a
|
|
|
|
} else {
|
|
|
|
gcd(b, a % b)
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
pub(crate) const GCD_1K: u64 = gcd(TICKS_PER_SECOND, 1_000);
|
|
|
|
pub(crate) const GCD_1M: u64 = gcd(TICKS_PER_SECOND, 1_000_000);
|