# [−] [src] Module rand::rngs

Random number generators and adapters

## Background: Random number generators (RNGs)

Computers cannot produce random numbers from nowhere. We classify random number generators as follows:

- "True" random number generators (TRNGs) use hard-to-predict data sources (e.g. the high-resolution parts of event timings and sensor jitter) to harvest random bit-sequences, apply algorithms to remove bias and estimate available entropy, then combine these bits into a byte-sequence or an entropy pool. This job is usually done by the operating system or a hardware generator (HRNG).
- "Pseudo"-random number generators (PRNGs) use algorithms to transform a seed into a sequence of pseudo-random numbers. These generators can be fast and produce well-distributed unpredictable random numbers (or not). They are usually deterministic: given algorithm and seed, the output sequence can be reproduced. They have finite period and eventually loop; with many algorithms this period is fixed and can be proven sufficiently long, while others are chaotic and the period depends on the seed.
- "Cryptographically secure" pseudo-random number generators (CSPRNGs) are the sub-set of PRNGs which are secure. Security of the generator relies both on hiding the internal state and using a strong algorithm.

## Traits and functionality

All RNGs implement the [`RngCore`] trait, as a consequence of which the [`Rng`] extension trait is automatically implemented. Secure RNGs may additionally implement the [`CryptoRng`] trait.

All PRNGs require a seed to produce their random number sequence. The [`SeedableRng`] trait provides three ways of constructing PRNGs:

- `from_seed` accepts a type specific to the PRNG
- `from_rng` allows a PRNG to be seeded from any other RNG
- `seed_from_u64` allows any PRNG to be seeded from a `u64` insecurely
- `from_entropy` securely seeds a PRNG from fresh entropy

Use the [`rand_core`] crate when implementing your own RNGs.

## Our generators

This crate provides several random number generators:

- `OsRng` is an interface to the operating system's random number source. Typically the operating system uses a CSPRNG with entropy provided by a TRNG and some type of on-going re-seeding.
- `ThreadRng`, provided by the [`thread_rng`] function, is a handle to a thread-local CSPRNG with periodic seeding from `OsRng`. Because this is local, it is typically much faster than `OsRng`. It should be secure, though the paranoid may prefer `OsRng`.
- `StdRng` is a CSPRNG chosen for good performance and trust of security (based on reviews, maturity and usage). The current algorithm is ChaCha20, which is well established and rigorously analysed. `StdRng` provides the algorithm used by `ThreadRng` but without periodic reseeding.
- `SmallRng` is an insecure PRNG designed to be fast, simple, require little memory, and have good output quality.

The algorithms selected for `StdRng` and `SmallRng` may change in any release and may be platform-dependent, therefore they should be considered not reproducible.

## Additional generators

TRNGs: The `rdrand` crate provides an interface to the RDRAND and RDSEED instructions available in modern Intel and AMD CPUs. The `rand_jitter` crate provides a user-space implementation of entropy harvesting from CPU timer jitter, but is very slow and has security issues.

PRNGs: Several companion crates are available, providing individual or families of PRNG algorithms. These provide the implementations behind `StdRng` and `SmallRng` but can also be used directly, indeed should be used directly when reproducibility matters. Some suggestions are: `rand_chacha`, `rand_pcg`, `rand_xoshiro`. A full list can be found by searching for crates with the `rng` tag.

## Modules

adapter | Wrappers / adapters forming RNGs
mock | Mock random number generator

## Structs

EntropyRng | Deprecated An interface returning random data from external source(s), provided specifically for securely seeding algorithmic generators (PRNGs).
OsRng | A random number generator that retrieves randomness from from the operating system.
StdRng | The standard RNG. The PRNG algorithm in `StdRng` is chosen to be efficient on the current platform, to be statistically strong and unpredictable (meaning a cryptographically secure PRNG).
ThreadRng | The type returned by [`thread_rng`], essentially just a reference to the PRNG in thread-local memory.

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)