rand/rngs/
thread.rs

1// Copyright 2018 Developers of the Rand project.
2//
3// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
4// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
5// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
6// option. This file may not be copied, modified, or distributed
7// except according to those terms.
8
9//! Thread-local random number generator
10
11use core::cell::UnsafeCell;
12use std::fmt;
13use std::rc::Rc;
14use std::thread_local;
15
16use super::{OsError, OsRng, ReseedingRng, std::Core};
17use rand_core::{CryptoRng, RngCore};
18
19// Rationale for using `UnsafeCell` in `ThreadRng`:
20//
21// Previously we used a `RefCell`, with an overhead of ~15%. There will only
22// ever be one mutable reference to the interior of the `UnsafeCell`, because
23// we only have such a reference inside `next_u32`, `next_u64`, etc. Within a
24// single thread (which is the definition of `ThreadRng`), there will only ever
25// be one of these methods active at a time.
26//
27// A possible scenario where there could be multiple mutable references is if
28// `ThreadRng` is used inside `next_u32` and co. But the implementation is
29// completely under our control. We just have to ensure none of them use
30// `ThreadRng` internally, which is nonsensical anyway. We should also never run
31// `ThreadRng` in destructors of its implementation, which is also nonsensical.
32
33// Number of generated bytes after which to reseed `ThreadRng`.
34// According to benchmarks, reseeding has a noticeable impact with thresholds
35// of 32 kB and less. We choose 64 kB to avoid significant overhead.
36const THREAD_RNG_RESEED_THRESHOLD: u64 = 1024 * 64;
37
38/// A reference to the thread-local generator
39///
40/// This type is a reference to a lazily-initialized thread-local generator.
41/// An instance can be obtained via [`rand::rng()`][crate::rng()] or via
42/// [`ThreadRng::default()`].
43/// The handle cannot be passed between threads (is not `Send` or `Sync`).
44///
45/// # Security
46///
47/// Security must be considered relative to a threat model and validation
48/// requirements. The Rand project can provide no guarantee of fitness for
49/// purpose. The design criteria for `ThreadRng` are as follows:
50///
51/// - Automatic seeding via [`OsRng`] and periodically thereafter (see
52///   ([`ReseedingRng`] documentation). Limitation: there is no automatic
53///   reseeding on process fork (see [below](#fork)).
54/// - A rigorusly analyzed, unpredictable (cryptographic) pseudo-random generator
55///   (see [the book on security](https://rust-random.github.io/book/guide-rngs.html#security)).
56///   The currently selected algorithm is ChaCha (12-rounds).
57///   See also [`StdRng`] documentation.
58/// - Not to leak internal state through [`Debug`] or serialization
59///   implementations.
60/// - No further protections exist to in-memory state. In particular, the
61///   implementation is not required to zero memory on exit (of the process or
62///   thread). (This may change in the future.)
63/// - Be fast enough for general-purpose usage. Note in particular that
64///   `ThreadRng` is designed to be a "fast, reasonably secure generator"
65///   (where "reasonably secure" implies the above criteria).
66///
67/// We leave it to the user to determine whether this generator meets their
68/// security requirements. For an alternative, see [`OsRng`].
69///
70/// # Fork
71///
72/// `ThreadRng` is not automatically reseeded on fork. It is recommended to
73/// explicitly call [`ThreadRng::reseed`] immediately after a fork, for example:
74/// ```ignore
75/// fn do_fork() {
76///     let pid = unsafe { libc::fork() };
77///     if pid == 0 {
78///         // Reseed ThreadRng in child processes:
79///         rand::rng().reseed();
80///     }
81/// }
82/// ```
83///
84/// Methods on `ThreadRng` are not reentrant-safe and thus should not be called
85/// from an interrupt (e.g. a fork handler) unless it can be guaranteed that no
86/// other method on the same `ThreadRng` is currently executing.
87///
88/// [`ReseedingRng`]: crate::rngs::ReseedingRng
89/// [`StdRng`]: crate::rngs::StdRng
90#[derive(Clone)]
91pub struct ThreadRng {
92    // Rc is explicitly !Send and !Sync
93    rng: Rc<UnsafeCell<ReseedingRng<Core, OsRng>>>,
94}
95
96impl ThreadRng {
97    /// Immediately reseed the generator
98    ///
99    /// This discards any remaining random data in the cache.
100    pub fn reseed(&mut self) -> Result<(), OsError> {
101        // SAFETY: We must make sure to stop using `rng` before anyone else
102        // creates another mutable reference
103        let rng = unsafe { &mut *self.rng.get() };
104        rng.reseed()
105    }
106}
107
108/// Debug implementation does not leak internal state
109impl fmt::Debug for ThreadRng {
110    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
111        write!(fmt, "ThreadRng {{ .. }}")
112    }
113}
114
115thread_local!(
116    // We require Rc<..> to avoid premature freeing when ThreadRng is used
117    // within thread-local destructors. See #968.
118    static THREAD_RNG_KEY: Rc<UnsafeCell<ReseedingRng<Core, OsRng>>> = {
119        let rng = ReseedingRng::new(THREAD_RNG_RESEED_THRESHOLD,
120                                    OsRng).unwrap_or_else(|err|
121                panic!("could not initialize ThreadRng: {}", err));
122        Rc::new(UnsafeCell::new(rng))
123    }
124);
125
126/// Access a fast, pre-initialized generator
127///
128/// This is a handle to the local [`ThreadRng`].
129///
130/// See also [`crate::rngs`] for alternatives.
131///
132/// # Example
133///
134/// ```
135/// use rand::prelude::*;
136///
137/// # fn main() {
138///
139/// let mut numbers = [1, 2, 3, 4, 5];
140/// numbers.shuffle(&mut rand::rng());
141/// println!("Numbers: {numbers:?}");
142///
143/// // Using a local binding avoids an initialization-check on each usage:
144/// let mut rng = rand::rng();
145///
146/// println!("True or false: {}", rng.random::<bool>());
147/// println!("A simulated die roll: {}", rng.random_range(1..=6));
148/// # }
149/// ```
150///
151/// # Security
152///
153/// Refer to [`ThreadRng#Security`].
154pub fn rng() -> ThreadRng {
155    let rng = THREAD_RNG_KEY.with(|t| t.clone());
156    ThreadRng { rng }
157}
158
159impl Default for ThreadRng {
160    fn default() -> ThreadRng {
161        rng()
162    }
163}
164
165impl RngCore for ThreadRng {
166    #[inline(always)]
167    fn next_u32(&mut self) -> u32 {
168        // SAFETY: We must make sure to stop using `rng` before anyone else
169        // creates another mutable reference
170        let rng = unsafe { &mut *self.rng.get() };
171        rng.next_u32()
172    }
173
174    #[inline(always)]
175    fn next_u64(&mut self) -> u64 {
176        // SAFETY: We must make sure to stop using `rng` before anyone else
177        // creates another mutable reference
178        let rng = unsafe { &mut *self.rng.get() };
179        rng.next_u64()
180    }
181
182    #[inline(always)]
183    fn fill_bytes(&mut self, dest: &mut [u8]) {
184        // SAFETY: We must make sure to stop using `rng` before anyone else
185        // creates another mutable reference
186        let rng = unsafe { &mut *self.rng.get() };
187        rng.fill_bytes(dest)
188    }
189}
190
191impl CryptoRng for ThreadRng {}
192
193#[cfg(test)]
194mod test {
195    #[test]
196    fn test_thread_rng() {
197        use crate::Rng;
198        let mut r = crate::rng();
199        r.random::<i32>();
200        assert_eq!(r.random_range(0..1), 0);
201    }
202
203    #[test]
204    fn test_debug_output() {
205        // We don't care about the exact output here, but it must not include
206        // private CSPRNG state or the cache stored by BlockRng!
207        assert_eq!(std::format!("{:?}", crate::rng()), "ThreadRng { .. }");
208    }
209}
rand/rngs/thread.rs

rand/rngs/
thread.rs
