From defeb0cea3fad7c8790686eedd4a35205a401d16 Mon Sep 17 00:00:00 2001 From: Diggory Hardy Date: Thu, 23 May 2024 07:21:07 +0100 Subject: [PATCH] Revise crate doc for rand_pcg, rand_chacha (#1454) * Pub-reexport rand_core from rand_pcg * Add getrandom feature to rand_pcg, rand_chacha --- rand_chacha/Cargo.toml | 4 ++- rand_chacha/src/lib.rs | 71 +++++++++++++++++++++++++++++++++++++++++- rand_pcg/Cargo.toml | 3 ++ rand_pcg/src/lib.rs | 70 ++++++++++++++++++++++++++++++----------- 4 files changed, 127 insertions(+), 21 deletions(-) diff --git a/rand_chacha/Cargo.toml b/rand_chacha/Cargo.toml index 0162599c..981cb7a6 100644 --- a/rand_chacha/Cargo.toml +++ b/rand_chacha/Cargo.toml @@ -16,6 +16,7 @@ edition = "2021" rust-version = "1.61" [package.metadata.docs.rs] +all-features = true rustdoc-args = ["--generate-link-to-definition"] [dependencies] @@ -26,9 +27,10 @@ serde = { version = "1.0", features = ["derive"], optional = true } [dev-dependencies] # Only to test serde1 serde_json = "1.0" +rand_core = { path = "../rand_core", version = "=0.9.0-alpha.1", features = ["getrandom"] } [features] default = ["std"] +getrandom = ["rand_core/getrandom"] std = ["ppv-lite86/std", "rand_core/std"] -simd = [] # deprecated serde1 = ["serde"] diff --git a/rand_chacha/src/lib.rs b/rand_chacha/src/lib.rs index f4b526b8..ba72b1b5 100644 --- a/rand_chacha/src/lib.rs +++ b/rand_chacha/src/lib.rs @@ -6,7 +6,76 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! The ChaCha random number generator. +//! The ChaCha random number generators. +//! +//! These are native Rust implementations of RNGs derived from the +//! [ChaCha stream ciphers] by D J Bernstein. +//! +//! ## Generators +//! +//! This crate provides 8-, 12- and 20-round variants of generators via a "core" +//! implementation (of [`BlockRngCore`]), each with an associated "RNG" type +//! (implementing [`RngCore`]). +//! +//! These generators are all deterministic and portable (see [Reproducibility] +//! in the book), with testing against reference vectors. +//! +//! ## Cryptographic (secure) usage +//! +//! Where secure unpredictable generators are required, it is suggested to use +//! [`ChaCha12Rng`] or [`ChaCha20Rng`] and to seed via +//! [`SeedableRng::from_os_rng`]. +//! +//! See also the [Security] chapter in the rand book. The crate is provided +//! "as is", without any form of guarantee, and without a security audit. +//! +//! ## Seeding (construction) +//! +//! Generators implement the [`SeedableRng`] trait. Any method may be used, +//! but note that `seed_from_u64` is not suitable for usage where security is +//! important. Some suggestions: +//! +//! 1. With a fresh seed, **direct from the OS** (implies a syscall): +//! ``` +//! # use {rand_core::SeedableRng, rand_chacha::ChaCha12Rng}; +//! let rng = ChaCha12Rng::from_os_rng(); +//! # let _: ChaCha12Rng = rng; +//! ``` +//! 2. **From a master generator.** This could be [`rand::thread_rng`] +//! (effectively a fresh seed without the need for a syscall on each usage) +//! or a deterministic generator such as [`ChaCha20Rng`]. +//! Beware that should a weak master generator be used, correlations may be +//! detectable between the outputs of its child generators. +//! +//! See also [Seeding RNGs] in the book. +//! +//! ## Generation +//! +//! Generators implement [`RngCore`], whose methods may be used directly to +//! generate unbounded integer or byte values. +//! ``` +//! use rand_core::{SeedableRng, RngCore}; +//! use rand_chacha::ChaCha12Rng; +//! +//! let mut rng = ChaCha12Rng::from_seed(Default::default()); +//! let x = rng.next_u64(); +//! assert_eq!(x, 0x53f955076a9af49b); +//! ``` +//! +//! It is often more convenient to use the [`rand::Rng`] trait, which provides +//! further functionality. See also the [Random Values] chapter in the book. +//! +//! [ChaCha stream ciphers]: https://cr.yp.to/chacha.html +//! [Reproducibility]: https://rust-random.github.io/book/crate-reprod.html +//! [Seeding RNGs]: https://rust-random.github.io/book/guide-seeding.html +//! [Security]: https://rust-random.github.io/book/guide-rngs.html#security +//! [Random Values]: https://rust-random.github.io/book/guide-values.html +//! [`BlockRngCore`]: rand_core::block::BlockRngCore +//! [`RngCore`]: rand_core::RngCore +//! [`SeedableRng`]: rand_core::SeedableRng +//! [`SeedableRng::from_os_rng`]: rand_core::SeedableRng::from_os_rng +//! [`rand::thread_rng`]: https://docs.rs/rand/latest/rand/fn.thread_rng.html +//! [`rand::Rng`]: https://docs.rs/rand/latest/rand/trait.Rng.html #![doc( html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png", diff --git a/rand_pcg/Cargo.toml b/rand_pcg/Cargo.toml index e80e16b0..30c3026f 100644 --- a/rand_pcg/Cargo.toml +++ b/rand_pcg/Cargo.toml @@ -16,10 +16,12 @@ edition = "2021" rust-version = "1.61" [package.metadata.docs.rs] +all-features = true rustdoc-args = ["--generate-link-to-definition"] [features] serde1 = ["serde"] +getrandom = ["rand_core/getrandom"] [dependencies] rand_core = { path = "../rand_core", version = "=0.9.0-alpha.1" } @@ -30,3 +32,4 @@ serde = { version = "1", features = ["derive"], optional = true } # deps yet, see: https://github.com/rust-lang/cargo/issues/1596 # Versions prior to 1.1.4 had incorrect minimal dependencies. bincode = { version = "1.1.4" } +rand_core = { path = "../rand_core", version = "=0.9.0-alpha.1", features = ["getrandom"] } diff --git a/rand_pcg/src/lib.rs b/rand_pcg/src/lib.rs index 72e68586..7ef5dea2 100644 --- a/rand_pcg/src/lib.rs +++ b/rand_pcg/src/lib.rs @@ -8,48 +8,78 @@ //! The PCG random number generators. //! -//! This is a native Rust implementation of a small selection of PCG generators. +//! This is a native Rust implementation of a small selection of [PCG generators]. //! The primary goal of this crate is simple, minimal, well-tested code; in //! other words it is explicitly not a goal to re-implement all of PCG. //! +//! ## Generators +//! //! This crate provides: //! -//! - `Pcg32` aka `Lcg64Xsh32`, officially known as `pcg32`, a general +//! - [`Pcg32`] aka [`Lcg64Xsh32`], officially known as `pcg32`, a general //! purpose RNG. This is a good choice on both 32-bit and 64-bit CPUs //! (for 32-bit output). -//! - `Pcg64` aka `Lcg128Xsl64`, officially known as `pcg64`, a general +//! - [`Pcg64`] aka [`Lcg128Xsl64`], officially known as `pcg64`, a general //! purpose RNG. This is a good choice on 64-bit CPUs. -//! - `Pcg64Mcg` aka `Mcg128Xsl64`, officially known as `pcg64_fast`, +//! - [`Pcg64Mcg`] aka [`Mcg128Xsl64`], officially known as `pcg64_fast`, //! a general purpose RNG using 128-bit multiplications. This has poor //! performance on 32-bit CPUs but is a good choice on 64-bit CPUs for //! both 32-bit and 64-bit output. //! -//! Both of these use 16 bytes of state and 128-bit seeds, and are considered -//! value-stable (i.e. any change affecting the output given a fixed seed would -//! be considered a breaking change to the crate). +//! These generators are all deterministic and portable (see [Reproducibility] +//! in the book), with testing against reference vectors. //! -//! # Example +//! ## Seeding (construction) //! -//! To initialize a generator, use the [`SeedableRng`][rand_core::SeedableRng] trait: +//! Generators implement the [`SeedableRng`] trait. All methods are suitable for +//! seeding. Some suggestions: //! +//! 1. Seed **from an integer** via `seed_from_u64`. This uses a hash function +//! internally to yield a (typically) good seed from any input. +//! ``` +//! # use {rand_core::SeedableRng, rand_pcg::Pcg64Mcg}; +//! let rng = Pcg64Mcg::seed_from_u64(1); +//! # let _: Pcg64Mcg = rng; +//! ``` +//! 2. With a fresh seed, **direct from the OS** (implies a syscall): +//! ``` +//! # use {rand_core::SeedableRng, rand_pcg::Pcg64Mcg}; +//! let rng = Pcg64Mcg::from_os_rng(); +//! # let _: Pcg64Mcg = rng; +//! ``` +//! 3. **From a master generator.** This could be [`rand::thread_rng`] +//! (effectively a fresh seed without the need for a syscall on each usage) +//! or a deterministic generator such as [`rand_chacha::ChaCha8Rng`]. +//! Beware that should a weak master generator be used, correlations may be +//! detectable between the outputs of its child generators. +//! +//! See also [Seeding RNGs] in the book. +//! +//! ## Generation +//! +//! Generators implement [`RngCore`], whose methods may be used directly to +//! generate unbounded integer or byte values. //! ``` //! use rand_core::{SeedableRng, RngCore}; //! use rand_pcg::Pcg64Mcg; //! //! let mut rng = Pcg64Mcg::seed_from_u64(0); -//! let x: u32 = rng.next_u32(); +//! let x = rng.next_u64(); +//! assert_eq!(x, 0x5603f242407deca2); //! ``` //! -//! The functionality of this crate is implemented using traits from the `rand_core` crate, but you may use the `rand` -//! crate for further functionality to initialize the generator from various sources and to generate random values: +//! It is often more convenient to use the [`rand::Rng`] trait, which provides +//! further functionality. See also the [Random Values] chapter in the book. //! -//! ```ignore -//! use rand::{Rng, SeedableRng}; -//! use rand_pcg::Pcg64Mcg; -//! -//! let mut rng = Pcg64Mcg::from_os_rng(); -//! let x: f64 = rng.gen(); -//! ``` +//! [PCG generators]: https://www.pcg-random.org/ +//! [Reproducibility]: https://rust-random.github.io/book/crate-reprod.html +//! [Seeding RNGs]: https://rust-random.github.io/book/guide-seeding.html +//! [Random Values]: https://rust-random.github.io/book/guide-values.html +//! [`RngCore`]: rand_core::RngCore +//! [`SeedableRng`]: rand_core::SeedableRng +//! [`rand::thread_rng`]: https://docs.rs/rand/latest/rand/fn.thread_rng.html +//! [`rand::Rng`]: https://docs.rs/rand/latest/rand/trait.Rng.html +//! [`rand_chacha::ChaCha8Rng`]: https://docs.rs/rand_chacha/latest/rand_chacha/struct.ChaCha8Rng.html #![doc( html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png", @@ -65,6 +95,8 @@ mod pcg128; mod pcg128cm; mod pcg64; +pub use rand_core; + pub use self::pcg128::{Lcg128Xsl64, Mcg128Xsl64, Pcg64, Pcg64Mcg}; pub use self::pcg128cm::{Lcg128CmDxsm64, Pcg64Dxsm}; pub use self::pcg64::{Lcg64Xsh32, Pcg32};