openthread/ot/types/
timestamp.rs

1// Copyright 2022 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use crate::ot::BadSystemTime;
6use crate::prelude_internal::*;
7use std::fmt::{Debug, Display, Formatter};
8use std::ops::{Add, AddAssign};
9use std::time::{Duration, SystemTime};
10
11/// Type representing a Thread timestamp.
12#[derive(Default, Clone, Copy, Ord, PartialOrd, PartialEq, Eq)]
13#[repr(transparent)]
14pub struct Timestamp(pub u64);
15
16const MICROSECONDS_PER_SECOND: u64 = 1000000;
17const FRACTIONS_PER_SECOND: u64 = 32768;
18const AUTHORITATIVE_BIT_MASK: u64 = 1;
19const SUBSEC_MASK: u64 = 0xFFFE;
20const MAX_SECONDS: u64 = 0xFFFFFFFFFFFF;
21
22/// Takes a value from 0 to 1000000 and scales it to a value from 0 to 32768, rounded to the
23/// nearest value.
24const fn micros_to_fractional_second(mut micros: u64) -> u64 {
25    micros += MICROSECONDS_PER_SECOND / (FRACTIONS_PER_SECOND * 2);
26    (micros * FRACTIONS_PER_SECOND / MICROSECONDS_PER_SECOND) & 0xffff
27}
28
29/// Takes a value from 0 to 32768 and scales it to a value from 0 to 1000000.
30const fn fractional_second_to_micros(fraction_of_second: u64) -> u64 {
31    fraction_of_second * MICROSECONDS_PER_SECOND / FRACTIONS_PER_SECOND
32}
33
34impl Timestamp {
35    /// Timestamp for the start of time.
36    pub const EPOCH: Timestamp = Timestamp(0);
37
38    /// Returns the timestamp representing this instant.
39    pub fn now() -> Timestamp {
40        Self::try_from_system_time(SystemTime::now()).unwrap()
41    }
42
43    /// Returns true if this timestamp is authoritative, false otherwise.
44    pub const fn is_authoritative(&self) -> bool {
45        (self.0 & AUTHORITATIVE_BIT_MASK) == AUTHORITATIVE_BIT_MASK
46    }
47
48    /// Sets or clears the authoritative bit.
49    pub fn set_authoritative(&mut self, authoritative: bool) {
50        self.0 &= !AUTHORITATIVE_BIT_MASK;
51        if authoritative {
52            self.0 |= AUTHORITATIVE_BIT_MASK;
53        }
54    }
55
56    /// Returns this timestamp with the authoritative bit changed as indicated.
57    pub fn with_authoritative(mut self, authoritative: bool) -> Self {
58        self.set_authoritative(authoritative);
59        self
60    }
61
62    /// Tries to convert a [`std::time::SystemTime`] to a [`Timestamp`].
63    ///
64    /// Will fail if the given SystemTime cannot be represented as a Timestamp. This
65    /// can happen if the `SystemTime` represents a time that is before the epoch or is too
66    /// far in the future.
67    pub fn try_from_system_time(system_time: SystemTime) -> Result<Timestamp, BadSystemTime> {
68        system_time
69            .duration_since(SystemTime::UNIX_EPOCH)
70            .map_err(|_| BadSystemTime)
71            .and_then(Timestamp::try_from_duration_since_epoch)
72    }
73
74    /// Tries to convert a [`std::time::Duration`] to a [`Timestamp`].
75    ///
76    /// Will fail if duration is negative or too large.
77    pub fn try_from_duration_since_epoch(duration: Duration) -> Result<Timestamp, BadSystemTime> {
78        let seconds = duration.as_secs();
79        if seconds > MAX_SECONDS {
80            return Err(BadSystemTime);
81        }
82
83        let seconds_shift_16 = seconds << 16;
84        let micros: u64 = (duration - Duration::from_secs(seconds)).as_micros().try_into().unwrap();
85        let fraction_of_second = micros_to_fractional_second(micros);
86
87        Ok(Timestamp(seconds_shift_16 + (fraction_of_second << 1)))
88    }
89
90    /// Returns the timestamp as the number of seconds since the epoch.
91    pub const fn as_secs(&self) -> u64 {
92        self.0 >> 16
93    }
94
95    /// Returns the subsecond fraction of the timestamp, measured in 1/32768ths of a second.
96    pub const fn subsec_fraction(&self) -> u64 {
97        (self.0 & SUBSEC_MASK) >> 1
98    }
99
100    /// Returns the timestamp as the number of microseconds since the epoch.
101    pub const fn as_micros(&self) -> u64 {
102        self.as_secs() * MICROSECONDS_PER_SECOND
103            + fractional_second_to_micros(self.subsec_fraction())
104    }
105
106    /// Converts this Timestamp into a [`std::time::SystemTime`];
107    pub fn to_system_time(&self) -> SystemTime {
108        SystemTime::UNIX_EPOCH + Duration::from_micros(self.as_micros())
109    }
110
111    /// Returns this timestamp as a duration since the UNIX epoch (`1970-01-01T00:00:00UTC`)
112    pub fn to_duration_since_epoch(&self) -> Duration {
113        self.to_system_time().duration_since(SystemTime::UNIX_EPOCH).unwrap()
114    }
115
116    /// Returns the timestamp as big-endian bytes.
117    pub const fn to_be_bytes(&self) -> [u8; 8] {
118        self.0.to_be_bytes()
119    }
120
121    /// Returns the timestamp as little-endian bytes.
122    pub const fn to_le_bytes(&self) -> [u8; 8] {
123        self.0.to_le_bytes()
124    }
125
126    /// Returns the timestamp as an instance of `chrono::naive::NaiveDateTime`.
127    pub fn to_naive_date_time(&self) -> chrono::naive::NaiveDateTime {
128        chrono::naive::NaiveDateTime::from_timestamp_micros(self.as_micros().try_into().unwrap())
129            .expect("time to be within range")
130    }
131}
132
133impl TryFrom<SystemTime> for Timestamp {
134    type Error = BadSystemTime;
135
136    fn try_from(value: SystemTime) -> std::result::Result<Self, Self::Error> {
137        Timestamp::try_from_system_time(value)
138    }
139}
140
141impl From<Timestamp> for SystemTime {
142    fn from(ts: Timestamp) -> Self {
143        ts.to_system_time()
144    }
145}
146
147impl From<Timestamp> for u64 {
148    fn from(ts: Timestamp) -> Self {
149        ts.0
150    }
151}
152
153impl From<u64> for Timestamp {
154    fn from(ts: u64) -> Self {
155        Timestamp(ts)
156    }
157}
158
159impl From<openthread_sys::otTimestamp> for Timestamp {
160    fn from(ts: otTimestamp) -> Self {
161        let mut ret = Timestamp::from((ts.mSeconds << 16) | ((ts.mTicks as u64) << 1));
162        ret.set_authoritative(ts.mAuthoritative);
163        ret
164    }
165}
166
167impl From<Timestamp> for openthread_sys::otTimestamp {
168    fn from(ts: Timestamp) -> Self {
169        openthread_sys::otTimestamp {
170            mSeconds: u64::from(ts) >> 16,
171            mTicks: ((u64::from(ts) & SUBSEC_MASK) >> 1) as u16,
172            mAuthoritative: ts.is_authoritative(),
173        }
174    }
175}
176
177impl Debug for Timestamp {
178    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
179        let authoritative = if self.is_authoritative() { "authoritative" } else { "" };
180        write!(f, "{:12X} ({:?}{})", self.0, self.to_naive_date_time(), authoritative)
181    }
182}
183
184impl Display for Timestamp {
185    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
186        let authoritative = if self.is_authoritative() { " authoritative" } else { "" };
187        write!(f, "{}{}", self.to_naive_date_time(), authoritative)
188    }
189}
190
191impl AddAssign<Duration> for Timestamp {
192    fn add_assign(&mut self, duration: Duration) {
193        self.0 += Self::try_from_duration_since_epoch(duration).unwrap().0;
194    }
195}
196
197impl Add<Duration> for Timestamp {
198    type Output = Timestamp;
199
200    fn add(mut self, rhs: Duration) -> Self::Output {
201        self += rhs;
202        self
203    }
204}
205
206#[cfg(test)]
207mod test {
208    use super::*;
209    const NANOSECONDS_PER_SECOND: u64 = 1000000000;
210
211    #[test]
212    fn test_timestamp() {
213        assert_eq!(Timestamp::EPOCH, SystemTime::UNIX_EPOCH.try_into().unwrap());
214        assert_eq!(
215            Timestamp(0x10000).to_system_time(),
216            SystemTime::UNIX_EPOCH + Duration::from_secs(1)
217        );
218        assert_eq!(
219            Timestamp(0x10000),
220            (SystemTime::UNIX_EPOCH + Duration::from_secs(1)).try_into().unwrap()
221        );
222        assert_eq!(
223            Timestamp(0x8000),
224            (SystemTime::UNIX_EPOCH + Duration::from_millis(500)).try_into().unwrap()
225        );
226        assert_eq!(
227            Timestamp(0x8000).to_system_time(),
228            (SystemTime::UNIX_EPOCH + Duration::from_millis(500))
229        );
230        assert_eq!(
231            Timestamp(0xFFFE),
232            (SystemTime::UNIX_EPOCH
233                + Duration::from_nanos(NANOSECONDS_PER_SECOND * 0xFFFE / 0x10000))
234            .try_into()
235            .unwrap()
236        );
237        assert_eq!(
238            Timestamp(0x10000),
239            (SystemTime::UNIX_EPOCH + Duration::from_nanos(999999999)).try_into().unwrap()
240        );
241        assert_eq!(
242            Timestamp(0x20000),
243            (SystemTime::UNIX_EPOCH + Duration::from_nanos(1999999999)).try_into().unwrap()
244        );
245
246        assert_eq!(Timestamp(1).to_be_bytes(), [0, 0, 0, 0, 0, 0, 0, 1]);
247        assert_eq!(Timestamp(1).to_le_bytes(), [1, 0, 0, 0, 0, 0, 0, 0]);
248
249        assert_eq!(
250            format!("{:?}", Timestamp::from(0x62CC8DE70000)),
251            "62CC8DE70000 (2022-07-11T20:53:59)".to_string()
252        );
253
254        assert_eq!(Timestamp::from(0x62CC8DE70000).to_string(), "2022-07-11 20:53:59".to_string());
255
256        assert_eq!(
257            Timestamp::from(0x62CC8DE70001).to_string(),
258            "2022-07-11 20:53:59 authoritative".to_string()
259        );
260
261        assert!(!Timestamp::from(0u64).is_authoritative());
262        assert!(Timestamp::from(1u64).is_authoritative());
263
264        assert_eq!(Timestamp::from(0x62CC8DE70000).to_string(), "2022-07-11 20:53:59".to_string());
265
266        assert_eq!(
267            Timestamp::from(0x62CC8DE70001).to_string(),
268            "2022-07-11 20:53:59 authoritative".to_string()
269        );
270
271        assert!(!Timestamp::from(0u64).is_authoritative());
272        assert!(Timestamp::from(1u64).is_authoritative());
273
274        assert!(Timestamp(0).with_authoritative(true).is_authoritative());
275        assert!(!Timestamp(1).with_authoritative(false).is_authoritative());
276
277        assert!(Timestamp::try_from_system_time(SystemTime::UNIX_EPOCH - Duration::from_secs(1))
278            .is_err());
279        assert_eq!(Timestamp::EPOCH + Duration::from_secs(1), Timestamp(0x10000));
280        println!("now={:?}", Timestamp::now());
281    }
282}
openthread/ot/types/timestamp.rs

openthread/ot/types/
timestamp.rs
