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