zeitstempel/
lib.rs

1//! zeitstempel is German for "timestamp".
2//!
3//! ---
4//!
5//! Time's hard. Correct time is near impossible.
6//!
7//! This crate has one purpose: give me a timestamp as an integer, coming from a monotonic clock
8//! source, include time across suspend/hibernation of the host machine and let me compare it to
9//! other timestamps.
10//!
11//! It becomes the developer's responsibility to only compare timestamps obtained from this clock source.
12//! Timestamps are not comparable across operating system reboots.
13//!
14//! # Why not `std::time::Instant`?
15//!
16//! [`std::time::Instant`] fulfills some of our requirements:
17//!
18//! * It's monotonic, guaranteed ([sort of][rustsource]).
19//! * It can be compared to other timespans.
20//!
21//! However:
22//!
23//! * It can't be serialized.
24//! * It's not guaranteed that the clock source it uses contains suspend/hibernation time across all operating systems.
25//!
26//! [rustsource]: https://doc.rust-lang.org/1.47.0/src/std/time.rs.html#213-237
27//!
28//! # Example
29//!
30//! ```
31//! # use std::{thread, time::Duration};
32//! let start = zeitstempel::now();
33//! thread::sleep(Duration::from_millis(2));
34//!
35//! let diff = Duration::from_nanos(zeitstempel::now() - start);
36//! assert!(diff >= Duration::from_millis(2));
37//! ```
38//!
39//! # Supported operating systems
40//!
41//! We support the following operating systems:
42//!
43//! * Windows\*
44//! * macOS
45//! * Linux
46//! * Android
47//! * iOS
48//!
49//! For other operating systems there's a fallback to `std::time::Instant`,
50//! compared against a process-global fixed reference point.
51//! We don't guarantee that measured time includes time the system spends in sleep or hibernation.
52//!
53//! \* To use native Windows 10 functionality enable the `win10plus` feature. Otherwise it will use the fallback.
54
55#![deny(missing_docs)]
56#![deny(rustdoc::broken_intra_doc_links)]
57
58cfg_if::cfg_if! {
59    if #[cfg(any(target_os = "macos", target_os = "ios"))] {
60        mod mac;
61        use mac as sys;
62    } else if #[cfg(any(target_os = "linux", target_os = "android"))] {
63        mod linux;
64        use linux as sys;
65    } else if #[cfg(all(windows, feature = "win10plus"))] {
66        mod win10;
67        use win10 as sys;
68    } else if #[cfg(windows)] {
69        mod win;
70        use win as sys;
71    } else {
72        mod fallback;
73        use fallback as sys;
74    }
75}
76
77/// Returns a timestamp corresponding to "now".
78///
79/// It can be compared to other timestamps gathered from this API, as long as the host was not
80/// rebooted inbetween.
81///
82///
83/// ## Note
84///
85/// * The difference between two timestamps will include time the system was in sleep or
86///   hibernation.
87/// * The difference between two timestamps gathered from this is in nanoseconds.
88/// * The clocks on some operating systems, e.g. on Windows, are not nanosecond-precise.
89///   The value will still use nanosecond resolution.
90pub fn now() -> u64 {
91    sys::now_including_suspend()
92}
93
94#[cfg(test)]
95mod test {
96    use super::*;
97    use std::thread;
98    use std::time::Duration;
99
100    #[test]
101    fn order() {
102        let ts1 = now();
103        thread::sleep(Duration::from_millis(2));
104        let ts2 = now();
105
106        assert!(ts1 < ts2);
107    }
108}
zeitstempel/lib.rs

zeitstempel/
lib.rs
