Add RngCore::bytes_per_round

benches/distributions.rs

@@ -1,5 +1,6 @@
 #![feature(test)]
-#![cfg_attr(feature = "i128_support", feature(i128_type, i128))]
+#![cfg_attr(all(feature="i128_support", feature="nightly"), allow(stable_features))] // stable since 2018-03-27
+#![cfg_attr(all(feature="i128_support", feature="nightly"), feature(i128_type, i128))]
 
 extern crate test;
 extern crate rand;

benches/generators.rs

@@ -1,4 +1,6 @@
 #![feature(test)]
+#![cfg_attr(all(feature="i128_support", feature="nightly"), allow(stable_features))] // stable since 2018-03-27
+#![cfg_attr(all(feature="i128_support", feature="nightly"), feature(i128_type, i128))]
 
 extern crate test;
 extern crate rand;
@@ -74,6 +76,10 @@ gen_uint!(gen_u64_std, u64, StdRng::new());
 gen_uint!(gen_u64_small, u64, SmallRng::new());
 gen_uint!(gen_u64_os, u64, OsRng::new().unwrap());
 
+#[cfg(feature = "i128_support")] gen_uint!(gen_u128_xorshift, u128, XorShiftRng::new());
+#[cfg(feature = "i128_support")] gen_uint!(gen_u128_hc128, u128, Hc128Rng::new());
+#[cfg(feature = "i128_support")] gen_uint!(gen_u128_os, u128, OsRng::new().unwrap());
+
 // Do not test JitterRng like the others by running it RAND_BENCH_N times per,
 // measurement, because it is way too slow. Only run it once.
 #[bench]

rand_core/src/lib.rs

@@ -186,6 +186,19 @@ pub trait RngCore {
     /// 
     /// [`fill_bytes`]: trait.RngCore.html#method.fill_bytes
     fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>;
+
+    /// Number of bytes generated per round of this RNG.
+    ///
+    /// Some algorithms would benefit from knowing some basic properties about
+    /// the RNG. In terms of performance an algorithm may want to know whether
+    /// an RNG is best at generating `u32`s, or could provide `u64`s or more at
+    /// little to no extra cost.
+    ///
+    /// For many RNGs a simple definition is: the smallest number of bytes this
+    /// RNG can generate without throwing away part of the generated value.
+    ///
+    /// `bytes_per_round` has a default implementation that returns `4` (bytes).
+    fn bytes_per_round(&self) -> usize { 4 }
 }
 
 /// A trait for RNGs which do not generate random numbers individually, but in
@@ -384,7 +397,9 @@ pub trait SeedableRng: Sized {
     }
 }
 
-
+// Implement `RngCore` for references to an `RngCore`.
+// Force inlining all functions, so that it is up to the `RngCore`
+// implementation and the optimizer to decide on inlining.
 impl<'a, R: RngCore + ?Sized> RngCore for &'a mut R {
     #[inline(always)]
     fn next_u32(&mut self) -> u32 {
@@ -396,15 +411,24 @@ impl<'a, R: RngCore + ?Sized> RngCore for &'a mut R {
         (**self).next_u64()
     }
 
+    #[inline(always)]
     fn fill_bytes(&mut self, dest: &mut [u8]) {
         (**self).fill_bytes(dest)
     }
 
+    #[inline(always)]
     fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
         (**self).try_fill_bytes(dest)
     }
+
+    fn bytes_per_round(&self) -> usize {
+        (**self).bytes_per_round()
+    }
 }
 
+// Implement `RngCore` for boxed references to an `RngCore`.
+// Force inlining all functions, so that it is up to the `RngCore`
+// implementation and the optimizer to decide on inlining.
 #[cfg(feature="alloc")]
 impl<R: RngCore + ?Sized> RngCore for Box<R> {
     #[inline(always)]
@@ -417,11 +441,17 @@ impl<R: RngCore + ?Sized> RngCore for Box<R> {
         (**self).next_u64()
     }
 
+    #[inline(always)]
     fn fill_bytes(&mut self, dest: &mut [u8]) {
         (**self).fill_bytes(dest)
     }
 
+    #[inline(always)]
     fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
         (**self).try_fill_bytes(dest)
     }
+
+    fn bytes_per_round(&self) -> usize {
+        (**self).bytes_per_round()
+    }
 }

src/distributions/integer.rs

@@ -13,46 +13,52 @@
 use {Rng};
 use distributions::{Distribution, Standard};
 
-impl Distribution<isize> for Standard {
-    #[inline]
-    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> isize {
-        rng.gen::<usize>() as isize
-    }
-}
-
-impl Distribution<i8> for Standard {
+impl Distribution<u8> for Standard {
     #[inline]
-    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> i8 {
-        rng.next_u32() as i8
+    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> u8 {
+        rng.next_u32() as u8
     }
 }
 
-impl Distribution<i16> for Standard {
+impl Distribution<u16> for Standard {
     #[inline]
-    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> i16 {
-        rng.next_u32() as i16
+    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> u16 {
+        rng.next_u32() as u16
     }
 }
 
-impl Distribution<i32> for Standard {
+impl Distribution<u32> for Standard {
     #[inline]
-    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> i32 {
-        rng.next_u32() as i32
+    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> u32 {
+        rng.next_u32()
     }
 }
 
-impl Distribution<i64> for Standard {
+impl Distribution<u64> for Standard {
     #[inline]
-    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> i64 {
-        rng.next_u64() as i64
+    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> u64 {
+        rng.next_u64()
     }
 }
 
 #[cfg(feature = "i128_support")]
-impl Distribution<i128> for Standard {
+impl Distribution<u128> for Standard {
     #[inline]
-    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> i128 {
-        rng.gen::<u128>() as i128
+    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> u128 {
+        if rng.bytes_per_round() < 128 {
+            // Use LE; we explicitly generate one value before the next.
+            let x = rng.next_u64() as u128;
+            let y = rng.next_u64() as u128;
+            (y << 64) | x
+        } else {
+            let mut val = 0u128;
+            unsafe {
+                let ptr = &mut val;
+                let b_ptr = &mut *(ptr as *mut u128 as *mut [u8; 16]);
+                rng.fill_bytes(b_ptr);
+            }
+            val.to_le()
+        }
     }
 }
 
@@ -70,44 +76,23 @@ impl Distribution<usize> for Standard {
     }
 }
 
-impl Distribution<u8> for Standard {
-    #[inline]
-    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> u8 {
-        rng.next_u32() as u8
+macro_rules! impl_int_from_uint {
+    ($ty:ty, $uty:ty) => {
+        impl Distribution<$ty> for Standard {
+            #[inline]
+            fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> $ty {
+                rng.gen::<$uty>() as $ty
+            }
+        }
     }
 }
 
-impl Distribution<u16> for Standard {
-    #[inline]
-    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> u16 {
-        rng.next_u32() as u16
-    }
-}
-
-impl Distribution<u32> for Standard {
-    #[inline]
-    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> u32 {
-        rng.next_u32()
-    }
-}
-
-impl Distribution<u64> for Standard {
-    #[inline]
-    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> u64 {
-        rng.next_u64()
-    }
-}
-
-#[cfg(feature = "i128_support")]
-impl Distribution<u128> for Standard {
-    #[inline]
-    fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> u128 {
-        // Use LE; we explicitly generate one value before the next.
-        let x = rng.next_u64() as u128;
-        let y = rng.next_u64() as u128;
-        (y << 64) | x
-    }
-}
+impl_int_from_uint! { i8, u8 }
+impl_int_from_uint! { i16, u16 }
+impl_int_from_uint! { i32, u32 }
+impl_int_from_uint! { i64, u64 }
+#[cfg(feature = "i128_support")] impl_int_from_uint! { i128, u128 }
+impl_int_from_uint! { isize, usize }
 
 
 #[cfg(test)]

src/lib.rs

@@ -849,6 +849,10 @@ impl RngCore for StdRng {
     fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
         self.0.try_fill_bytes(dest)
     }
+
+    fn bytes_per_round(&self) -> usize {
+        self.0.bytes_per_round()
+    }
 }
 
 impl SeedableRng for StdRng {
@@ -936,6 +940,10 @@ impl RngCore for SmallRng {
     fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
         self.0.try_fill_bytes(dest)
     }
+
+    fn bytes_per_round(&self) -> usize {
+        self.0.bytes_per_round()
+    }
 }
 
 impl SeedableRng for SmallRng {
@@ -1017,6 +1025,9 @@ mod test {
         fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
             self.inner.try_fill_bytes(dest)
         }
+        fn bytes_per_round(&self) -> usize {
+            self.inner.bytes_per_round()
+        }
     }
 
     pub fn rng(seed: u64) -> TestRng<StdRng> {

src/mock.rs

@@ -58,4 +58,6 @@ impl RngCore for StepRng {
     fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
         Ok(self.fill_bytes(dest))
     }
+
+    fn bytes_per_round(&self) -> usize { 8 }
 }

src/os.rs

@@ -131,6 +131,14 @@ impl RngCore for OsRng {
     fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
         self.0.try_fill_bytes(dest)
     }
+
+    fn bytes_per_round(&self) -> usize {
+        // The overhead of doing a syscall is large compared to the time
+        // it takes to generate the values. Requesting many values at a time is
+        // often faster than only one at a time.
+        // 256 is the limit some operating systems have per system call.
+        256
+    }
 }
 
 #[cfg(all(unix,

src/reseeding.rs

@@ -101,6 +101,10 @@ where R: BlockRngCore<Item = u32> + SeedableRng,
     fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
         self.0.try_fill_bytes(dest)
     }
+
+    fn bytes_per_round(&self) -> usize {
+        self.0.bytes_per_round()
+    }
 }
 
 impl<R, Rsdr> CryptoRng for ReseedingRng<R, Rsdr>