Struct rand::ThreadRng

Overview

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 OsRng and periodically thereafter (see (ReseedingRng documentation). Limitation: there is no automatic reseeding on process fork (see below).
  • A rigorusly 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 OsRng.

Fork

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.

Methods

fn reseed(self) -> Result

Immediately reseed the generator

This discards any remaining random data in the cache.

fn random<u64>(self) -> u64

Return a random u64 value via a standard uniform distribution.

Example

use rand::ThreadRng;

let rng = rand::rng();
let x = rng.random::<u64>();
println!("{x}");
fn random<i64>(self) -> i64

Return a random i64 value via a standard uniform distribution.

Example

use rand::ThreadRng;

let rng = rand::rng();
let x = rng.random::<i64>();
println!("{x}");
fn random<char>(self) -> char

Return a random char value via a standard uniform distribution.

Example

use rand::ThreadRng;

let rng = rand::rng();
let x = rng.random::<char>();
println!("{x}");
fn random<bool>(self) -> bool

Return a random bool value via a standard uniform distribution.

Example

use rand::ThreadRng;

let rng = rand::rng();
let x = rng.random::<bool>();
println!("{x}");
fn random_range<u64>(self, range: any) -> u64

Return a random u64 value via a standard uniform constrained with a range.

Example

use rand::ThreadRng;

let rng = rand::rng();
let x = rng.random_range::<u64>(0 .. 100);
println!("{x}");
fn random_range<i64>(self, range: any) -> i64

Return a random i64 value via a standard uniform constrained with a range.

Example

use rand::ThreadRng;

let rng = rand::rng();
let x = rng.random_range::<i64>(- 100 .. 100);
println!("{x}");
fn random_range<char>(self, range: any) -> char

Return a random char value via a standard uniform constrained with a range.

Example

use rand::ThreadRng;

let rng = rand::rng();
let x = rng.random_range::<char>('a' .. 'z');
println!("{x}");