Skip to main content

critpath_core/
millis.rs

1//! Whole-millisecond durations.
2
3use core::fmt;
4use core::num::NonZeroU64;
5
6/// A duration in whole milliseconds.
7///
8/// Weights are integers rather than floating-point seconds so that ordering is total, sums are
9/// exact, and identical input produces identical output on every platform. Cargo reports two
10/// decimal places of seconds, so milliseconds lose nothing that was ever measured.
11///
12/// Arithmetic saturates rather than overflowing, so a graph with absurd weights produces an
13/// absurd answer instead of a panic or a wrapped one.
14///
15/// ```
16/// use critpath_core::Millis;
17///
18/// let a = Millis::new(1_500);
19/// let b = Millis::new(250);
20/// assert_eq!(a.saturating_add(b), Millis::new(1_750));
21/// assert_eq!(b.saturating_sub(a), Millis::ZERO);
22/// assert_eq!(a.to_string(), "1500ms");
23/// ```
24#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
25pub struct Millis(u64);
26
27impl Millis {
28    /// No time at all.
29    pub const ZERO: Self = Self(0);
30
31    /// A duration of `ms` milliseconds.
32    #[must_use]
33    pub const fn new(ms: u64) -> Self {
34        Self(ms)
35    }
36
37    /// The duration as a count of milliseconds.
38    #[must_use]
39    pub const fn get(self) -> u64 {
40        self.0
41    }
42
43    /// The sum, clamped to the maximum representable duration.
44    #[must_use]
45    pub const fn saturating_add(self, other: Self) -> Self {
46        Self(self.0.saturating_add(other.0))
47    }
48
49    /// The difference, clamped at zero. There are no negative durations.
50    #[must_use]
51    pub const fn saturating_sub(self, other: Self) -> Self {
52        Self(self.0.saturating_sub(other.0))
53    }
54
55    /// The larger of two durations.
56    #[must_use]
57    pub const fn max(self, other: Self) -> Self {
58        if self.0 >= other.0 {
59            self
60        } else {
61            other
62        }
63    }
64
65    /// This duration divided by `divisor`, rounded up.
66    ///
67    /// Rounding up matters because this computes the area bound `total_work / J`, which is a lower
68    /// bound on the makespan. Rounding down would report a bound that no schedule can achieve.
69    #[must_use]
70    pub fn div_ceil_by(self, divisor: NonZeroU64) -> Self {
71        Self(self.0.div_ceil(divisor.get()))
72    }
73
74    /// This duration scaled by the fraction `numerator / denominator`, rounded to nearest.
75    ///
76    /// Used to divide a unit's weight between the halves of a hypothetical split. Widening to 128
77    /// bits keeps the product exact for any duration a real build could produce.
78    #[must_use]
79    pub fn scaled(self, numerator: u64, denominator: NonZeroU64) -> Self {
80        let d = denominator.get() as u128;
81        let product = self.0 as u128 * numerator as u128;
82        // Deliberate integer division; rounding to nearest is done by adding half the divisor.
83        #[allow(clippy::integer_division)]
84        let q = (product + d / 2) / d;
85        // Saturate rather than truncate if a caller passes a numerator larger than the
86        // denominator and the result leaves the range.
87        if q > u64::MAX as u128 {
88            Self(u64::MAX)
89        } else {
90            Self(q as u64)
91        }
92    }
93}
94
95impl fmt::Display for Millis {
96    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
97        write!(f, "{}ms", self.0)
98    }
99}
100
101impl core::iter::Sum for Millis {
102    fn sum<I: Iterator<Item = Self>>(iter: I) -> Self {
103        iter.fold(Self::ZERO, Self::saturating_add)
104    }
105}