Debian Codegraph @

.cargo/vendor/rand/src/rngs/thread.rs

raw
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
11 use core::cell::UnsafeCell;
12 use std::fmt;
13 use std::rc::Rc;
14 use std::thread_local;
15
16 use rand_core::{CryptoRng, RngCore};
17
18 use super::std::Core;
19 use crate::rngs::OsRng;
20 use 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.
39 const 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)]
94 pub struct ThreadRng {
95 // Rc is explicitly !Send and !Sync
96 rng: Rc<UnsafeCell<ReseedingRng<Core, OsRng>>>,
97 }
98
99 impl 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 = unsafe { &mut *self.rng.get() };
107 rng.reseed()
108 }
109 }
110
111 /// Debug implementation does not leak internal state
112 impl fmt::Debug for ThreadRng {
113 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
114 write!(fmt, "ThreadRng {{ .. }}")
115 }
116 }
117
118 thread_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`].
157 pub fn rng() -> ThreadRng {
158 let rng = THREAD_RNG_KEY.with(|t| t.clone());
159 ThreadRng { rng }
160 }
161
162 impl Default for ThreadRng {
163 fn default() -> ThreadRng {
164 rng()
165 }
166 }
167
168 impl 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
194 impl CryptoRng for ThreadRng {}
195
196 #[cfg(test)]
197 mod 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 }