Trait rand::SeedableRng

source · [−]

pub trait SeedableRng: Sized {
-    type Seed: Sized + Default + AsMut<[u8]>;
-
-    fn from_seed(seed: Self::Seed) -> Self;
-
-    fn seed_from_u64(state: u64) -> Self { ... }
-    fn from_rng<R>(rng: R) -> Result<Self, Error>
    where
        R: RngCore,
-    { ... }
-    fn from_entropy() -> Self { ... }
-}

Expand description

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

source

type Seed: Sized + 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

source

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

source

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.

-

source

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).

-

source

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().

-