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, convert::Infallible};
12use std::fmt;
13use std::rc::Rc;
14use std::thread_local;
15
16use super::{SysError, SysRng};
17use rand_core::SeedableRng;
18use rand_core::block::{BlockRng, Generator};
19use rand_core::{TryCryptoRng, TryRng};
20
21// Rationale for using `UnsafeCell` in `ThreadRng`:
22//
23// Previously we used a `RefCell`, with an overhead of ~15%. There will only
24// ever be one mutable reference to the interior of the `UnsafeCell`, because
25// we only have such a reference inside `next_u32`, `next_u64`, etc. Within a
26// single thread (which is the definition of `ThreadRng`), there will only ever
27// be one of these methods active at a time.
28//
29// A possible scenario where there could be multiple mutable references is if
30// `ThreadRng` is used inside `next_u32` and co. But the implementation is
31// completely under our control. We just have to ensure none of them use
32// `ThreadRng` internally, which is nonsensical anyway. We should also never run
33// `ThreadRng` in destructors of its implementation, which is also nonsensical.
34
35// Number of generated bytes after which to reseed `ThreadRng`.
36// According to benchmarks, reseeding has a noticeable impact with thresholds
37// of 32 kB and less. We choose 64 kiB output to avoid significant overhead;
38// since a block consists of 16 4-byte words this equals 1024 blocks.
39const RESEED_BLOCK_THRESHOLD: u64 = 1024;
40
41type Core = chacha20::ChaChaCore<chacha20::R12, chacha20::variants::Legacy>;
42type Results = <Core as Generator>::Output;
43
44struct ReseedingCore {
45    inner: Core,
46}
47
48impl Generator for ReseedingCore {
49    type Output = Results;
50
51    #[inline(always)]
52    fn generate(&mut self, results: &mut Results) {
53        if self.inner.get_block_pos() >= RESEED_BLOCK_THRESHOLD {
54            self.try_to_reseed();
55        }
56        self.inner.generate(results);
57    }
58}
59
60impl ReseedingCore {
61    /// Reseed the internal PRNG.
62    fn reseed(&mut self) -> Result<(), SysError> {
63        Core::try_from_rng(&mut SysRng).map(|result| self.inner = result)
64    }
65
66    #[cold]
67    #[inline(never)]
68    fn try_to_reseed(&mut self) {
69        if let Err(e) = self.reseed() {
70            panic!("could not reseed ThreadRng: {e}");
71        }
72    }
73}
74
75/// A reference to the thread-local generator
76///
77/// This type is a reference to a lazily-initialized thread-local generator.
78/// An instance can be obtained via [`rand::rng()`][crate::rng()] or via
79/// [`ThreadRng::default()`].
80/// The handle cannot be passed between threads (is not `Send` or `Sync`).
81///
82/// # Security
83///
84/// Security must be considered relative to a threat model and validation
85/// requirements. The Rand project can provide no guarantee of fitness for
86/// purpose. The design criteria for `ThreadRng` are as follows:
87///
88/// - Automatic seeding via [`SysRng`] and after every 64 kB of output.
89///   Limitation: there is no automatic reseeding on process fork (see [below](#fork)).
90/// - A rigorously analyzed, unpredictable (cryptographic) pseudo-random generator
91///   (see [the book on security](https://rust-random.github.io/book/guide-rngs.html#security)).
92///   The currently selected algorithm is ChaCha (12-rounds).
93///   See also [`StdRng`] documentation.
94/// - Not to leak internal state through [`Debug`] or serialization
95///   implementations.
96/// - No further protections exist to in-memory state. In particular, the
97///   implementation is not required to zero memory on exit (of the process or
98///   thread). (This may change in the future.)
99/// - Be fast enough for general-purpose usage. Note in particular that
100///   `ThreadRng` is designed to be a "fast, reasonably secure generator"
101///   (where "reasonably secure" implies the above criteria).
102///
103/// We leave it to the user to determine whether this generator meets their
104/// security requirements. For an alternative, see [`SysRng`].
105///
106/// # Forks and interrupts
107///
108/// `ThreadRng` is not automatically reseeded on fork. It is recommended to
109/// explicitly call [`ThreadRng::reseed`] immediately after a fork, for example:
110/// ```ignore
111/// fn do_fork() {
112///     let pid = unsafe { libc::fork() };
113///     if pid == 0 {
114///         // Reseed ThreadRng in child processes:
115///         rand::rng().reseed();
116///     }
117/// }
118/// ```
119///
120/// Methods on `ThreadRng` are not reentrant-safe and thus should not be called
121/// from an interrupt (e.g. a fork handler) unless it can be guaranteed that no
122/// other method on the same `ThreadRng` is currently executing.
123///
124/// # Panics
125///
126/// Implementations of [`TryRng`] and [`Rng`] panic in case of [`SysRng`]
127/// failure during reseeding (highly unlikely).
128///
129/// [`StdRng`]: crate::rngs::StdRng
130/// [`Rng`]: rand_core::Rng
131#[derive(Clone)]
132pub struct ThreadRng {
133    // Rc is explicitly !Send and !Sync
134    rng: Rc<UnsafeCell<BlockRng<ReseedingCore>>>,
135}
136
137impl ThreadRng {
138    /// Immediately reseed the generator
139    ///
140    /// This discards any remaining random data in the cache.
141    pub fn reseed(&mut self) -> Result<(), SysError> {
142        // SAFETY: We must make sure to stop using `rng` before anyone else
143        // creates another mutable reference
144        let rng = unsafe { &mut *self.rng.get() };
145        rng.reset_and_skip(0);
146        rng.core.reseed()
147    }
148}
149
150/// Debug implementation does not leak internal state
151impl fmt::Debug for ThreadRng {
152    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
153        write!(fmt, "ThreadRng {{ .. }}")
154    }
155}
156
157thread_local!(
158    // We require Rc<..> to avoid premature freeing when ThreadRng is used
159    // within thread-local destructors. See #968.
160    static THREAD_RNG_KEY: Rc<UnsafeCell<BlockRng<ReseedingCore>>> = {
161        Rc::new(UnsafeCell::new(BlockRng::new(ReseedingCore {
162            inner: Core::try_from_rng(&mut SysRng).unwrap_or_else(|err| {
163                panic!("could not initialize ThreadRng: {}", err)
164            }),
165        })))
166    }
167);
168
169/// Access a fast, pre-initialized generator
170///
171/// This is a handle to the local [`ThreadRng`].
172///
173/// See also [`crate::rngs`] for alternatives.
174///
175/// # Example
176///
177/// ```
178/// use rand::prelude::*;
179///
180/// # fn main() {
181///
182/// let mut numbers = [1, 2, 3, 4, 5];
183/// numbers.shuffle(&mut rand::rng());
184/// println!("Numbers: {numbers:?}");
185///
186/// // Using a local binding avoids an initialization-check on each usage:
187/// let mut rng = rand::rng();
188///
189/// println!("True or false: {}", rng.random::<bool>());
190/// println!("A simulated die roll: {}", rng.random_range(1..=6));
191/// # }
192/// ```
193///
194/// # Security
195///
196/// Refer to [`ThreadRng#Security`].
197///
198/// # Panics
199///
200/// This method panics in case of [`SysRng`] failure during initial seeding.
201pub fn rng() -> ThreadRng {
202    let rng = THREAD_RNG_KEY.with(|t| t.clone());
203    ThreadRng { rng }
204}
205
206impl Default for ThreadRng {
207    fn default() -> ThreadRng {
208        rng()
209    }
210}
211
212impl TryRng for ThreadRng {
213    type Error = Infallible;
214
215    #[inline(always)]
216    fn try_next_u32(&mut self) -> Result<u32, Infallible> {
217        // SAFETY: We must make sure to stop using `rng` before anyone else
218        // creates another mutable reference
219        let rng = unsafe { &mut *self.rng.get() };
220        Ok(rng.next_word())
221    }
222
223    #[inline(always)]
224    fn try_next_u64(&mut self) -> Result<u64, Infallible> {
225        // SAFETY: We must make sure to stop using `rng` before anyone else
226        // creates another mutable reference
227        let rng = unsafe { &mut *self.rng.get() };
228        Ok(rng.next_u64_from_u32())
229    }
230
231    #[inline(always)]
232    fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Infallible> {
233        // SAFETY: We must make sure to stop using `rng` before anyone else
234        // creates another mutable reference
235        let rng = unsafe { &mut *self.rng.get() };
236        rng.fill_bytes(dest);
237        Ok(())
238    }
239}
240
241impl TryCryptoRng for ThreadRng {}
242
243#[cfg(test)]
244mod test {
245    #[test]
246    fn test_thread_rng() {
247        use crate::RngExt;
248        let mut r = crate::rng();
249        r.random::<i32>();
250        assert_eq!(r.random_range(0..1), 0);
251    }
252
253    #[test]
254    fn test_debug_output() {
255        // We don't care about the exact output here, but it must not include
256        // private CSPRNG state or the cache stored by BlockRng!
257        assert_eq!(std::format!("{:?}", crate::rng()), "ThreadRng { .. }");
258    }
259}
rand/rngs/thread.rs

rand/rngs/
thread.rs
