Skip to main content

hyprstream_bench/
rng.rs

1//! The pinned benchmark PRNG.
2//!
3//! Item generation must be bit-reproducible forever: the frozen manifest
4//! (hashes) is the contract that P1.3's contamination firewall and the P1.4
5//! gates consume, so the random stream is part of the released artifact. We
6//! therefore pin our own generator instead of depending on an external `rand`
7//! crate whose stream semantics may change across versions.
8//!
9//! Algorithm: **splitmix64**, counter-based. `FROZEN: changing anything in
10//! this file invalidates every published item hash.`
11
12/// A splitmix64 stream. State advances by the golden-ratio constant on every
13/// draw; the output is the standard splitmix64 finalizer.
14#[derive(Debug, Clone)]
15pub struct BenchRng {
16    state: u64,
17}
18
19impl BenchRng {
20    /// Start a stream from a 64-bit seed.
21    pub fn new(seed: u64) -> Self {
22        Self { state: seed }
23    }
24
25    /// Derive an independent stream for (seed, stream index) pairs.
26    pub fn keyed(seed: u64, key: u64) -> Self {
27        let mut root = Self::new(seed);
28        let mixed = root.next_u64() ^ key.wrapping_mul(0x9E37_79B9_7F4A_7C15);
29        Self::new(mixed)
30    }
31
32    /// The next 64-bit value.
33    pub fn next_u64(&mut self) -> u64 {
34        self.state = self.state.wrapping_add(0x9E37_79B9_7F4A_7C15);
35        let mut z = self.state;
36        z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
37        z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
38        z ^ (z >> 31)
39    }
40
41    /// Uniform integer in `0..n` (rejection-free multiply-high; bias is
42    /// negligible at our n ≤ 255 and identical on every platform).
43    pub fn below(&mut self, n: u64) -> u64 {
44        debug_assert!(n > 0);
45        ((self.next_u64() as u128 * n as u128) >> 64) as u64
46    }
47
48    /// Uniform integer in `lo..=hi`.
49    pub fn range(&mut self, lo: i64, hi: i64) -> i64 {
50        debug_assert!(lo <= hi);
51        lo + self.below((hi - lo + 1) as u64) as i64
52    }
53
54    /// Fisher–Yates shuffle of `0..n` drawn from this stream.
55    pub fn permutation(&mut self, n: usize) -> Vec<usize> {
56        let mut order: Vec<usize> = (0..n).collect();
57        for i in (1..n).rev() {
58            let j = self.below(i as u64 + 1) as usize;
59            order.swap(i, j);
60        }
61        order
62    }
63}
64
65#[cfg(test)]
66mod tests {
67    use super::*;
68
69    #[test]
70    fn stream_is_deterministic() {
71        let mut a = BenchRng::new(42);
72        let mut b = BenchRng::new(42);
73        for _ in 0..1000 {
74            assert_eq!(a.next_u64(), b.next_u64());
75        }
76    }
77
78    #[test]
79    fn pinned_golden_values() {
80        // Regression lock: if these change, every frozen item hash changes.
81        let mut rng = BenchRng::new(0);
82        let values: Vec<u64> = (0..4).map(|_| rng.next_u64()).collect();
83        assert_eq!(
84            values,
85            vec![
86                0xE220_A839_7B1D_CDAF,
87                0x6E78_9E6A_A1B9_65F4,
88                0x06C4_5D18_8009_454F,
89                0xF88B_B8A8_724C_81EC,
90            ]
91        );
92    }
93}