moonpool-core 0.6.0

Core abstractions for the moonpool simulation framework
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

//! Random number generation provider abstraction.
//!
//! This module provides a provider pattern for random number generation,
//! consistent with other provider abstractions in the simulation framework
//! like TimeProvider, NetworkProvider, and TaskProvider.

use rand::distr::{Distribution, StandardUniform, uniform::SampleUniform};
use rand::prelude::*;
use std::cell::RefCell;
use std::ops::Range;

/// Provider trait for random number generation.
///
/// This trait abstracts random number generation to enable both
/// deterministic simulation randomness and real random numbers
/// in a unified way. Implementations handle the source of randomness
/// appropriate for their environment.
pub trait RandomProvider: Clone {
    /// Generate a random value of type T.
    ///
    /// The type T must implement the Standard distribution.
    fn random<T>(&self) -> T
    where
        StandardUniform: Distribution<T>;

    /// Generate a random value within a specified range.
    ///
    /// The range is exclusive of the upper bound (start..end).
    fn random_range<T>(&self, range: Range<T>) -> T
    where
        T: SampleUniform + PartialOrd;

    /// Generate a random f64 between 0.0 and 1.0.
    ///
    /// This is a convenience method for generating ratios and percentages.
    fn random_ratio(&self) -> f64;

    /// Generate a random bool with the given probability of being true.
    ///
    /// The probability should be between 0.0 and 1.0.
    fn random_bool(&self, probability: f64) -> bool;
}

/// Production random provider using thread-local RNG.
///
/// Uses `rand::rng()` (thread-local, non-cryptographic) for efficient
/// random number generation in production environments.
///
/// # Example
///
/// ```rust
/// use moonpool_core::{RandomProvider, TokioRandomProvider};
///
/// let random = TokioRandomProvider::new();
/// let value: u64 = random.random();
/// let in_range = random.random_range(1..100);
/// ```
#[derive(Clone, Default)]
pub struct TokioRandomProvider;

impl TokioRandomProvider {
    /// Create a new production random provider.
    pub fn new() -> Self {
        Self
    }
}

// Thread-local RNG for TokioRandomProvider
thread_local! {
    static RNG: RefCell<rand::rngs::ThreadRng> = RefCell::new(rand::rng());
}

impl RandomProvider for TokioRandomProvider {
    fn random<T>(&self) -> T
    where
        StandardUniform: Distribution<T>,
    {
        RNG.with(|rng| rng.borrow_mut().random())
    }

    fn random_range<T>(&self, range: Range<T>) -> T
    where
        T: SampleUniform + PartialOrd,
    {
        RNG.with(|rng| rng.borrow_mut().random_range(range))
    }

    fn random_ratio(&self) -> f64 {
        RNG.with(|rng| rng.borrow_mut().random())
    }

    fn random_bool(&self, probability: f64) -> bool {
        self.random_ratio() < probability
    }
}