t2t_clock/lib.rs
1//! Clocks that read the time: the OS's wall and monotonic clocks, the CPU's counter, and
2//! clocks set by hand.
3//!
4//! Each clock gives its reading through one verb, [`Clock::now`], and the reading's type says
5//! which timeline it came from: subtracting an [`Uptime`] from a [`Timestamp`] does not compile.
6//!
7//! | Clock | Reads | Steps? | For |
8//! | ---------------------- | -------------- | ------- | ---------------------------------------- |
9//! | `SystemClock` | `Timestamp` | yes | a stamp other machines compare |
10//! | `CoarseSystemClock` | `Timestamp` | yes | whether a heartbeat or expiry is due |
11//! | `TaiClock` (Linux) | `TaiTimestamp` | never | a stamp on the timescale PTP keeps |
12//! | `MonotonicClock` | `Uptime` | never | a deadline, a timeout |
13//! | `CoarseMonotonicClock` | `Uptime` | never | a far deadline, polled often |
14//! | `RawMonotonicClock` | `RawUptime` | never | a span no time service's slewing touches |
15//! | `BootClock` | `BootUptime` | never | a timeout that runs through a suspension |
16//! | `ProcessCpuClock` | `Timedelta` | never | the CPU time the process has used |
17//! | `ThreadCpuClock` | `Timedelta` | never | the CPU time the calling thread has used |
18//! | [`Counter`] | [`Tickstamp`] | never | a stamp or a span in one instruction |
19//! | [`ManualClock`] | any point | by hand | a test or a replay on one thread |
20//! | [`AtomicManualClock`] | any point | by hand | a test or a replay shared across threads |
21//!
22//! The OS clocks need the `std` feature, on 64-bit Linux or macOS, and read the clock the
23//! table's name says on each; each clock's docs give the ids. [`Counter`] reads the virtual counter
24//! on `aarch64` and the time-stamp counter on `x86_64`, with or without `std`.
25//!
26//! # Examples
27//! ```
28//! use t2t_clock::{Clock, ManualClock};
29//! use t2t_core::{Timedelta, Timestamp};
30//!
31//! /// Whether the quote stamped at `stamp` is older than a second.
32//! fn is_stale<C: Clock<Reading = Timestamp>>(clock: &C, stamp: Timestamp) -> bool {
33//! clock.now() - stamp > Timedelta::SECOND
34//! }
35//!
36//! let clock = ManualClock::new(Timestamp::from_secs(10));
37//! assert!(!is_stale(&clock, Timestamp::from_secs(10)), "fresh at capture");
38//! clock.advance(Timedelta::from_secs(2));
39//! assert!(is_stale(&clock, Timestamp::from_secs(10)), "stale two seconds on");
40//! ```
41//!
42//! # Crate Features
43//!
44//! None is on by default, and nothing reaches the operating system unless `std` is named; what
45//! `std` adds is on 64-bit Linux and macOS.
46//!
47//! | Feature | Adds |
48//! | ------- | ------------------------------------------------------ |
49//! | `std` | the OS clocks, and an `x86_64` counter's measured rate |
50//!
51//! [`Timestamp`]: t2t_core::Timestamp
52//! [`Uptime`]: t2t_core::Uptime
53//! [`Tickstamp`]: t2t_core::Tickstamp
54
55#![no_std]
56#![cfg_attr(docsrs, feature(doc_cfg))]
57
58#[cfg(test)]
59extern crate alloc;
60#[cfg(test)]
61extern crate std;
62
63mod clock;
64#[cfg(counter)]
65mod counter;
66#[cfg(counter)]
67mod errors;
68mod manual;
69#[cfg(os_clocks)]
70mod os;
71#[cfg(atomic_clock)]
72mod sync;
73
74pub use crate::clock::Clock;
75#[cfg(counter)]
76pub use crate::counter::Counter;
77#[cfg(counter)]
78pub use crate::errors::CounterError;
79#[cfg(atomic_clock)]
80pub use crate::manual::AtomicManualClock;
81pub use crate::manual::ManualClock;
82#[cfg(tai_clock)]
83pub use crate::os::TaiClock;
84#[cfg(os_clocks)]
85pub use crate::os::{
86 BootClock, CoarseMonotonicClock, CoarseSystemClock, MonotonicClock, ProcessCpuClock,
87 RawMonotonicClock, SystemClock, ThreadCpuClock,
88};