144 lines
5.3 KiB
Rust
144 lines
5.3 KiB
Rust
// Copyright 2018 Developers of the Rand project.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
|
|
// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
|
|
// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
|
|
// option. This file may not be copied, modified, or distributed
|
|
// except according to those terms.
|
|
|
|
//! Thread-local random number generator
|
|
|
|
use core::cell::UnsafeCell;
|
|
use std::rc::Rc;
|
|
use std::thread_local;
|
|
|
|
use super::std::Core;
|
|
use crate::rngs::adapter::ReseedingRng;
|
|
use crate::rngs::OsRng;
|
|
use crate::{CryptoRng, Error, RngCore, SeedableRng};
|
|
|
|
// Rationale for using `UnsafeCell` in `ThreadRng`:
|
|
//
|
|
// Previously we used a `RefCell`, with an overhead of ~15%. There will only
|
|
// ever be one mutable reference to the interior of the `UnsafeCell`, because
|
|
// we only have such a reference inside `next_u32`, `next_u64`, etc. Within a
|
|
// single thread (which is the definition of `ThreadRng`), there will only ever
|
|
// be one of these methods active at a time.
|
|
//
|
|
// A possible scenario where there could be multiple mutable references is if
|
|
// `ThreadRng` is used inside `next_u32` and co. But the implementation is
|
|
// completely under our control. We just have to ensure none of them use
|
|
// `ThreadRng` internally, which is nonsensical anyway. We should also never run
|
|
// `ThreadRng` in destructors of its implementation, which is also nonsensical.
|
|
|
|
|
|
// Number of generated bytes after which to reseed `ThreadRng`.
|
|
// According to benchmarks, reseeding has a noticeable impact with thresholds
|
|
// of 32 kB and less. We choose 64 kB to avoid significant overhead.
|
|
const THREAD_RNG_RESEED_THRESHOLD: u64 = 1024 * 64;
|
|
|
|
/// A reference to the thread-local generator
|
|
///
|
|
/// An instance can be obtained via [`thread_rng`] or via `ThreadRng::default()`.
|
|
/// This handle is safe to use everywhere (including thread-local destructors),
|
|
/// though it is recommended not to use inside a fork handler.
|
|
/// The handle cannot be passed between threads (is not `Send` or `Sync`).
|
|
///
|
|
/// `ThreadRng` uses the same PRNG as [`StdRng`] for security and performance
|
|
/// and is automatically seeded from [`OsRng`].
|
|
///
|
|
/// Unlike `StdRng`, `ThreadRng` uses the [`ReseedingRng`] wrapper to reseed
|
|
/// the PRNG from fresh entropy every 64 kiB of random data as well as after a
|
|
/// fork on Unix (though not quite immediately; see documentation of
|
|
/// [`ReseedingRng`]).
|
|
/// Note that the reseeding is done as an extra precaution against side-channel
|
|
/// attacks and mis-use (e.g. if somehow weak entropy were supplied initially).
|
|
/// The PRNG algorithms used are assumed to be secure.
|
|
///
|
|
/// [`ReseedingRng`]: crate::rngs::adapter::ReseedingRng
|
|
/// [`StdRng`]: crate::rngs::StdRng
|
|
#[cfg_attr(doc_cfg, doc(cfg(all(feature = "std", feature = "std_rng"))))]
|
|
#[derive(Clone, Debug)]
|
|
pub struct ThreadRng {
|
|
// Rc is explicitly !Send and !Sync
|
|
rng: Rc<UnsafeCell<ReseedingRng<Core, OsRng>>>,
|
|
}
|
|
|
|
thread_local!(
|
|
// We require Rc<..> to avoid premature freeing when thread_rng is used
|
|
// within thread-local destructors. See #968.
|
|
static THREAD_RNG_KEY: Rc<UnsafeCell<ReseedingRng<Core, OsRng>>> = {
|
|
let r = Core::from_rng(OsRng).unwrap_or_else(|err|
|
|
panic!("could not initialize thread_rng: {}", err));
|
|
let rng = ReseedingRng::new(r,
|
|
THREAD_RNG_RESEED_THRESHOLD,
|
|
OsRng);
|
|
Rc::new(UnsafeCell::new(rng))
|
|
}
|
|
);
|
|
|
|
/// Retrieve the lazily-initialized thread-local random number generator,
|
|
/// seeded by the system. Intended to be used in method chaining style,
|
|
/// e.g. `thread_rng().gen::<i32>()`, or cached locally, e.g.
|
|
/// `let mut rng = thread_rng();`. Invoked by the `Default` trait, making
|
|
/// `ThreadRng::default()` equivalent.
|
|
///
|
|
/// For more information see [`ThreadRng`].
|
|
#[cfg_attr(doc_cfg, doc(cfg(all(feature = "std", feature = "std_rng"))))]
|
|
pub fn thread_rng() -> ThreadRng {
|
|
let rng = THREAD_RNG_KEY.with(|t| t.clone());
|
|
ThreadRng { rng }
|
|
}
|
|
|
|
impl Default for ThreadRng {
|
|
fn default() -> ThreadRng {
|
|
crate::prelude::thread_rng()
|
|
}
|
|
}
|
|
|
|
impl RngCore for ThreadRng {
|
|
#[inline(always)]
|
|
fn next_u32(&mut self) -> u32 {
|
|
// SAFETY: We must make sure to stop using `rng` before anyone else
|
|
// creates another mutable reference
|
|
let rng = unsafe { &mut *self.rng.get() };
|
|
rng.next_u32()
|
|
}
|
|
|
|
#[inline(always)]
|
|
fn next_u64(&mut self) -> u64 {
|
|
// SAFETY: We must make sure to stop using `rng` before anyone else
|
|
// creates another mutable reference
|
|
let rng = unsafe { &mut *self.rng.get() };
|
|
rng.next_u64()
|
|
}
|
|
|
|
fn fill_bytes(&mut self, dest: &mut [u8]) {
|
|
// SAFETY: We must make sure to stop using `rng` before anyone else
|
|
// creates another mutable reference
|
|
let rng = unsafe { &mut *self.rng.get() };
|
|
rng.fill_bytes(dest)
|
|
}
|
|
|
|
fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
|
|
// SAFETY: We must make sure to stop using `rng` before anyone else
|
|
// creates another mutable reference
|
|
let rng = unsafe { &mut *self.rng.get() };
|
|
rng.try_fill_bytes(dest)
|
|
}
|
|
}
|
|
|
|
impl CryptoRng for ThreadRng {}
|
|
|
|
|
|
#[cfg(test)]
|
|
mod test {
|
|
#[test]
|
|
fn test_thread_rng() {
|
|
use crate::Rng;
|
|
let mut r = crate::thread_rng();
|
|
r.gen::<i32>();
|
|
assert_eq!(r.gen_range(0..1), 0);
|
|
}
|
|
}
|