qubit_clock/wall/
wall_clock.rs

1// =============================================================================
2//    Copyright (c) 2025 - 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Defines the wall-clock capability.
9
10use std::time::SystemTime;
11
12/// Provides the current civil time as a [`SystemTime`].
13///
14/// Unlike monotonic time, wall time may move backward after a system clock
15/// adjustment and must not be used to measure elapsed durations.
16///
17/// Discarding a sampled wall time is rejected when `unused_must_use` is denied:
18///
19/// ```compile_fail
20/// #![deny(unused_must_use)]
21/// use qubit_clock::{StdWallClock, WallClock};
22///
23/// StdWallClock::new().now();
24/// ```
25pub trait WallClock: Send + Sync {
26    /// Returns the current wall-clock time.
27    ///
28    /// # Returns
29    ///
30    /// The implementor's current civil-time reading.
31    #[must_use = "the sampled wall-clock time should be used"]
32    fn now(&self) -> SystemTime;
33}
34
35impl<T> WallClock for &T
36where
37    T: WallClock + ?Sized,
38{
39    /// Delegates to the borrowed wall clock object.
40    ///
41    /// # Returns
42    ///
43    /// The current wall time returned by the borrowed clock.
44    #[inline(always)]
45    fn now(&self) -> SystemTime {
46        <T as WallClock>::now(*self)
47    }
48}
49
50impl<T> WallClock for std::sync::Arc<T>
51where
52    T: WallClock + ?Sized,
53{
54    /// Delegates to the shared wall clock object.
55    ///
56    /// # Returns
57    ///
58    /// The current wall time returned by the wrapped clock.
59    #[inline(always)]
60    fn now(&self) -> SystemTime {
61        self.as_ref().now()
62    }
63}
64
65impl<T> WallClock for Box<T>
66where
67    T: WallClock + ?Sized,
68{
69    /// Delegates to the boxed wall clock object.
70    ///
71    /// # Returns
72    ///
73    /// The current wall time returned by the wrapped clock.
74    #[inline(always)]
75    fn now(&self) -> SystemTime {
76        self.as_ref().now()
77    }
78}
qubit_clock/wall/wall_clock.rs

qubit_clock/wall/
wall_clock.rs
