Add RngCore::bytes_per_round

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
@@ -403,6 +416,10 @@ impl<'a, R: RngCore + ?Sized> RngCore for &'a mut R {
     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()
+    }
 }
 
 #[cfg(feature="alloc")]
@@ -424,4 +441,8 @@ impl<R: RngCore + ?Sized> RngCore for Box<R> {
     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/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>