Add PCG to benchmarks and PRNG module documentation

Author: dhardy

benches/generators.rs

@@ -13,6 +13,7 @@ extern crate rand;
 extern crate rand_isaac;
 extern crate rand_chacha;
 extern crate rand_hc128;
+extern crate rand_pcg;
 extern crate rand_xorshift;
 
 const RAND_BENCH_N: u64 = 1000;
@@ -27,6 +28,7 @@ use rand::rngs::{OsRng, JitterRng, EntropyRng};
 use rand_isaac::{IsaacRng, Isaac64Rng};
 use rand_chacha::ChaChaRng;
 use rand_hc128::{Hc128Rng, Hc128Core};
+use rand_pcg::{Lcg64Xsh32, Mcg128Xsl64};
 use rand_xorshift::XorShiftRng;
 
 macro_rules! gen_bytes {
@@ -47,6 +49,8 @@ macro_rules! gen_bytes {
 }
 
 gen_bytes!(gen_bytes_xorshift, XorShiftRng::from_entropy());
+gen_bytes!(gen_bytes_lcg64_xsh32, Lcg64Xsh32::from_entropy());
+gen_bytes!(gen_bytes_mcg128_xsh64, Mcg128Xsl64::from_entropy());
 gen_bytes!(gen_bytes_chacha20, ChaChaRng::from_entropy());
 gen_bytes!(gen_bytes_hc128, Hc128Rng::from_entropy());
 gen_bytes!(gen_bytes_isaac, IsaacRng::from_entropy());
@@ -73,6 +77,8 @@ macro_rules! gen_uint {
 }
 
 gen_uint!(gen_u32_xorshift, u32, XorShiftRng::from_entropy());
+gen_uint!(gen_u32_lcg64_xsh32, u32, Lcg64Xsh32::from_entropy());
+gen_uint!(gen_u32_mcg128_xsh64, u32, Mcg128Xsl64::from_entropy());
 gen_uint!(gen_u32_chacha20, u32, ChaChaRng::from_entropy());
 gen_uint!(gen_u32_hc128, u32, Hc128Rng::from_entropy());
 gen_uint!(gen_u32_isaac, u32, IsaacRng::from_entropy());
@@ -82,6 +88,8 @@ gen_uint!(gen_u32_small, u32, SmallRng::from_entropy());
 gen_uint!(gen_u32_os, u32, OsRng::new().unwrap());
 
 gen_uint!(gen_u64_xorshift, u64, XorShiftRng::from_entropy());
+gen_uint!(gen_u64_lcg64_xsh32, u64, Lcg64Xsh32::from_entropy());
+gen_uint!(gen_u64_mcg128_xsh64, u64, Mcg128Xsl64::from_entropy());
 gen_uint!(gen_u64_chacha20, u64, ChaChaRng::from_entropy());
 gen_uint!(gen_u64_hc128, u64, Hc128Rng::from_entropy());
 gen_uint!(gen_u64_isaac, u64, IsaacRng::from_entropy());
@@ -115,6 +123,8 @@ macro_rules! init_gen {
 }
 
 init_gen!(init_xorshift, XorShiftRng);
+init_gen!(init_lcg64_xsh32, Lcg64Xsh32);
+init_gen!(init_mcg128_xsh64, Mcg128Xsl64);
 init_gen!(init_hc128, Hc128Rng);
 init_gen!(init_isaac, IsaacRng);
 init_gen!(init_isaac64, Isaac64Rng);

src/prng/mod.rs

@@ -45,16 +45,17 @@
 //!
 //! | name | full name | performance | memory | quality | period | features |
 //! |------|-----------|-------------|--------|---------|--------|----------|
-//! | [`XorShiftRng`] | Xorshift 32/128 | ★★★☆☆ | 16 bytes | ★☆☆☆☆ | `u32` * 2<sup>128</sup> - 1 | — |
+//! | [`Pcg32`] | PCG XSH RR 64/32 (LCG) | ★★★☆☆ | 16 bytes | ★★★☆☆ | `u32` * 2<sup>64</sup> | — |
+//! | [`Pcg64Mcg`] | PCG XSL 128/64 (MCG) | ★★★★☆ | 16 bytes | ★★★☆☆ | `u64` * 2<sup>126</sup> | — |
+//! | [`XorShiftRng`] | Xorshift 32/128 | ★★★★☆ | 16 bytes | ★☆☆☆☆ | `u32` * 2<sup>128</sup> - 1 | — |
 //!
 // Quality stars [not rendered in documentation]:
-// 5. reserved for crypto-level (e.g. ChaCha8, ISAAC)
-// 4. good performance on TestU01 and PractRand, good theory
+// 5. proven cryptographic quality (e.g. ChaCha20)
+// 4. potentially cryptographic, but low margin or lack of theory (e.g. ChaCha8, ISAAC)
+// 3. good performance on TestU01 and PractRand, good theory
 //    (e.g. PCG, truncated Xorshift*)
-// 3. good performance on TestU01 and PractRand, but "falling through the
-//    cracks" or insufficient theory (e.g. SFC, Xoshiro)
-// 2. imperfect performance on tests or other limiting properties, but not
-//    terrible (e.g. Xoroshiro128+)
+// 2. imperfect performance on tests or other limiting properties, or
+//    insufficient theory, but not terrible (e.g. SFC, Xoshiro, Xoroshiro128+)
 // 1. clear deficiencies in test results, cycle length, theory, or other
 //    properties (e.g. Xorshift)
 //
@@ -297,6 +298,8 @@
 //! [`rngs` module]: ../rngs/index.html
 //! [basic PRNGs]: #basic-pseudo-random-number-generators-prngs
 //! [CSPRNGs]: #cryptographically-secure-pseudo-random-number-generators-csprngs
+//! [`Pcg32`]: ../../rand_pcg/type.Pcg32.html
+//! [`Pcg64Mcg`]: ../../rand_pcg/type.Pcg64Mcg.html
 //! [`XorShiftRng`]: ../../rand_xorshift/struct.XorShiftRng.html
 //! [`ChaChaRng`]: ../../rand_chacha/struct.ChaChaRng.html
 //! [`Hc128Rng`]: ../../rand_hc128/struct.Hc128Rng.html

src/rngs/small.rs

@@ -25,8 +25,7 @@ type Rng = ::rand_pcg::Pcg32;
 /// different output. Further, this generator may not be portable and can
 /// produce different output depending on the architecture. If you require
 /// reproducible output, use a named RNG. Refer to the documentation on the
-/// [`prng` module](../../prng.index.html) or the
-/// [small-rngs repo](https://github.com/rust-random/small-rngs).
+/// [`prng` module](../prng/index.html).
 ///
 /// The current algorithm is [`Pcg64Mcg`] on 64-bit platforms with Rust version
 /// 1.26 and later, or [`Pcg32`] otherwise.