|
|
---
|
|
|
source: tests/output.rs
|
|
|
expression: "get_stdout(&[item])"
|
|
|
---
|
|
|
rand_core Trait rand_core::SeedableRng rusty-man
|
|
|
|
|
|
SYNOPSIS
|
|
|
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: RngCore>(rng: R) -> Result<Self, Error> { ... }
|
|
|
fn from_entropy() -> Self { ... }
|
|
|
}
|
|
|
|
|
|
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).
|
|
|
|
|
|
ASSOCIATED TYPES
|
|
|
Seed
|
|
|
type Seed: Sized + Default + AsMut<[u8]>
|
|
|
|
|
|
Seed type, which is restricted to types mutably-dereferencable 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)
|
|
|
}
|
|
|
}
|
|
|
|
|
|
METHODS
|
|
|
Required Methods
|
|
|
from_seed
|
|
|
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
|
|
|
seed_from_u64
|
|
|
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.
|
|
|
|
|
|
from_rng
|
|
|
fn from_rng<R: RngCore>(rng: R) -> Result<Self, Error>
|
|
|
|
|
|
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).
|
|
|
|
|
|
from_entropy
|
|
|
fn from_entropy() -> Self
|
|
|
|
|
|
Creates a new instance of the RNG seeded via [`getrandom`][1].
|
|
|
|
|
|
This method is the recommended way to construct non-deterministic PRNGs since it is
|
|
|
convenient and secure.
|
|
|
|
|
|
In case the overhead of using [`getrandom`][2] 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`][3] is unable to provide secure entropy this method will panic.
|
|
|
|
|
|
[1] https://docs.rs/getrandom
|
|
|
[2] https://docs.rs/getrandom
|
|
|
[3] https://docs.rs/getrandom
|
|
|
|
|
|
|