embassy_time/
instant.rs

1use core::fmt;
2use core::ops::{Add, AddAssign, Sub, SubAssign};
3
4use super::{Duration, GCD_1K, GCD_1M, TICK_HZ};
5
6#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
7#[cfg_attr(feature = "defmt", derive(defmt::Format))]
8/// An Instant in time, based on the MCU's clock ticks since startup.
9pub struct Instant {
10    ticks: u64,
11}
12
13impl Instant {
14    /// The smallest (earliest) value that can be represented by the `Instant` type.
15    pub const MIN: Instant = Instant { ticks: u64::MIN };
16    /// The largest (latest) value that can be represented by the `Instant` type.
17    pub const MAX: Instant = Instant { ticks: u64::MAX };
18
19    /// Returns an Instant representing the current time.
20    pub fn now() -> Instant {
21        Instant {
22            ticks: embassy_time_driver::now(),
23        }
24    }
25
26    /// Create an Instant from a tick count since system boot.
27    pub const fn from_ticks(ticks: u64) -> Self {
28        Self { ticks }
29    }
30
31    /// Create an Instant from a microsecond count since system boot.
32    pub const fn from_micros(micros: u64) -> Self {
33        Self {
34            ticks: micros * (TICK_HZ / GCD_1M) / (1_000_000 / GCD_1M),
35        }
36    }
37
38    /// Create an Instant from a millisecond count since system boot.
39    pub const fn from_millis(millis: u64) -> Self {
40        Self {
41            ticks: millis * (TICK_HZ / GCD_1K) / (1000 / GCD_1K),
42        }
43    }
44
45    /// Create an Instant from a second count since system boot.
46    pub const fn from_secs(seconds: u64) -> Self {
47        Self {
48            ticks: seconds * TICK_HZ,
49        }
50    }
51
52    /// Tick count since system boot.
53    pub const fn as_ticks(&self) -> u64 {
54        self.ticks
55    }
56
57    /// Seconds since system boot.
58    pub const fn as_secs(&self) -> u64 {
59        self.ticks / TICK_HZ
60    }
61
62    /// Milliseconds since system boot.
63    pub const fn as_millis(&self) -> u64 {
64        self.ticks * (1000 / GCD_1K) / (TICK_HZ / GCD_1K)
65    }
66
67    /// Microseconds since system boot.
68    pub const fn as_micros(&self) -> u64 {
69        self.ticks * (1_000_000 / GCD_1M) / (TICK_HZ / GCD_1M)
70    }
71
72    /// Duration between this Instant and another Instant
73    /// Panics on over/underflow.
74    pub fn duration_since(&self, earlier: Instant) -> Duration {
75        Duration {
76            ticks: unwrap!(self.ticks.checked_sub(earlier.ticks)),
77        }
78    }
79
80    /// Duration between this Instant and another Instant
81    pub fn checked_duration_since(&self, earlier: Instant) -> Option<Duration> {
82        if self.ticks < earlier.ticks {
83            None
84        } else {
85            Some(Duration {
86                ticks: self.ticks - earlier.ticks,
87            })
88        }
89    }
90
91    /// Returns the duration since the "earlier" Instant.
92    /// If the "earlier" instant is in the future, the duration is set to zero.
93    pub fn saturating_duration_since(&self, earlier: Instant) -> Duration {
94        Duration {
95            ticks: if self.ticks < earlier.ticks {
96                0
97            } else {
98                self.ticks - earlier.ticks
99            },
100        }
101    }
102
103    /// Duration elapsed since this Instant.
104    pub fn elapsed(&self) -> Duration {
105        Instant::now() - *self
106    }
107
108    /// Adds one Duration to self, returning a new `Instant` or None in the event of an overflow.
109    pub fn checked_add(&self, duration: Duration) -> Option<Instant> {
110        self.ticks.checked_add(duration.ticks).map(|ticks| Instant { ticks })
111    }
112
113    /// Subtracts one Duration to self, returning a new `Instant` or None in the event of an overflow.
114    pub fn checked_sub(&self, duration: Duration) -> Option<Instant> {
115        self.ticks.checked_sub(duration.ticks).map(|ticks| Instant { ticks })
116    }
117}
118
119impl Add<Duration> for Instant {
120    type Output = Instant;
121
122    fn add(self, other: Duration) -> Instant {
123        self.checked_add(other)
124            .expect("overflow when adding duration to instant")
125    }
126}
127
128impl AddAssign<Duration> for Instant {
129    fn add_assign(&mut self, other: Duration) {
130        *self = *self + other;
131    }
132}
133
134impl Sub<Duration> for Instant {
135    type Output = Instant;
136
137    fn sub(self, other: Duration) -> Instant {
138        self.checked_sub(other)
139            .expect("overflow when subtracting duration from instant")
140    }
141}
142
143impl SubAssign<Duration> for Instant {
144    fn sub_assign(&mut self, other: Duration) {
145        *self = *self - other;
146    }
147}
148
149impl Sub<Instant> for Instant {
150    type Output = Duration;
151
152    fn sub(self, other: Instant) -> Duration {
153        self.duration_since(other)
154    }
155}
156
157impl<'a> fmt::Display for Instant {
158    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
159        write!(f, "{} ticks", self.ticks)
160    }
161}
embassy_time/instant.rs

embassy_time/
instant.rs
