Struct `ThreadRng`

pub struct ThreadRng { /* private fields */ }

A reference to the thread-local generator

This type is a reference to a lazily-initialized thread-local generator. An instance can be obtained via [rand::rng()][crate::rng()] or via [ThreadRng::default()]. The handle cannot be passed between threads (is not Send or Sync).

Security

Security must be considered relative to a threat model and validation requirements. The Rand project can provide no guarantee of fitness for purpose. The design criteria for ThreadRng are as follows:

Automatic seeding via SysRng and after every 64 kB of output. Limitation: there is no automatic reseeding on process fork (see below).
A rigorously analyzed, unpredictable (cryptographic) pseudo-random generator (see the book on security). The currently selected algorithm is ChaCha (12-rounds). See also StdRng documentation.
Not to leak internal state through Debug or serialization implementations.
No further protections exist to in-memory state. In particular, the implementation is not required to zero memory on exit (of the process or thread). (This may change in the future.)
Be fast enough for general-purpose usage. Note in particular that ThreadRng is designed to be a "fast, reasonably secure generator" (where "reasonably secure" implies the above criteria).

We leave it to the user to determine whether this generator meets their security requirements. For an alternative, see SysRng.

Forks and interrupts

ThreadRng is not automatically reseeded on fork. It is recommended to explicitly call ThreadRng::reseed immediately after a fork, for example:

fn do_fork() {
    let pid = unsafe { libc::fork() };
    if pid == 0 {
        // Reseed ThreadRng in child processes:
        rand::rng().reseed();
    }
}

Methods on ThreadRng are not reentrant-safe and thus should not be called from an interrupt (e.g. a fork handler) unless it can be guaranteed that no other method on the same ThreadRng is currently executing.

Panics

Implementations of TryRng and Rng panic in case of SysRng failure during reseeding (highly unlikely).

Implementations

`impl ThreadRng`

fn reseed(&mut self) -> Result<(), SysError>

Immediately reseed the generator

This discards any remaining random data in the cache.

Trait Implementations

`impl Clone for ThreadRng`

fn clone(&self) -> ThreadRng

`impl Debug for ThreadRng`

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

`impl Default for ThreadRng`

fn default() -> ThreadRng

`impl TryCryptoRng for ThreadRng`

`impl TryRng for ThreadRng`

type Error = Infallible;
fn try_next_u32(&mut self) -> Result<u32, Infallible>
fn try_next_u64(&mut self) -> Result<u64, Infallible>
fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Infallible>

Auto Trait Implementations

`impl !RefUnwindSafe for ThreadRng`

`impl !Send for ThreadRng`

`impl !Sync for ThreadRng`

`impl !UnwindSafe for ThreadRng`

`impl Freeze for ThreadRng`

`impl Unpin for ThreadRng`

`impl UnsafeUnpin for ThreadRng`

Blanket Implementations

`impl<R> CryptoRng for ThreadRng where R: TryCryptoRng<Error = Infallible> + ?Sized,`

`impl<R> Rng for ThreadRng where R: TryRng<Error = Infallible> + ?Sized,`

fn next_u32(&mut self) -> u32
fn next_u64(&mut self) -> u64
fn fill_bytes(&mut self, dst: &mut [u8])

`impl<R> RngCore for ThreadRng where R: Rng,`

`impl<R> RngExt for ThreadRng where R: Rng + ?Sized,`

`impl<R> TryRngCore for ThreadRng where R: TryRng,`

type Error = <R as TryRng>::Error;

`impl<T> Any for ThreadRng where T: 'static + ?Sized,`

fn type_id(&self) -> TypeId

`impl<T> Borrow<T> for ThreadRng where T: ?Sized,`

fn borrow(&self) -> &T

`impl<T> BorrowMut<T> for ThreadRng where T: ?Sized,`

fn borrow_mut(&mut self) -> &mut T

`impl<T> CloneToUninit for ThreadRng where T: Clone,`

unsafe fn clone_to_uninit(&self, dest: *mut u8)

`impl<T> From<T> for ThreadRng`

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T> ToOwned for ThreadRng where T: Clone,`

type Owned = T;
fn to_owned(&self) -> T
fn clone_into(&self, target: &mut T)

`impl<T, U> Into<U> for ThreadRng where U: From<T>,`

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

`impl<T, U> TryFrom<U> for ThreadRng where U: Into<T>,`

type Error = Infallible;
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

`impl<T, U> TryInto<U> for ThreadRng where U: TryFrom<T>,`

type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>