Merge pull request #98 from rust-random/remove-rand_chacha

Prefer RNGs from `rand` over RNGs from other crates

Author: vks

src/contrib-doc.md

@@ -46,37 +46,6 @@ The [rust-random/getrandom](https://github.com/rust-random/getrandom)
 repository contains only a single crate, hence a simple `cargo doc` will
 suffice.
 
-### Cross-crate links
-
-When referring to another crate, we prefer linking to the crate page on
-crates.io since (a) this includes the README documenting the purpose of the
-crate and (b) this links directly to both the repository and the API
-documentation. Example:
-
-```rust,noplayground
-// Link to the crate page:
-//! [`rand_chacha`]: https://crates.io/crates/rand_chacha
-```
-
-When referring to an item from within another crate,
-
-1.  if that item is accessible via a crate dependency (even if not via the
-    public API), use the Rust item path
-2.  otherwise, use an absolute link to docs.rs
-
-Examples:
-
-```rust,noplayground
-//! We depend on rand_core, therefore can use the Rust path:
-//! [`BlockRngCore`]: rand_core::block::BlockRngCore
-
-//! rand_chacha is not a dependency, but is within the same repository:
-//! [`ChaCha20Rng`]: ../../rand_chacha/struct.ChaCha20Rng.html
-
-//! Link directly to docs.rs, with major & minor but no patch version:
-//! [`getrandom`]: https://docs.rs/getrandom/0.1/getrandom/fn.getrandom.html
-```
-
 ## Auxiliary documentation
 
 ### README files

src/contrib-scope.md

@@ -58,7 +58,7 @@ following reasons:
 -   to provide a few high-quality alternative generators
 -   historical usage
 
-These are implemented within "family" crates, e.g. `rand_chacha`, `rand_pcg`,
+These are implemented within "family" crates, e.g. `chacha20`, `rand_pcg`,
 `rand_xoshiro`.
 
 We have received several requests to adopt new algorithms into the library; when

src/crate-features.md

@@ -9,7 +9,7 @@ Release versions of `Cargo.toml` can be viewed on `docs.rs`:
 -   <https://docs.rs/crate/rand/latest/source/Cargo.toml.orig>
 -   <https://docs.rs/crate/rand_core/latest/source/Cargo.toml.orig>
 -   <https://docs.rs/crate/rand_distr/latest/source/Cargo.toml.orig>
--   <https://docs.rs/crate/rand_chacha/latest/source/Cargo.toml.orig>
+-   <https://docs.rs/crate/chacha20/latest/source/Cargo.toml.orig>
 -   <https://docs.rs/crate/rand_xoshiro/latest/source/Cargo.toml.orig>
 -   <https://docs.rs/crate/rand_pcg/latest/source/Cargo.toml.orig>
 

src/crates.md

@@ -1,11 +1,19 @@
 # The crate family
 
 <pre><code class="language-plain">                                           ┌ <a href="https://docs.rs/statrs/">statrs</a>
-<a href="https://docs.rs/getrandom/">getrandom</a> ┐                                ├ <a href="https://docs.rs/rand_distr/">rand_distr</a>
-          └ <a href="https://docs.rs/rand_core/">rand_core</a> ┬─────────────┬ <a href="https://docs.rs/rand/">rand</a> ┘
-                      ├ <a href="https://docs.rs/rand_chacha/">rand_chacha</a> ┘
-                      ├ <a href="https://docs.rs/rand_pcg/">rand_pcg</a>
-                      └ [other RNG crates]
+                                           ├ <a href="https://docs.rs/rand_distr/">rand_distr</a>
+          <a href="https://docs.rs/rand_core/">rand_core</a> ┬───────────────┬ <a href="https://docs.rs/rand/">rand</a> ┘
+                    ├ <a href="https://docs.rs/chacha20/">chacha20</a> ─────┤
+                    ├ <a href="https://docs.rs/getrandom/">getrandom</a> ────┘
+                    ├ <a href="https://docs.rs/rand_chacha/">rand_chacha</a>
+                    ├ <a href="https://docs.rs/rand_hc/">rand_hc</a>
+                    ├ <a href="https://docs.rs/rand_isaac/">rand_isaac</a>
+                    ├ <a href="https://docs.rs/rand_jitter/">rand_jitter</a>
+                    ├ <a href="https://docs.rs/rand_pcg/">rand_pcg</a>
+                    ├ <a href="https://docs.rs/rand_sfc/">rand_sfc</a>
+                    ├ <a href="https://docs.rs/rand_seeder/">rand_seeder</a>
+                    ├ <a href="https://docs.rs/rand_xorshift/">rand_xorshift</a>
+                    └ <a href="https://docs.rs/rand_xoshiro/">rand_xoshiro</a>
 </code></pre>
 
 ## Interfaces
@@ -20,15 +28,23 @@ random-number sources.
 The following crates implement pseudo-random number generators
 (see [Our RNGs](guide-rngs.md)):
 
--   [`rand_chacha`] provides generators using the ChaCha cipher
+-   [`chacha20`] provides generators using the ChaCha cipher
+    (used internally by [`rand`] via the `chacha` feature)
+-   [`rand_chacha`] also provides ChaCha-cipher generators
+    (predecessor of `chacha20` for this purpose; kept for compatibility)
 -   [`rand_hc`] implements a generator using the HC-128 cipher
 -   [`rand_isaac`] implements the ISAAC generators
 -   [`rand_pcg`] implements a small selection of PCG generators
--   [`rand_xoshiro`] implements the SplitMix and Xoshiro generators
+-   [`rand_sfc`] implements the SFC (Small Fast Counter) generators
 -   [`rand_xorshift`] implements the basic Xorshift generator
+-   [`rand_xoshiro`] implements the SplitMix and Xoshiro generators
 
 Exceptionally, [`SmallRng`] is implemented directly in [`rand`].
 
+In addition, [`rand_jitter`] provides a jitter-based entropy source, and
+[`rand_seeder`] derives seeds from arbitrary hashable data (used as a building
+block in [Seeding RNGs](guide-seeding.md)).
+
 ## rand (main crate)
 
 The [`rand`] crate is designed for easy usage of common random-number
@@ -59,13 +75,17 @@ number distributions: uniform and weighted sampling. For everything else,
 [`rand_distr`]: https://docs.rs/rand_distr/
 [`statrs`]: https://docs.rs/statrs/
 [`getrandom`]: https://docs.rs/getrandom/
-[`rand_chacha`]: https://docs.rs/rand_chacha/
+[`chacha20`]: https://docs.rs/chacha20/
 [`rand_pcg`]: https://docs.rs/rand_pcg/
 [`rand_xoshiro`]: https://docs.rs/rand_xoshiro/
 [`log`]: https://docs.rs/log/
 [`serde`]: https://serde.rs/
+[`rand_chacha`]: https://docs.rs/rand_chacha/
 [`rand_hc`]: https://docs.rs/rand_hc/
 [`rand_isaac`]: https://docs.rs/rand_isaac/
+[`rand_jitter`]: https://docs.rs/rand_jitter/
+[`rand_sfc`]: https://docs.rs/rand_sfc/
+[`rand_seeder`]: https://docs.rs/rand_seeder/
 [`rand_xorshift`]: https://docs.rs/rand_xorshift/
 
 [`RngCore`]: https://docs.rs/rand_core/latest/rand_core/trait.RngCore.html

src/guide-parallel.md

@@ -25,7 +25,7 @@ a unique stream on each.
 
 Which RNG families support multiple streams?
 
--   [ChaCha](https://docs.rs/rand_chacha/latest/rand_chacha/): the ChaCha RNGs
+-   [ChaCha](https://docs.rs/rand/latest/rand/rngs/struct.ChaCha20Rng.html): the ChaCha RNGs
     support 256-bit seed, 64-bit stream and 64-bit counter (per 16-word block),
     thus supporting 2<sup>64</sup> streams of 2<sup>68</sup> words each.
 -   [Hc128](https://docs.rs/rand_hc/latest/rand_hc/) is a cryptographic RNG
@@ -145,4 +145,4 @@ fn main() {
 
 [`rng()`]: https://docs.rs/rand/latest/rand/fn.rng.html
 [`map_init`]: https://docs.rs/rayon/latest/rayon/iter/trait.ParallelIterator.html#method.map_init
-[`ChaCha8Rng::set_stream`]: https://docs.rs/rand_chacha/latest/rand_chacha/struct.ChaCha8Rng.html#method.set_stream
+[`ChaCha8Rng::set_stream`]: https://docs.rs/rand/latest/rand/rngs/struct.ChaCha8Rng.html#method.set_stream

src/guide-rngs.md

@@ -39,19 +39,19 @@ You may wish to refer to the [pcg-random] and [xoshiro] websites.
 
 | name | full name | performance | memory | quality | period | features |
 |------|-----------|-------------|--------|---------|--------|----------|
-| [`SmallRng`] | (unspecified) | 7 GB/s | 16 bytes | ★★★☆☆ | ≥ `u32` * 2<sup>64</sup> | not portable |
-| [`Pcg32`] | PCG XSH RR 64/32 (LCG) | 3 GB/s | 16 bytes | ★★★☆☆ | `u32` * 2<sup>64</sup> | — |
-| [`Pcg64`] | PCG XSL 128/64 (LCG) | 4 GB/s | 32 bytes | ★★★☆☆ | `u64` * 2<sup>128</sup> | — |
-| [`Pcg64Mcg`] | PCG XSL 128/64 (MCG) | 7 GB/s | 16 bytes | ★★★☆☆ | `u64` * 2<sup>126</sup> | — |
-| [`XorShiftRng`] | Xorshift 32/128 | 5 GB/s | 16 bytes | ★☆☆☆☆ | `u32` * 2<sup>128</sup> - 1 | — |
-| [`Xoshiro256PlusPlus`] | Xoshiro256++ | 7 GB/s | 32 bytes | ★★★☆☆ | `u64` * 2<sup>256</sup> - 1 | jump-ahead |
-| [`Xoshiro256Plus`] | Xoshiro256+ | 8 GB/s | 32 bytes | ★★☆☆☆ | `u64` * 2<sup>256</sup> - 1 | jump-ahead |
-| [`SplitMix64`] | splitmix64 | 8 GB/s | 8 bytes | ★☆☆☆☆ | `u64` * 2<sup>64</sup> | — |
-| [`StepRng`] | counter | 51 GB/s | 16 bytes | ☆☆☆☆☆ | `u64` * 2<sup>64</sup> | — |
-
-Here, performance is measured roughly for `u64` outputs on a 3.4GHz Haswell CPU
-(note that this will vary significantly by application; in general cryptographic
-RNGs do better with byte sequence output). Quality ratings are
+| [`SmallRng`] | (unspecified) | 11 GB/s | 16 bytes | ★★★☆☆ | ≥ `u32` * 2<sup>64</sup> | not portable |
+| [`Pcg32`] | PCG XSH RR 64/32 (LCG) | 5 GB/s | 16 bytes | ★★★☆☆ | `u32` * 2<sup>64</sup> | — |
+| [`Pcg64`] | PCG XSL 128/64 (LCG) | 7 GB/s | 32 bytes | ★★★☆☆ | `u64` * 2<sup>128</sup> | — |
+| [`Pcg64Mcg`] | PCG XSL 128/64 (MCG) | 8 GB/s | 16 bytes | ★★★☆☆ | `u64` * 2<sup>126</sup> | — |
+| [`XorShiftRng`] | Xorshift 32/128 | 7 GB/s | 16 bytes | ★☆☆☆☆ | `u32` * 2<sup>128</sup> - 1 | — |
+| [`Xoshiro256PlusPlus`] | Xoshiro256++ | 11 GB/s | 32 bytes | ★★★☆☆ | `u64` * 2<sup>256</sup> - 1 | jump-ahead |
+| [`Xoshiro256Plus`] | Xoshiro256+ | 13 GB/s | 32 bytes | ★★☆☆☆ | `u64` * 2<sup>256</sup> - 1 | jump-ahead |
+| [`SplitMix64`] | splitmix64 | 13 GB/s | 8 bytes | ★☆☆☆☆ | `u64` * 2<sup>64</sup> | — |
+| `StepRng` | counter | 35 GB/s | 16 bytes | ☆☆☆☆☆ | `u64` * 2<sup>64</sup> | — |
+
+Here, performance is measured roughly for `u64` outputs on an
+AMD Ryzen 9 9950X3D (note that this will vary significantly by application; in
+general cryptographic RNGs do better with byte sequence output). Quality ratings are
 based on theory and observable defects, roughly as follows:
 
 -   ★☆☆☆☆ = suitable for simple applications but with significant flaws
@@ -79,12 +79,12 @@ table since CSPRNGs may not have observable defects.
 
 | name | full name |  performance | initialization | memory | security (predictability) | forward secrecy |
 |------|-----------|--------------|--------------|----------|----------------|-------------------------|
-| [`StdRng`] | (unspecified) | 1.5 GB/s | fast | 136 bytes | widely trusted | no |
-| [`ChaCha20Rng`] | ChaCha20 | 1.8 GB/s | fast | 136 bytes | [rigorously analysed](https://tools.ietf.org/html/rfc7539#section-1) | no |
-| [`ChaCha8Rng`] | ChaCha8 | 2.2 GB/s | fast | 136 bytes | small security margin | no |
-| [`Hc128Rng`] | HC-128 | 2.1 GB/s | slow | 4176 bytes | [recommended by eSTREAM](http://www.ecrypt.eu.org/stream/) | no |
-| [`IsaacRng`] | ISAAC | 1.1 GB/s | slow | 2072 bytes | [unknown](https://burtleburtle.net/bob/rand/isaacafa.html) | unknown |
-| [`Isaac64Rng`] | ISAAC-64 | 2.2 GB/s | slow | 4136 bytes| unknown | unknown |
+| [`StdRng`] | (unspecified) | 4.1 GB/s | fast | 136 bytes | widely trusted | no |
+| [`ChaCha20Rng`] | ChaCha20 | 2.6 GB/s | fast | 136 bytes | [rigorously analysed](https://tools.ietf.org/html/rfc7539#section-1) | no |
+| [`ChaCha8Rng`] | ChaCha8 | 5.8 GB/s | fast | 136 bytes | small security margin | no |
+| [`Hc128Rng`] | HC-128 | 4.6 GB/s | slow | 4176 bytes | [recommended by eSTREAM](http://www.ecrypt.eu.org/stream/) | no |
+| [`IsaacRng`] | ISAAC | 2.1 GB/s | slow | 2072 bytes | [unknown](https://burtleburtle.net/bob/rand/isaacafa.html) | unknown |
+| [`Isaac64Rng`] | ISAAC-64 | 3.7 GB/s | slow | 4136 bytes| unknown | unknown |
 
 It should be noted that the ISAAC generators are only included for
 historical reasons: they have been with the Rust language since the very
@@ -131,13 +131,13 @@ Mersenne Twister MT19937 algorithm requires 2.5 kB of state.
 CSPRNGs typically require more memory; since the seed size is recommended
 to be at least 192 bits and some more may be required for the algorithm,
 256 bits would be approximately the minimum secure size. In practice,
-CSPRNGs tend to use quite a bit more, [`ChaChaRng`] is relatively small with
+CSPRNGs tend to use quite a bit more, [`ChaCha20Rng`] is relatively small with
 136 bytes of state.
 
 ### Initialization time
 
 The time required to initialize new generators varies significantly. Many
-simple PRNGs and even some cryptographic ones (including [`ChaChaRng`])
+simple PRNGs and even some cryptographic ones (including [`ChaCha20Rng`])
 only need to copy the seed value and some constants into their state, and
 thus can be constructed very quickly. In contrast, CSPRNGs with large state
 require an expensive key-expansion.
@@ -311,7 +311,6 @@ by P. Hellekalek.
 [`rngs` module]: https://docs.rs/rand/latest/rand/rngs/
 [`SmallRng`]: https://docs.rs/rand/latest/rand/rngs/struct.SmallRng.html
 [`StdRng`]: https://docs.rs/rand/latest/rand/rngs/struct.StdRng.html
-[`StepRng`]: https://docs.rs/rand/latest/rand/rngs/mock/struct.StepRng.html
 [`rand::rng`]: https://docs.rs/rand/latest/rand/fn.rng.html
 [basic PRNGs]: #basic-pseudo-random-number-generators-prngs
 [CSPRNGs]: #cryptographically-secure-pseudo-random-number-generators-csprngs
@@ -322,9 +321,8 @@ by P. Hellekalek.
 [`Xoshiro256PlusPlus`]: https://docs.rs/rand_xoshiro/latest/rand_xoshiro/struct.Xoshiro256PlusPlus.html
 [`Xoshiro256Plus`]: https://docs.rs/rand_xoshiro/latest/rand_xoshiro/struct.Xoshiro256Plus.html
 [`SplitMix64`]: https://docs.rs/rand_xoshiro/latest/rand_xoshiro/struct.SplitMix64.html
-[`ChaChaRng`]: https://docs.rs/rand_chacha/latest/rand_chacha/type.ChaChaRng.html
-[`ChaCha20Rng`]: https://docs.rs/rand_chacha/latest/rand_chacha/struct.ChaCha20Rng.html
-[`ChaCha8Rng`]: https://docs.rs/rand_chacha/latest/rand_chacha/struct.ChaCha8Rng.html
+[`ChaCha20Rng`]: https://docs.rs/chacha20/latest/chacha20/struct.ChaCha20Rng.html
+[`ChaCha8Rng`]: https://docs.rs/chacha20/latest/chacha20/struct.ChaCha8Rng.html
 [`Hc128Rng`]: https://docs.rs/rand_hc/latest/rand_hc/struct.Hc128Rng.html
 [`IsaacRng`]: https://docs.rs/rand_isaac/latest/rand_isaac/isaac/struct.IsaacRng.html
 [`Isaac64Rng`]: https://docs.rs/rand_isaac/latest/rand_isaac/isaac64/struct.Isaac64Rng.html

src/guide-seeding.md

@@ -110,12 +110,12 @@ to a hash result, then using that result to seed a generator. The
 
 ```rust,noplayground
 use rand::prelude::*;
+use rand::rngs::Xoshiro256PlusPlus;
 use rand_seeder::{Seeder, SipHasher};
-use rand_pcg::Pcg64;
 
 fn main() {
     // In one line:
-    let mut rng: Pcg64 = Seeder::from("stripy zebra").into_rng();
+    let mut rng: Xoshiro256PlusPlus = Seeder::from("stripy zebra").into_rng();
     println!("{}", rng.random::<char>());
 
     // If we want to be more explicit, first we create a SipRng:
@@ -124,11 +124,11 @@ fn main() {
     // (Note: hasher_rng is a full RNG and can be used directly.)
 
     // Now, we use hasher_rng to create a seed:
-    let mut seed: <Pcg64 as SeedableRng>::Seed = Default::default();
+    let mut seed: <Xoshiro256PlusPlus as SeedableRng>::Seed = Default::default();
     hasher_rng.fill(&mut seed);
 
     // And create our RNG from that seed:
-    let mut rng = Pcg64::from_seed(seed);
+    let mut rng = Xoshiro256PlusPlus::from_seed(seed);
     println!("{}", rng.random::<char>());
 }
 ```
@@ -144,6 +144,6 @@ function such as Argon2 must be used.
 [`SeedableRng::from_rng`]: https://docs.rs/rand_core/latest/rand_core/trait.SeedableRng.html#method.from_rng
 [`SeedableRng::seed_from_u64`]: https://docs.rs/rand_core/latest/rand_core/trait.SeedableRng.html#method.seed_from_u64
 [`XorShiftRng`]: https://docs.rs/rand_xorshift/latest/rand_xorshift/struct.XorShiftRng.html
-[`ChaCha8Rng`]: https://docs.rs/rand_chacha/latest/rand_chacha/struct.ChaCha8Rng.html
+[`ChaCha8Rng`]: https://docs.rs/rand/latest/rand/rngs/struct.ChaCha8Rng.html
 [`rand_seeder`]: https://github.com/rust-random/seeder/
 [`rand::make_rng()`]: https://docs.rs/rand/latest/rand/fn.make_rng.html