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}