Merge pull request #446 from dhardy/block-value-order

Specify value consumption order for block-based RNGs

Author: dhardy

rand_core/src/block.rs

@@ -90,19 +90,31 @@ pub trait 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
-/// `fill_bytes` / `try_fill_bytes` is called on a large array. These methods
+/// calling [`BlockRngCore::generate`] directly on the output array when
+/// [`fill_bytes`] / [`try_fill_bytes`] is called on a large array. These methods
 /// also handle the bookkeeping of when to generate a new batch of values.
-/// No generated values are ever thown away and all values are consumed
-/// in-order (this may be important for reproducibility).
+///
+/// No whole generated `u32` values are thown away and all values are consumed
+/// in-order. [`next_u32`] simply takes the next available `u32` value.
+/// [`next_u64`] is implemented by combining two `u32` values, least
+/// significant first. [`fill_bytes`] and [`try_fill_bytes`] consume a whole
+/// number of `u32` values, converting each `u32` to a byte slice in
+/// little-endian order. If the requested byte length is not a multiple of 4,
+/// some bytes will be discarded.
 ///
 /// See also [`BlockRng64`] which uses `u64` array buffers. Currently there is
 /// no direct support for other buffer types.
 ///
 /// For easy initialization `BlockRng` also implements [`SeedableRng`].
 ///
 /// [`BlockRngCore`]: BlockRngCore.t.html
+/// [`BlockRngCore::generate`]: trait.BlockRngCore.html#tymethod.generate
+/// [`BlockRng64`]: struct.BlockRng64.html
 /// [`RngCore`]: ../RngCore.t.html
+/// [`next_u32`]: ../trait.RngCore.html#tymethod.next_u32
+/// [`next_u64`]: ../trait.RngCore.html#tymethod.next_u64
+/// [`fill_bytes`]: ../trait.RngCore.html#tymethod.fill_bytes
+/// [`try_fill_bytes`]: ../trait.RngCore.html#tymethod.try_fill_bytes
 /// [`SeedableRng`]: ../SeedableRng.t.html
 #[derive(Clone)]
 #[cfg_attr(feature="serde1", derive(Serialize, Deserialize))]
@@ -289,15 +301,23 @@ impl<R: BlockRngCore + SeedableRng> SeedableRng for BlockRng<R> {
 /// This is similar to [`BlockRng`], but specialized for algorithms that operate
 /// on `u64` values.
 ///
-/// Like [`BlockRng`], this wrapper does not throw away whole results and does
-/// use all generated values in-order. The behaviour of `next_u32` is however
-/// a bit special: half of a `u64` is consumed, leaving the other half in the
-/// buffer. If the next function called is `next_u32` then the other half is
-/// then consumed, however both `next_u64` and `fill_bytes` discard any
-/// half-consumed `u64`s when called.
+/// No whole generated `u64` values are thrown away and all values are consumed
+/// in-order. [`next_u64`] simply takes the next available `u64` value.
+/// [`next_u32`] is however a bit special: half of a `u64` is consumed, leaving
+/// the other half in the buffer. If the next function called is [`next_u32`]
+/// then the other half is then consumed, however both [`next_u64`] and
+/// [`fill_bytes`] discard the rest of any half-consumed `u64`s when called.
+///
+/// [`fill_bytes`] and [`try_fill_bytes`] consume a whole number of `u64`
+/// values. If the requested length is not a multiple of 8, some bytes will be
+/// discarded.
 ///
 /// [`BlockRngCore`]: BlockRngCore.t.html
 /// [`RngCore`]: ../RngCore.t.html
+/// [`next_u32`]: ../trait.RngCore.html#tymethod.next_u32
+/// [`next_u64`]: ../trait.RngCore.html#tymethod.next_u64
+/// [`fill_bytes`]: ../trait.RngCore.html#tymethod.fill_bytes
+/// [`try_fill_bytes`]: ../trait.RngCore.html#tymethod.try_fill_bytes
 /// [`BlockRng`]: struct.BlockRng.html
 #[derive(Clone)]
 #[cfg_attr(feature="serde1", derive(Serialize, Deserialize))]

src/prng/chacha.rs

@@ -54,6 +54,9 @@ const STATE_WORDS: usize = 16;
 /// counter  counter  nonce    nonce
 /// ```
 ///
+/// This implementation uses an output buffer of sixteen `u32` words, and uses
+/// [`BlockRng`] to implement the [`RngCore`] methods.
+///
 /// [1]: D. J. Bernstein, [*ChaCha, a variant of Salsa20*](
 ///      https://cr.yp.to/chacha.html)
 ///
@@ -62,6 +65,8 @@ const STATE_WORDS: usize = 16;
 ///
 /// [`set_word_pos`]: #method.set_word_pos
 /// [`set_stream`]: #method.set_stream
+/// [`BlockRng`]: ../../../rand_core/block/struct.BlockRng.html
+/// [`RngCore`]: ../../trait.RngCore.html
 #[derive(Clone, Debug)]
 pub struct ChaChaRng(BlockRng<ChaChaCore>);
 

src/prng/hc128.rs

@@ -44,6 +44,9 @@ const SEED_WORDS: usize = 8; // 128 bit key followed by 128 bit iv
 /// We support seeding with a 256-bit array, which matches the 128-bit key
 /// concatenated with a 128-bit IV from the stream cipher.
 ///
+/// This implementation uses an output buffer of sixteen `u32` words, and uses
+/// [`BlockRng`] to implement the [`RngCore`] methods.
+///
 /// ## References
 /// [1]: Hongjun Wu (2008). ["The Stream Cipher HC-128"](
 ///      http://www.ecrypt.eu.org/stream/p3ciphers/hc/hc128_p3.pdf).
@@ -61,6 +64,9 @@ const SEED_WORDS: usize = 8; // 128 bit key followed by 128 bit iv
 ///
 /// [5]: Internet Engineering Task Force (Februari 2015),
 ///      ["Prohibiting RC4 Cipher Suites"](https://tools.ietf.org/html/rfc7465).
+///
+/// [`BlockRng`]: ../../../rand_core/block/struct.BlockRng.html
+/// [`RngCore`]: ../../trait.RngCore.html
 #[derive(Clone, Debug)]
 pub struct Hc128Rng(BlockRng<Hc128Core>);
 

src/prng/isaac.rs

@@ -75,6 +75,8 @@ const RAND_SIZE: usize = 1 << RAND_SIZE_LEN;
 /// ISAAC therefore needs a lot of memory, relative to other non-vrypto RNGs.
 /// 2 * 256 * 4 = 2 kb to hold the state and results.
 ///
+/// This implementation uses [`BlockRng`] to implement the [`RngCore`] methods.
+///
 /// ## References
 /// [1]: Bob Jenkins, [*ISAAC: A fast cryptographic random number generator*](
 ///      http://burtleburtle.net/bob/rand/isaacafa.html)
@@ -86,6 +88,8 @@ const RAND_SIZE: usize = 1 << RAND_SIZE_LEN;
 ///      https://eprint.iacr.org/2006/438)
 ///
 /// [`Hc128Rng`]: ../hc128/struct.Hc128Rng.html
+/// [`BlockRng`]: ../../../rand_core/block/struct.BlockRng.html
+/// [`RngCore`]: ../../trait.RngCore.html
 #[derive(Clone, Debug)]
 #[cfg_attr(feature="serde1", derive(Serialize, Deserialize))]
 pub struct IsaacRng(BlockRng<IsaacCore>);

src/prng/isaac64.rs

@@ -69,13 +69,17 @@ const RAND_SIZE: usize = 1 << RAND_SIZE_LEN;
 /// }
 /// ```
 ///
+/// This implementation uses [`BlockRng64`] to implement the [`RngCore`] methods.
+///
 /// See for more information the documentation of [`IsaacRng`].
 ///
 /// [1]: Bob Jenkins, [*ISAAC and RC4*](
 ///      http://burtleburtle.net/bob/rand/isaac.html)
 ///
 /// [`IsaacRng`]: ../isaac/struct.IsaacRng.html
 /// [`Hc128Rng`]: ../hc128/struct.Hc128Rng.html
+/// [`BlockRng64`]: ../../../rand_core/block/struct.BlockRng64.html
+/// [`RngCore`]: ../../trait.RngCore.html
 #[derive(Clone, Debug)]
 #[cfg_attr(feature="serde1", derive(Serialize, Deserialize))]
 pub struct Isaac64Rng(BlockRng64<Isaac64Core>);