max/embassy
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add readme for embassy-time

Browse Source
This commit is contained in:
Ulf Lilleengen 2022-08-23 13:57:45 +02:00
parent 7b3ae0446c
commit 189d4137cc
2 changed files with 44 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
embassy-time/README.md Normal file
View File

@ -0,0 +1,43 @@
# 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.

43
embassy-time/src/lib.rs
View File

@ -1,50 +1,9 @@
#![cfg_attr(not(any(feature = "std", feature = "wasm")), no_std)] #![cfg_attr(not(any(feature = "std", feature = "wasm")), no_std)]
#![cfg_attr(feature = "nightly", feature(generic_associated_types, type_alias_impl_trait))] #![cfg_attr(feature = "nightly", feature(generic_associated_types, type_alias_impl_trait))]
#![doc = include_str!("../README.md")]
#![allow(clippy::new_without_default)] #![allow(clippy::new_without_default)]
#![warn(missing_docs)] #![warn(missing_docs)]
//! 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.
// This mod MUST go first, so that the others see its macros. // This mod MUST go first, so that the others see its macros.
pub(crate) mod fmt; pub(crate) mod fmt;