Crate ya_rand

YA-Rand: Yet Another Rand

Simple and fast pseudo/crypto random number generation.

But why?

Because rand is very cool and extremely powerful, but kind of an enormous fucking pain in the ass to use, and it’s far too large and involved for someone who just needs to flip a coin once every few minutes. But if you’re doing some crazy black magic computational sorcery, it almost certainly has something you can use to complete your spell.

Other crates, like fastrand, tinyrand, or oorandom, fall somewhere between “I’m not sure I trust the backing RNG” (state size is too small or algorithm is iffy) and “this API is literally just rand but far less powerful”. I wanted something easy, but also fast and statistically robust.

So here we are.

Windows 10 users on Rust 1.71 or newer

It is highly recommended that you add RUSTFLAGS=--cfg windows_raw_dylib to your path. Currently, the getrandom crate that’s used to seed RNGs behind the scenes defers its operation to windows-targets, which by default statically links to a 5-12MB lib. Adding the above cfg flag tells it to instead use the raw-dylib feature, which was stabilized in Rust 1.71. This turns windows-targets into a small macro-only library, which improves compile times and decreases binary size for both debug and release builds.

Usage

Glob import the contents of the library and use new_rng to create new RNGs wherever you need them. Then call whatever method you require on those instances. All methods available are directly accessible through any generator instance via the dot operator, and are named in a way that should make it easy to quickly identify what you need. See below for a few examples.

If you need cryptographic security, enable the secure library feature and use new_rng_secure instead.

“How do I access the thread-local RNG?” There isn’t one, and unless Rust improves the performance and ergonomics of the TLS implementation, there probably won’t ever be. Create a local instance when and where you need one and use it while you need it. If you need an RNG to stick around for a while, passing it between functions or storing it in structs is a perfectly valid solution.

use ya_rand::*;

// **Correct** instantiation is very easy.
// This seeds the RNG using operating system entropy,
// so you never have to worry about the quality of the
// initial state of RNG instances.
let mut rng = new_rng();

// Generate a random number with a given upper bound.
let max: u64 = 420;
let val = rng.bound(max);
assert!(val < max);

// Generate a random number in a given range.
let min: i64 = -69;
let max: i64 = 69;
let val = rng.range(min, max);
assert!(min <= val && val < max);

// Generate a random floating point value.
let val = rng.f64();
assert!(0.0 <= val && val < 1.0);

// Generate a random ascii digit: '0'..='9' as a char.
let digit = rng.ascii_digit();
assert!(digit.is_ascii_digit());

Features

• std - Enabled by default, but can be disabled for compatibility with no_std environments. Enables normal/exponential distributions and error type conversions for getrandom. Also enables generation of random String values when enabled alongside the secure feature.
• inline - Marks each YARandGenerator::u64 implementation with #[inline]. Should generally increase runtime performance at the cost of binary size and compile time, especially for SecureRng. You’ll have to test your specific use case to determine if this feature is worth it for you, but generally speaking all the RNGs provided are plenty fast without additional inlining.
• secure - Enables infrastructure for cryptographically secure random number generation via the chacha20 crate. Moderately increases compile time and binary size.

Details

This crate uses the xoshiro family of pseudo-random number generators. These generators are very fast, of very high statistical quality, and small. They aren’t cryptographically secure, but most users don’t need their RNG to be secure, they just need it to be random and fast. The default generator is xoshiro256++, which should provide a large enough period for most users. The xoshiro512++ generator is also provided in case you need a longer period.

All generators output a distinct u64 value on each call, and the various methods used for transforming those outputs into more usable forms are all high-quality and well-understood. Placing an upper bound on these values uses Lemire’s method. Both inclusive bounding and range-based bounding are applications of this method, with a few intermediary steps to adjust the bound and apply shifts as needed. This approach is unbiased and quite fast, but for very large bounds performance might degrade slightly, since the algorithm may need to sample the underlying RNG multiple times to get an unbiased result. But this is just a byproduct of how the underlying algorithm works, and isn’t something you should ever be worried about when using the aforementioned methods, since these resamples are few and far between. If your bound happens to be a power of 2, always use YARandGenerator::bits, since it’s nothing more than a bit-shift of the original u64 provided by the RNG, and will always be as fast as possible.

Floating point values (besides the normal and exponential distributions) are uniformly distributed, with all the possible outputs being equidistant within the given interval. They are not maximally dense; if that’s something you need, you’ll have to generate those values yourself. This approach is very fast, and endorsed by both Lemire and Vigna (the author of the RNGs used in this crate). The normal distribution implementation uses the Marsaglia polar method, returning pairs of independently sampled f64 values. Exponential variates are generated using this approach.

Security

If you’re in the market for secure random number generation, you’ll want to enable the secure feature, which provides SecureRng and the SecureYARandGenerator trait. It functions identically to the other provided RNGs, but with added functionality that isn’t safe to use on pseudo RNGs. The current implementation is ChaCha with 8 rounds via the chacha20 crate. I reserve the right to change this at any time to another RNG which is at least as secure, without changing the API or bumping the major/minor version. Why only 8 rounds? Because people who are very passionate about cryptography are convinced that’s enough, and I have zero reason to doubt them, nor any capacity to prove them wrong. See page 14 of the Too Much Crypto paper if you’re interested in the justification.

The security promises made to the user are identical to those made by ChaCha as an algorithm. It is up to you to determine if those guarantees meet the demands of your use case.

Safety

Generators are seeded using entropy from the underlying OS, and have the potential to fail during creation. But in practice this is extraordinarily unlikely, and isn’t something the end-user should ever worry about. Modern Windows versions (10 and newer) have a crypto subsystem that will never fail during runtime, and rustc can trivially remove the failure branch when compiling binaries for those systems.

Modules

ya_rand_encoding

Structs

SecureRng

A cryptographically secure random number generator.

Xoshiro256pp

Rust implementation of the xoshiro256++ PRNG. This generator is fast, high-quality, and small, but not cryptographically secure.

Xoshiro512pp

Rust implementation of the xoshiro512++ PRNG. This generator is fast, high-quality, and small, but not cryptographically secure.

Traits

SecureYARandGenerator

Trait for RNGs that are known to provide streams of cryptographically secure data.

SeedableYARandGenerator

Trait for RNGs that can be created from a user-provided seed.

YARandGenerator

Base trait that all RNGs must implement.

Functions

new_rng

The recommended way to create new PRNG instances.

new_rng_secure

The recommended way to create new CRNG instances.

Type Aliases

ShiroRng

The recommended generator for all non-cryptographic purposes.