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

+