Expand description
A pseudo random number generator using the Romu algorithm.
This pseudo random number generator (PRNG) is not intended for cryptographic purposes. This crate only implements the 64-bit “RomuTrio” generator, since it’s the recommended generator by the original author.
§Non-linear random number generator
Romu is a non-linear random number generator. That means that the period is probabilistic and is based on the seed. The bigger the needed period is, the higher the chance it is that the actual period is “too small”.
Following formula is given by the author:
P(|cycle contains x<= 2^k|) = 2^k-s+7
k is size of random numbers needed + 1.
s is the state size.
Example chances for getting a “too small” period:
- When 2^62 * 64 bit numbers are needed (32 EiB) -> 2^-122 chance
- When 2^39 * 64 bit numbers are needed (4 TiB) -> 2^-146 chance
- When 2^36 * 64 bit numbers are needed (512 GiB) -> 2^-149 chance
You can read more about the theory behind Romu in the official paper and it’s unique selling points on the official website of the original author.
§Seeding
When the user calls the new()
or default()
functions of a generator, the implementation
tries to use the best available randomness source to seed the generator (in the following order):
- The crate
getrandom
to seed from a high quality randomness source of the operating system. The featuregetrandom
must be activated for this. - Use the functionality of the standard library to create a low quality randomness seed (using
the current time, the thread ID and a memory address).
The feature
std
must be activated for this. - Use a memory address as a very low randomness seed. If Address Space Layout Randomization (ASLR) is supported by the operating system, this should be a pretty “random” value.
It is highly recommended using the no_std
compatible getrandom
feature to get high quality
randomness seeds.
The user can always create / update a generator with a user provided seed value.
If the tls
feature is used, the user should call the seed()
function to seed the TLS
before creating the first random numbers, since the TLS instance is instantiated with a fixed
value.
§SIMD
The crate currently provides three generators that tries to use auto vectorization to speed up the generation of large amounts of random numbers.
Rng128
- This should be used when the processor has access to 128-bit SIMD (SSE2 / NEON).Rng256
- This should be used when the processor has access to 256-bit SIMD (AVX2).Rng512
- This should be used when the processor has access to 512-bit SIMD (AVX512).
The nightly only feature unstable_simd
uses the core::simd
create to implement the SIMD.
Users should test the available generators for their workload and verify if they can accelerate
them using the SIMD functionality.
§Features
The crate is no_std
compatible.
std
- Ifgetrandom
is not used or returns an error, the generator will use the thread name and the current instance time to create a seed value. Enabled by default.tls
- Create static functions to use a thread local version of the generator. Enabled by default.getrandom
- Uses thegetrandom
crate to create a seed of high randomness. Enabled by default.unstable_tls
- Uses the unstablethread_local
feature of Rust nightly. Improves the call times to the thread local functions greatly.unstable_simd
- Uses the unstablecore::simd
crate of Rust nightly to provide special SIMD versions of the generator which can be used to create large amount of random data fast.
Structs§
- Implements
RomuTrio
. - Implements
RomuTrio
with 128-bit width. - Implements
RomuTrio
with 256-bit width. - Implements
RomuTrio
with 512-bit width.
Enums§
- Defines which source the seed was created from.
Functions§
- bool
tls
Generates a random bool value. - f32
tls
Generates a random f32 value in range (0..1). - f64
tls
Generates a random f64 value in range (0..1). - fill_bytes
tls
Fills a mutable[u8]
slice with random values. - i8
tls
Generates a random i8 value. - i16
tls
Generates a random i16 value. - i32
tls
Generates a random i32 value. - i64
tls
Generates a random i64 value. - isize
tls
Generates a random isize value. - mix
tls
Mixes the state, which should improve the quality of the random numbers. - mod_u8
tls
Generates a random u8 value in range (0..n). - mod_u16
tls
Generates a random u16 value in range (0..n). - mod_u32
tls
Generates a random u32 value in range (0..n). - mod_u64
tls
Generates a random u64 value in range (0..n). - mod_usize
tls
Generates a random usize value in range (0..n). - range_i8
tls
Generates a random i8 value in the given range. - range_i16
tls
Generates a random i16 value in the given range. - range_i32
tls
Generates a random i32 value in the given range. - range_i64
tls
Generates a random i64 value in the given range. - range_isize
tls
Generates a random isize value in the given range. - range_u8
tls
Generates a random u8 value in the given range. - range_u16
tls
Generates a random u16 value in the given range. - range_u32
tls
Generates a random u32 value in the given range. - range_u64
tls
Generates a random u64 value in the given range. - range_usize
tls
Generates a random usize value in the given range. - seed
tls
Seeds the thread local instance from the best available randomness source. - seed_source
tls
Shows which source was used to acquire the seed for the thread local instance. - Seeds the thread local instance with the given 64-bit seed.
- Seeds the thread local instance with the given 192-bit seed.
- shuffle
tls
Randomly shuffles a slice. - u8
tls
Generates a random u8 value. - u16
tls
Generates a random u16 value. - u32
tls
Generates a random u32 value. - u64
tls
Generates a random u64 value. - usize
tls
Generates a random usize value.