Rename BlockRngCore -> Generator

Author: dhardy

src/block.rs

@@ -1,6 +1,6 @@
-//! The `BlockRngCore` trait and implementation helpers
+//! The `Generator` trait and implementation helpers
 //!
-//! The [`BlockRngCore`] trait exists to assist in the implementation of RNGs
+//! The [`Generator`] trait exists to assist in the implementation of RNGs
 //! which generate a block of data in a cache instead of returning generated
 //! values directly.
 //!
@@ -15,14 +15,14 @@
 //!
 //! ```no_run
 //! use rand_core::{RngCore, SeedableRng};
-//! use rand_core::block::{BlockRngCore, BlockRng};
+//! use rand_core::block::{Generator, BlockRng};
 //!
 //! struct MyRngCore;
 //!
-//! impl BlockRngCore for MyRngCore {
-//!     type Results = [u32; 16];
+//! impl Generator for MyRngCore {
+//!     type Result = [u32; 16];
 //!
-//!     fn generate(&mut self, results: &mut Self::Results) {
+//!     fn generate(&mut self, result: &mut Self::Result) {
 //!         unimplemented!()
 //!     }
 //! }
@@ -34,14 +34,14 @@
 //!     }
 //! }
 //!
-//! // optionally, also implement CryptoBlockRng for MyRngCore
+//! // optionally, also implement CryptoGenerator for MyRngCore
 //!
 //! // Final RNG.
 //! let mut rng = BlockRng::<MyRngCore>::seed_from_u64(0);
 //! println!("First value: {}", rng.next_u32());
 //! ```
 //!
-//! [`BlockRngCore`]: crate::block::BlockRngCore
+//! [`Generator`]: crate::block::Generator
 //! [`fill_bytes`]: RngCore::fill_bytes
 
 use crate::le::fill_via_chunks;
@@ -50,28 +50,54 @@ use core::fmt;
 #[cfg(feature = "serde")]
 use serde::{Deserialize, Serialize};
 
-/// A trait for RNGs which do not generate random numbers individually, but in
-/// blocks (typically `[u32; N]`). This technique is commonly used by
-/// cryptographic RNGs to improve performance.
-///
-/// See the [module][crate::block] documentation for details.
-pub trait BlockRngCore {
-    /// Results type. This is the 'block' an RNG implementing `BlockRngCore`
-    /// generates, which will usually be an array like `[u32; 16]`.
-    type Results;
-
-    /// Generate a new block of results.
-    fn generate(&mut self, results: &mut Self::Results);
+/// A random generator
+pub trait Generator {
+    /// The result type.
+    ///
+    /// This could be a simple word like `u64` or an array like `[u32; 16]`.
+    type Result;
+
+    /// Generate a new result.
+    ///
+    /// Since [`Self::Result`] may be large, the output is passed by reference.
+    /// Word generators should likely implement this as a shim over another
+    /// method:
+    /// ```
+    /// pub struct CountingGenerator(u64);
+    /// impl CountingGenerator {
+    ///     fn next(&mut self) -> u64 {
+    ///         let x = self.0;
+    ///         self.0 = self.0.wrapping_add(1);
+    ///         x
+    ///     }
+    /// }
+    ///
+    /// impl rand_core::block::Generator for CountingGenerator {
+    ///     type Result = u64;
+    ///
+    ///     #[inline]
+    ///     fn generate(&mut self, result: &mut Self::Result) {
+    ///         *result = self.next();
+    ///     }
+    /// }
+    /// ```
+    fn generate(&mut self, result: &mut Self::Result);
 }
 
-/// A marker trait used to indicate that an [`RngCore`] implementation is
-/// supposed to be cryptographically secure.
+/// A cryptographically secure generator
+///
+/// This is a marker trait used to indicate that a [`Generator`] implementation
+/// is supposed to be cryptographically secure.
+///
+/// Mock generators should not implement this trait *except* under a
+/// `#[cfg(test)]` attribute to ensure that mock "crypto" generators cannot be
+/// used in production.
 ///
 /// See [`CryptoRng`] docs for more information.
-pub trait CryptoBlockRng: BlockRngCore {}
+pub trait CryptoGenerator: Generator {}
 
 /// A wrapper type implementing [`RngCore`] for some type implementing
-/// [`BlockRngCore`] with `u32` array buffer; i.e. this can be used to implement
+/// [`Generator`] with `u32` array buffer; i.e. this can be used to implement
 /// a full RNG from just a `generate` function.
 ///
 /// The `core` field may be accessed directly but the results buffer may not.
@@ -84,7 +110,7 @@ pub trait CryptoBlockRng: BlockRngCore {}
 ///
 /// `BlockRng` has heavily optimized implementations of the [`RngCore`] methods
 /// reading values from the results buffer, as well as
-/// calling [`BlockRngCore::generate`] directly on the output array when
+/// calling [`Generator::generate`] directly on the output array when
 /// [`fill_bytes`] is called on a large array. These methods also handle
 /// the bookkeeping of when to generate a new batch of values.
 ///
@@ -108,18 +134,18 @@ pub trait CryptoBlockRng: BlockRngCore {}
 #[cfg_attr(
     feature = "serde",
     serde(
-        bound = "for<'x> R: Serialize + Deserialize<'x>, for<'x> R::Results: Serialize + Deserialize<'x>"
+        bound = "for<'x> R: Serialize + Deserialize<'x>, for<'x> R::Result: Serialize + Deserialize<'x>"
     )
 )]
-pub struct BlockRng<R: BlockRngCore> {
-    results: R::Results,
+pub struct BlockRng<R: Generator> {
+    results: R::Result,
     index: usize,
     /// The *core* part of the RNG, implementing the `generate` function.
     pub core: R,
 }
 
 // Custom Debug implementation that does not expose the contents of `results`.
-impl<const N: usize, R: BlockRngCore<Results = [u32; N]> + fmt::Debug> fmt::Debug for BlockRng<R> {
+impl<const N: usize, R: Generator<Result = [u32; N]> + fmt::Debug> fmt::Debug for BlockRng<R> {
     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
         fmt.debug_struct("BlockRng")
             .field("core", &self.core)
@@ -129,9 +155,9 @@ impl<const N: usize, R: BlockRngCore<Results = [u32; N]> + fmt::Debug> fmt::Debu
     }
 }
 
-impl<const N: usize, R: BlockRngCore<Results = [u32; N]>> BlockRng<R> {
+impl<const N: usize, R: Generator<Result = [u32; N]>> BlockRng<R> {
     /// Create a new `BlockRng` from an existing RNG implementing
-    /// `BlockRngCore`. Results will be generated on first use.
+    /// `Generator`. Result will be generated on first use.
     #[inline]
     pub fn new(core: R) -> BlockRng<R> {
         BlockRng {
@@ -168,7 +194,7 @@ impl<const N: usize, R: BlockRngCore<Results = [u32; N]>> BlockRng<R> {
     }
 }
 
-impl<const N: usize, R: BlockRngCore<Results = [u32; N]>> RngCore for BlockRng<R> {
+impl<const N: usize, R: Generator<Result = [u32; N]>> RngCore for BlockRng<R> {
     #[inline]
     fn next_u32(&mut self) -> u32 {
         if self.index >= self.results.as_ref().len() {
@@ -221,7 +247,7 @@ impl<const N: usize, R: BlockRngCore<Results = [u32; N]>> RngCore for BlockRng<R
     }
 }
 
-impl<const N: usize, R: BlockRngCore<Results = [u32; N]> + SeedableRng> SeedableRng
+impl<const N: usize, R: Generator<Result = [u32; N]> + SeedableRng> SeedableRng
     for BlockRng<R>
 {
     type Seed = R::Seed;
@@ -247,10 +273,10 @@ impl<const N: usize, R: BlockRngCore<Results = [u32; N]> + SeedableRng> Seedable
     }
 }
 
-impl<const N: usize, R: CryptoBlockRng<Results = [u32; N]>> CryptoRng for BlockRng<R> {}
+impl<const N: usize, R: CryptoGenerator<Result = [u32; N]>> CryptoRng for BlockRng<R> {}
 
 /// A wrapper type implementing [`RngCore`] for some type implementing
-/// [`BlockRngCore`] with `u64` array buffer; i.e. this can be used to implement
+/// [`Generator`] with `u64` array buffer; i.e. this can be used to implement
 /// a full RNG from just a `generate` function.
 ///
 /// This is similar to [`BlockRng`], but specialized for algorithms that operate
@@ -271,16 +297,16 @@ impl<const N: usize, R: CryptoBlockRng<Results = [u32; N]>> CryptoRng for BlockR
 /// [`fill_bytes`]: RngCore::fill_bytes
 #[derive(Clone)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
-pub struct BlockRng64<R: BlockRngCore + ?Sized> {
-    results: R::Results,
+pub struct BlockRng64<R: Generator + ?Sized> {
+    results: R::Result,
     index: usize,
     half_used: bool, // true if only half of the previous result is used
     /// The *core* part of the RNG, implementing the `generate` function.
     pub core: R,
 }
 
 // Custom Debug implementation that does not expose the contents of `results`.
-impl<const N: usize, R: BlockRngCore<Results = [u64; N]> + fmt::Debug> fmt::Debug
+impl<const N: usize, R: Generator<Result = [u64; N]> + fmt::Debug> fmt::Debug
     for BlockRng64<R>
 {
     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
@@ -293,9 +319,9 @@ impl<const N: usize, R: BlockRngCore<Results = [u64; N]> + fmt::Debug> fmt::Debu
     }
 }
 
-impl<const N: usize, R: BlockRngCore<Results = [u64; N]>> BlockRng64<R> {
+impl<const N: usize, R: Generator<Result = [u64; N]>> BlockRng64<R> {
     /// Create a new `BlockRng` from an existing RNG implementing
-    /// `BlockRngCore`. Results will be generated on first use.
+    /// `Generator`. Results will be generated on first use.
     #[inline]
     pub fn new(core: R) -> BlockRng64<R> {
         let results_empty = [0; N];
@@ -336,7 +362,7 @@ impl<const N: usize, R: BlockRngCore<Results = [u64; N]>> BlockRng64<R> {
     }
 }
 
-impl<const N: usize, R: BlockRngCore<Results = [u64; N]>> RngCore for BlockRng64<R> {
+impl<const N: usize, R: Generator<Result = [u64; N]>> RngCore for BlockRng64<R> {
     #[inline]
     fn next_u32(&mut self) -> u32 {
         let mut index = self.index - self.half_used as usize;
@@ -388,7 +414,7 @@ impl<const N: usize, R: BlockRngCore<Results = [u64; N]>> RngCore for BlockRng64
     }
 }
 
-impl<const N: usize, R: BlockRngCore<Results = [u64; N]> + SeedableRng> SeedableRng
+impl<const N: usize, R: Generator<Result = [u64; N]> + SeedableRng> SeedableRng
     for BlockRng64<R>
 {
     type Seed = R::Seed;
@@ -414,22 +440,22 @@ impl<const N: usize, R: BlockRngCore<Results = [u64; N]> + SeedableRng> Seedable
     }
 }
 
-impl<const N: usize, R: CryptoBlockRng<Results = [u64; N]>> CryptoRng for BlockRng64<R> {}
+impl<const N: usize, R: CryptoGenerator<Result = [u64; N]>> CryptoRng for BlockRng64<R> {}
 
 #[cfg(test)]
 mod test {
-    use crate::block::{BlockRng, BlockRng64, BlockRngCore};
+    use crate::block::{BlockRng, BlockRng64, Generator};
     use crate::{RngCore, SeedableRng};
 
     #[derive(Debug, Clone)]
     struct DummyRng {
         counter: u32,
     }
 
-    impl BlockRngCore for DummyRng {
-        type Results = [u32; 16];
+    impl Generator for DummyRng {
+        type Result = [u32; 16];
 
-        fn generate(&mut self, results: &mut Self::Results) {
+        fn generate(&mut self, results: &mut Self::Result) {
             for r in results {
                 *r = self.counter;
                 self.counter = self.counter.wrapping_add(3511615421);
@@ -476,10 +502,10 @@ mod test {
         counter: u64,
     }
 
-    impl BlockRngCore for DummyRng64 {
-        type Results = [u64; 8];
+    impl Generator for DummyRng64 {
+        type Result = [u64; 8];
 
-        fn generate(&mut self, results: &mut Self::Results) {
+        fn generate(&mut self, results: &mut Self::Result) {
             for r in results {
                 *r = self.counter;
                 self.counter = self.counter.wrapping_add(2781463553396133981);