horloge 0.1.1

Clock and timer traits
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

use crate::{Clock, Monotonic};
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::{Duration, Instant};

/// Monotic virtual clock using the standard [`Instant`] type.
///
/// The clock is monotonic. It can cover a period of `u64::MAX`
/// nanoseconds (about 584 years).
///
/// If trying to exceed the maximum supported time, the clock
/// will silently saturate.
///
/// The main use case of this clock is to mock time during
/// during tests.
///
/// This clock is internally backed by an atomic u64. References
/// can be shared between threads.
pub struct VirtualStdClock {
  /// Start time of the clock
  start: Instant,
  /// Offset in nanoseconds
  offset: AtomicU64,
}

impl VirtualStdClock {
  /// Create a new virtual clock starting at the provided time.
  pub fn new(start: Instant) -> Self {
    Self {
      start,
      offset: AtomicU64::new(0),
    }
  }

  /// Add the provided duration to the clock.
  ///
  /// Returns the time after the update.
  pub fn advance_by(&self, d: Duration) -> Instant {
    let d: u128 = d.as_nanos();
    let d: u64 = u64::try_from(d).unwrap_or(u64::MAX);
    let prev: u64 = self.offset.load(Ordering::SeqCst);
    let wanted_offset = prev.max(d);
    let prev: u64 = self.offset.fetch_max(wanted_offset, Ordering::SeqCst);
    let current_offset = prev.max(wanted_offset);
    self.start + Duration::from_nanos(current_offset)
  }

  /// Updates the clock to the provided time, if it more recent than the
  /// current time.
  ///
  /// Returns the time after the update.
  pub fn advance_to(&self, t: Instant) -> Instant {
    let wanted_offset: u128 = match t.checked_duration_since(self.start) {
      Some(d) => d.as_nanos(),
      None => 0u128,
    };
    let wanted_offset: u64 = u64::try_from(wanted_offset).unwrap_or(u64::MAX);
    let prev: u64 = self.offset.fetch_max(wanted_offset, Ordering::SeqCst);
    let current_offset = prev.max(wanted_offset);
    self.start + Duration::from_nanos(current_offset)
  }
}

impl Clock for VirtualStdClock {
  type Instant = Instant;

  fn now(&self) -> Self::Instant {
    let current_offset = self.offset.load(Ordering::SeqCst);
    self.start + Duration::from_nanos(current_offset)
  }
}

// SAFETY:
// The monotonicity of `VirtualStdClock::now` depends on the monotonicity
// of `VirtualStdClock::offset`. `VirtualStdClock::offset` is only updated by
// using `u64::fetch_max` to ensure monotonicity.
unsafe impl Monotonic for VirtualStdClock {}

#[cfg(test)]
mod tests {
  use super::*;
  use crate::StdClock;
  const ONE_YEAR: Duration = Duration::new(365 * 24 * 60 * 60, 0);

  #[test]
  fn test_now() {
    let start = Instant::now();
    let clock = VirtualStdClock::new(start);
    use_clock(&clock);
    use_std_clock(&clock);
  }

  fn use_clock<TyClock>(clock: &TyClock)
  where
    TyClock: Clock<Instant = Instant> + Monotonic,
  {
    let one_year_ago = Instant::now() - ONE_YEAR;
    let now = clock.now();
    assert!(now > one_year_ago);
    use_std_clock(clock);
  }

  fn use_std_clock<TyClock>(clock: &TyClock)
  where
    TyClock: StdClock + Monotonic,
  {
    let one_year_ago = Instant::now() - ONE_YEAR;
    let now = clock.now_std();
    assert!(now > one_year_ago);
  }

  #[test]
  fn test_advance_by() {
    let start = Instant::now();
    let clock = VirtualStdClock::new(start);
    assert_eq!(clock.now(), start);
    clock.advance_by(ONE_YEAR);
    assert_eq!(clock.now(), start + ONE_YEAR);
    assert_eq!(clock.now(), start + ONE_YEAR);
  }

  #[test]
  fn test_advance_to() {
    let start = Instant::now();
    let clock = VirtualStdClock::new(start);
    assert_eq!(clock.now(), start);
    clock.advance_to(start + 2 * ONE_YEAR);
    assert_eq!(clock.now(), start + 2 * ONE_YEAR);
    assert_eq!(clock.now(), start + 2 * ONE_YEAR);
  }

  #[test]
  fn test_monotonic() {
    let start = Instant::now();
    let clock = VirtualStdClock::new(start);
    assert_eq!(clock.now(), start);
    clock.advance_to(start + 2 * ONE_YEAR);
    assert_eq!(clock.now(), start + 2 * ONE_YEAR);
    clock.advance_to(start + ONE_YEAR);
    assert_eq!(clock.now(), start + 2 * ONE_YEAR);
  }
}