tcp/util/
time.rs

1//! Traits that provide an abstract interface for time-related operations, modelled after [`std::time`].
2//!
3//! ```
4//! fn add_durations<T: tcp::util::time::Duration>(x1: T, x2: T) -> T {
5//!     x1 + x2
6//! }
7//!
8//! use std::time::Duration;
9//! assert_eq!(
10//!     add_durations(Duration::from_secs(1), Duration::from_millis(2)),
11//!     Duration::from_secs(1) + Duration::from_millis(2),
12//! );
13//! ```
14
15// this is only used in doc comments.
16#[allow(unused)]
17use crate::Dependencies;
18
19use std::fmt::Debug;
20
21/// A trait for time instants that follow the API of [`std::time::Instant`]. This is useful for code
22/// that should work with not just the real time, but also simulated time.
23pub trait Instant:
24    'static
25    + Sized
26    + Copy
27    + Clone
28    + Debug
29    + std::ops::Add<Self::Duration, Output = Self>
30    + std::ops::AddAssign<Self::Duration>
31    + std::ops::Sub<Self::Duration, Output = Self>
32    + std::ops::Sub<Self, Output = Self::Duration>
33    + std::ops::SubAssign<Self::Duration>
34    + std::cmp::PartialOrd
35    + std::cmp::Ord
36    + std::cmp::PartialEq
37    + std::cmp::Eq
38    + std::hash::Hash
39{
40    type Duration: Duration;
41
42    /// See [`std::time::Instant::duration_since`].
43    fn duration_since(&self, earlier: Self) -> Self::Duration;
44    /// See [`std::time::Instant::saturating_duration_since`].
45    fn saturating_duration_since(&self, earlier: Self) -> Self::Duration;
46    /// See [`std::time::Instant::checked_duration_since`].
47    fn checked_duration_since(&self, earlier: Self) -> Option<Self::Duration>;
48    /// See [`std::time::Instant::checked_add`].
49    fn checked_add(&self, duration: Self::Duration) -> Option<Self>;
50    /// See [`std::time::Instant::checked_sub`].
51    fn checked_sub(&self, duration: Self::Duration) -> Option<Self>;
52}
53
54/// A trait for time durations that follow the API of [`std::time::Duration`]. This is useful for
55/// code that should work with not just the real time, but also simulated time.
56pub trait Duration:
57    'static
58    + Sized
59    + Copy
60    + Clone
61    + Debug
62    + std::ops::Add<Output = Self>
63    + std::ops::AddAssign
64    + std::ops::Sub<Output = Self>
65    + std::ops::SubAssign
66    + std::ops::Mul<u32>
67    + std::ops::MulAssign<u32>
68    + std::ops::Div<u32>
69    + std::ops::DivAssign<u32>
70    + std::cmp::PartialOrd
71    + std::cmp::Ord
72    + std::cmp::PartialEq
73    + std::cmp::Eq
74    + std::hash::Hash
75// it would also be nice to include the bound `u32: std::ops::Mul<Self>`, but we can't do that
76// without a where clause, and the where clause would need to be duplicated everywhere that we use
77// the trait
78{
79    /// See [`std::time::Duration::MAX`].
80    const MAX: Self;
81    /// See [`std::time::Duration::NANOSECOND`].
82    const NANOSECOND: Self;
83    /// See [`std::time::Duration::MICROSECOND`].
84    const MICROSECOND: Self;
85    /// See [`std::time::Duration::MILLISECOND`].
86    const MILLISECOND: Self;
87    /// See [`std::time::Duration::SECOND`].
88    const SECOND: Self;
89    /// See [`std::time::Duration::ZERO`].
90    const ZERO: Self;
91
92    /// See [`std::time::Duration::as_micros`].
93    fn as_micros(&self) -> u128;
94    /// See [`std::time::Duration::as_millis`].
95    fn as_millis(&self) -> u128;
96    /// See [`std::time::Duration::as_nanos`].
97    fn as_nanos(&self) -> u128;
98    /// See [`std::time::Duration::as_secs`].
99    fn as_secs(&self) -> u64;
100    /// See [`std::time::Duration::checked_add`].
101    fn checked_add(self, rhs: Self) -> Option<Self>;
102    /// See [`std::time::Duration::checked_div`].
103    fn checked_div(self, rhs: u32) -> Option<Self>;
104    /// See [`std::time::Duration::checked_mul`].
105    fn checked_mul(self, rhs: u32) -> Option<Self>;
106    /// See [`std::time::Duration::checked_sub`].
107    fn checked_sub(self, rhs: Self) -> Option<Self>;
108    /// See [`std::time::Duration::from_micros`].
109    fn from_micros(micros: u64) -> Self;
110    /// See [`std::time::Duration::from_millis`].
111    fn from_millis(millis: u64) -> Self;
112    /// See [`std::time::Duration::from_nanos`].
113    fn from_nanos(nanos: u64) -> Self;
114    /// See [`std::time::Duration::from_secs`].
115    fn from_secs(secs: u64) -> Self;
116    /// See [`std::time::Duration::is_zero`].
117    fn is_zero(&self) -> bool;
118    /// See [`std::time::Duration::saturating_add`].
119    fn saturating_add(self, rhs: Self) -> Self;
120    /// See [`std::time::Duration::saturating_mul`].
121    fn saturating_mul(self, rhs: u32) -> Self;
122    /// See [`std::time::Duration::saturating_sub`].
123    fn saturating_sub(self, rhs: Self) -> Self;
124    /// See [`std::time::Duration::subsec_micros`].
125    fn subsec_micros(&self) -> u32;
126    /// See [`std::time::Duration::subsec_millis`].
127    fn subsec_millis(&self) -> u32;
128    /// See [`std::time::Duration::subsec_nanos`].
129    fn subsec_nanos(&self) -> u32;
130}
131
132/// Calls into [`std::time::Instant`] methods of the same name.
133impl Instant for std::time::Instant {
134    type Duration = std::time::Duration;
135
136    #[inline]
137    fn duration_since(&self, earlier: Self) -> Self::Duration {
138        self.duration_since(earlier)
139    }
140
141    #[inline]
142    fn saturating_duration_since(&self, earlier: Self) -> Self::Duration {
143        self.saturating_duration_since(earlier)
144    }
145
146    #[inline]
147    fn checked_duration_since(&self, earlier: Self) -> Option<Self::Duration> {
148        self.checked_duration_since(earlier)
149    }
150
151    #[inline]
152    fn checked_add(&self, duration: Self::Duration) -> Option<Self> {
153        self.checked_add(duration)
154    }
155
156    #[inline]
157    fn checked_sub(&self, duration: Self::Duration) -> Option<Self> {
158        self.checked_sub(duration)
159    }
160}
161
162/// Calls into [`std::time::Duration`] methods of the same name.
163impl Duration for std::time::Duration {
164    const MAX: Self = Self::MAX;
165    // the std lib does contain these constants on nightly
166    const NANOSECOND: Self = Self::from_nanos(1);
167    const MICROSECOND: Self = Self::from_micros(1);
168    const MILLISECOND: Self = Self::from_millis(1);
169    const SECOND: Self = Self::from_secs(1);
170    const ZERO: Self = Self::ZERO;
171
172    #[inline]
173    fn as_micros(&self) -> u128 {
174        self.as_micros()
175    }
176
177    #[inline]
178    fn as_millis(&self) -> u128 {
179        self.as_millis()
180    }
181
182    #[inline]
183    fn as_nanos(&self) -> u128 {
184        self.as_nanos()
185    }
186
187    #[inline]
188    fn as_secs(&self) -> u64 {
189        self.as_secs()
190    }
191
192    #[inline]
193    fn checked_add(self, rhs: Self) -> Option<Self> {
194        self.checked_add(rhs)
195    }
196
197    #[inline]
198    fn checked_div(self, rhs: u32) -> Option<Self> {
199        self.checked_div(rhs)
200    }
201
202    #[inline]
203    fn checked_mul(self, rhs: u32) -> Option<Self> {
204        self.checked_mul(rhs)
205    }
206
207    #[inline]
208    fn checked_sub(self, rhs: Self) -> Option<Self> {
209        self.checked_sub(rhs)
210    }
211
212    #[inline]
213    fn from_micros(micros: u64) -> Self {
214        Self::from_micros(micros)
215    }
216
217    #[inline]
218    fn from_millis(millis: u64) -> Self {
219        Self::from_millis(millis)
220    }
221
222    #[inline]
223    fn from_nanos(nanos: u64) -> Self {
224        Self::from_nanos(nanos)
225    }
226
227    #[inline]
228    fn from_secs(secs: u64) -> Self {
229        Self::from_secs(secs)
230    }
231
232    #[inline]
233    fn is_zero(&self) -> bool {
234        self.is_zero()
235    }
236
237    #[inline]
238    fn saturating_add(self, rhs: Self) -> Self {
239        self.saturating_add(rhs)
240    }
241
242    #[inline]
243    fn saturating_mul(self, rhs: u32) -> Self {
244        self.saturating_mul(rhs)
245    }
246
247    #[inline]
248    fn saturating_sub(self, rhs: Self) -> Self {
249        self.saturating_sub(rhs)
250    }
251
252    #[inline]
253    fn subsec_micros(&self) -> u32 {
254        self.subsec_micros()
255    }
256
257    #[inline]
258    fn subsec_millis(&self) -> u32 {
259        self.subsec_millis()
260    }
261
262    #[inline]
263    fn subsec_nanos(&self) -> u32 {
264        self.subsec_nanos()
265    }
266}
tcp/util/time.rs

tcp/util/
time.rs
