Trait servo_rand::SeedableRng

pub trait SeedableRng: Sized {
    type Seed: Default + AsMut<[u8]>;

    // Required method
    fn from_seed(seed: Self::Seed) -> Self;

    // Provided methods
    fn seed_from_u64(state: u64) -> Self { ... }
    fn from_rng<R>(rng: R) -> Result<Self, Error>
       where R: RngCore { ... }
    fn from_entropy() -> Self { ... }
}

A random number generator that can be explicitly seeded.

This trait encapsulates the low-level functionality common to all pseudo-random number generators (PRNGs, or algorithmic generators).

Required Associated Types

type Seed: Default + AsMut<[u8]>

Seed type, which is restricted to types mutably-dereferenceable as u8 arrays (we recommend [u8; N] for some N).

It is recommended to seed PRNGs with a seed of at least circa 100 bits, which means an array of [u8; 12] or greater to avoid picking RNGs with partially overlapping periods.

For cryptographic RNG’s a seed of 256 bits is recommended, [u8; 32].

Implementing SeedableRng for RNGs with large seeds

Note that the required traits core::default::Default and core::convert::AsMut<u8> are not implemented for large arrays [u8; N] with N > 32. To be able to implement the traits required by SeedableRng for RNGs with such large seeds, the newtype pattern can be used:

use rand_core::SeedableRng;

const N: usize = 64;
pub struct MyRngSeed(pub [u8; N]);
pub struct MyRng(MyRngSeed);

impl Default for MyRngSeed {
    fn default() -> MyRngSeed {
        MyRngSeed([0; N])
    }
}

impl AsMut<[u8]> for MyRngSeed {
    fn as_mut(&mut self) -> &mut [u8] {
        &mut self.0
    }
}

impl SeedableRng for MyRng {
    type Seed = MyRngSeed;

    fn from_seed(seed: MyRngSeed) -> MyRng {
        MyRng(seed)
    }
}

Required Methods

fn from_seed(seed: Self::Seed) -> Self

Create a new PRNG using the given seed.

PRNG implementations are allowed to assume that bits in the seed are well distributed. That means usually that the number of one and zero bits are roughly equal, and values like 0, 1 and (size - 1) are unlikely. Note that many non-cryptographic PRNGs will show poor quality output if this is not adhered to. If you wish to seed from simple numbers, use seed_from_u64 instead.

All PRNG implementations should be reproducible unless otherwise noted: given a fixed seed, the same sequence of output should be produced on all runs, library versions and architectures (e.g. check endianness). Any “value-breaking” changes to the generator should require bumping at least the minor version and documentation of the change.

It is not required that this function yield the same state as a reference implementation of the PRNG given equivalent seed; if necessary another constructor replicating behaviour from a reference implementation can be added.

PRNG implementations should make sure from_seed never panics. In the case that some special values (like an all zero seed) are not viable seeds it is preferable to map these to alternative constant value(s), for example 0xBAD5EEDu32 or 0x0DDB1A5E5BAD5EEDu64 (“odd biases? bad seed”). This is assuming only a small number of values must be rejected.

Provided Methods

fn seed_from_u64(state: u64) -> Self

Create a new PRNG using a u64 seed.

This is a convenience-wrapper around from_seed to allow construction of any SeedableRng from a simple u64 value. It is designed such that low Hamming Weight numbers like 0 and 1 can be used and should still result in good, independent seeds to the PRNG which is returned.

This is not suitable for cryptography, as should be clear given that the input size is only 64 bits.

Implementations for PRNGs may provide their own implementations of this function, but the default implementation should be good enough for all purposes. Changing the implementation of this function should be considered a value-breaking change.

fn from_rng<R>(rng: R) -> Result<Self, Error>

where R: RngCore,

Create a new PRNG seeded from another Rng.

This may be useful when needing to rapidly seed many PRNGs from a master PRNG, and to allow forking of PRNGs. It may be considered deterministic.

The master PRNG should be at least as high quality as the child PRNGs. When seeding non-cryptographic child PRNGs, we recommend using a different algorithm for the master PRNG (ideally a CSPRNG) to avoid correlations between the child PRNGs. If this is not possible (e.g. forking using small non-crypto PRNGs) ensure that your PRNG has a good mixing function on the output or consider use of a hash function with from_seed.

Note that seeding XorShiftRng from another XorShiftRng provides an extreme example of what can go wrong: the new PRNG will be a clone of the parent.

PRNG implementations are allowed to assume that a good RNG is provided for seeding, and that it is cryptographically secure when appropriate. As of rand 0.7 / rand_core 0.5, implementations overriding this method should ensure the implementation satisfies reproducibility (in prior versions this was not required).

fn from_entropy() -> Self

Creates a new instance of the RNG seeded via getrandom.

This method is the recommended way to construct non-deterministic PRNGs since it is convenient and secure.

In case the overhead of using getrandom to seed many PRNGs is an issue, one may prefer to seed from a local PRNG, e.g. from_rng(thread_rng()).unwrap().

Panics

If getrandom is unable to provide secure entropy this method will panic.

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl SeedableRng for StdRng

type Seed = <ChaCha12Rng as SeedableRng>::Seed

fn from_seed(seed: <StdRng as SeedableRng>::Seed) -> StdRng

fn from_rng<R>(rng: R) -> Result<StdRng, Error>

where R: RngCore,

impl SeedableRng for ChaCha8Core

type Seed = [u8; 32]

fn from_seed(seed: <ChaCha8Core as SeedableRng>::Seed) -> ChaCha8Core

impl SeedableRng for ChaCha8Rng

type Seed = [u8; 32]

fn from_seed(seed: <ChaCha8Rng as SeedableRng>::Seed) -> ChaCha8Rng

impl SeedableRng for ChaCha12Core

type Seed = [u8; 32]

fn from_seed(seed: <ChaCha12Core as SeedableRng>::Seed) -> ChaCha12Core

impl SeedableRng for ChaCha12Rng

type Seed = [u8; 32]

fn from_seed(seed: <ChaCha12Rng as SeedableRng>::Seed) -> ChaCha12Rng

impl SeedableRng for ChaCha20Core

type Seed = [u8; 32]

fn from_seed(seed: <ChaCha20Core as SeedableRng>::Seed) -> ChaCha20Core

impl SeedableRng for ChaCha20Rng

type Seed = [u8; 32]

fn from_seed(seed: <ChaCha20Rng as SeedableRng>::Seed) -> ChaCha20Rng

impl SeedableRng for Isaac64Core

type Seed = [u8; 32]

fn from_seed(seed: <Isaac64Core as SeedableRng>::Seed) -> Isaac64Core

fn seed_from_u64(seed: u64) -> Isaac64Core

fn from_rng<R>(rng: R) -> Result<Isaac64Core, Error>

where R: RngCore,

impl SeedableRng for Isaac64Rng

fn seed_from_u64(seed: u64) -> Isaac64Rng

Create an ISAAC random number generator using an u64 as seed. If seed == 0 this will produce the same stream of random numbers as the reference implementation when used unseeded.

type Seed = <Isaac64Core as SeedableRng>::Seed

fn from_seed(seed: <Isaac64Rng as SeedableRng>::Seed) -> Isaac64Rng

fn from_rng<S>(rng: S) -> Result<Isaac64Rng, Error>

where S: RngCore,

impl SeedableRng for IsaacCore

fn seed_from_u64(seed: u64) -> IsaacCore

Create an ISAAC random number generator using an u64 as seed. If seed == 0 this will produce the same stream of random numbers as the reference implementation when used unseeded.

type Seed = [u8; 32]

fn from_seed(seed: <IsaacCore as SeedableRng>::Seed) -> IsaacCore

fn from_rng<R>(rng: R) -> Result<IsaacCore, Error>

where R: RngCore,

impl SeedableRng for IsaacRng

fn seed_from_u64(seed: u64) -> IsaacRng

Create an ISAAC random number generator using an u64 as seed. If seed == 0 this will produce the same stream of random numbers as the reference implementation when used unseeded.

type Seed = <IsaacCore as SeedableRng>::Seed

fn from_seed(seed: <IsaacRng as SeedableRng>::Seed) -> IsaacRng

fn from_rng<S>(rng: S) -> Result<IsaacRng, Error>

where S: RngCore,

Implementors

impl SeedableRng for ServoRng

type Seed = Seed

impl<R> SeedableRng for BlockRng64<R>

where R: BlockRngCore + SeedableRng,

type Seed = <R as SeedableRng>::Seed

impl<R> SeedableRng for BlockRng<R>

where R: BlockRngCore + SeedableRng,

type Seed = <R as SeedableRng>::Seed