zeitstempel 0.2.0

A timestamp you can serialize, and it might include suspend time.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159

//! zeitstempel is German for "timestamp".
//!
//! ---
//!
//! Time's hard. Correct time is near impossible.
//!
//! This crate has one purpose: give me a timestamp as an integer, coming from a monotonic clock
//! source, guaranteed with or without time across suspend/hibernation of the host machine,
//! and let me compare it to other timestamps.
//!
//! It becomes the developer's responsibility to only compare timestamps obtained from this clock source.
//! Timestamps are not comparable across operating system reboots.
//!
//! # Why not `std::time::Instant`?
//!
//! [`std::time::Instant`] fulfills some of our requirements:
//!
//! * It's monotonic, guaranteed ([sort of][rustsource]).
//! * It can be compared to other timespans.
//!
//! However:
//!
//! * It can't be serialized.
//! * It's not guaranteed that the clock source it uses contains (or exclude) suspend/hibernation time across all operating systems.
//!
//! [rustsource]: https://doc.rust-lang.org/1.47.0/src/std/time.rs.html#213-237
//!
//! # Example with suspend time
//!
//! ```
//! # use std::{thread, time::Duration};
//! let start = zeitstempel::now();
//! thread::sleep(Duration::from_millis(2));
//!
//! let diff = Duration::from_nanos(zeitstempel::now() - start);
//! assert!(diff >= Duration::from_millis(2));
//! ```
//!
//! # Example with only awake time
//!
//! ```
//! # use std::{thread, time::Duration};
//! let start = zeitstempel::now_awake();
//! thread::sleep(Duration::from_millis(2));
//!
//! let diff = Duration::from_nanos(zeitstempel::now_awake() - start);
//! assert!(diff >= Duration::from_millis(2));
//! ```
//!
//! # Supported operating systems
//!
//! We support the following operating systems:
//!
//! * Windows\*
//! * macOS
//! * Linux
//! * Android
//! * iOS
//!
//! For other operating systems there's a fallback to `std::time::Instant`,
//! compared against a process-global fixed reference point.
//! We don't guarantee that measured time includes time the system spends in sleep or hibernation.
//!
//! \* To use native Windows 10 functionality enable the `win10plus` feature. Otherwise it will use the fallback.

#![deny(missing_docs)]
#![deny(rustdoc::broken_intra_doc_links)]

cfg_if::cfg_if! {
    if #[cfg(any(target_os = "macos", target_os = "ios"))] {
        mod mac;
        use mac as sys;
    } else if #[cfg(any(target_os = "linux", target_os = "android"))] {
        mod linux;
        use linux as sys;
    } else if #[cfg(all(windows, feature = "win10plus"))] {
        mod win10;
        use win10 as sys;
    } else if #[cfg(windows)] {
        mod win;
        use win as sys;
    } else {
        mod fallback;
        use fallback as sys;
    }
}

/// Returns a timestamp corresponding to "now", including suspend time.
///
/// It can be compared to other timestamps gathered from this API, as long as the host was not
/// rebooted inbetween.
///
///
/// ## Note
///
/// * The difference between two timestamps will include time the system was in sleep or
///   hibernation.
/// * The difference between two timestamps gathered from this is in nanoseconds.
/// * The clocks on some operating systems, e.g. on Windows, are not nanosecond-precise.
///   The value will still use nanosecond resolution.
pub fn now() -> u64 {
    sys::now_including_suspend()
}

/// Returns a timestamp corresponding to "now", excluding suspend time.
///
/// It can be compared to other timestamps gathered from this API, as long as the host was not
/// rebooted inbetween.
///
///
/// ## Note
///
/// * The difference between two timestamps will NOT include time the system was in sleep or
///   hibernation.
/// * The difference between two timestamps gathered from this is in nanoseconds.
/// * The clocks on some operating systems, e.g. on Windows, are not nanosecond-precise.
///   The value will still use nanosecond resolution.
pub fn now_awake() -> u64 {
    sys::now_awake()
}

#[cfg(test)]
mod test {
    use super::*;
    use std::thread;
    use std::time::Duration;

    #[test]
    fn order() {
        let ts1 = now();
        thread::sleep(Duration::from_millis(2));
        let ts2 = now();

        assert!(ts1 < ts2);
    }

    #[test]
    fn awake_time_atleast_total_time() {
        let ts1 = now();
        let a_ts1 = now_awake();
        thread::sleep(Duration::from_millis(2));
        let ts2 = now();
        let a_ts2 = now_awake();

        assert!(ts1 < ts2);
        assert!(a_ts1 < a_ts2);
        let total_diff = Duration::from_nanos(ts2 - ts1);
        let awake_diff = Duration::from_nanos(a_ts2 - a_ts1);
        // `now_awake` gives us nanosecond resolution. That might be _too_ precise,
        // such that `awake` might be actually longer than `total` due to the calls taking just a
        // tiny bit longer.
        assert!(
            total_diff.as_millis() <= awake_diff.as_millis(),
            "total: {:?}, awake: {:?}",
            total_diff,
            awake_diff
        );
    }
}