Associated error type for RngCore

rand-core/src/error.rs

@@ -161,3 +161,19 @@ impl stdError for Error {
         self.cause.as_ref().map(|e| e.as_ref() as &stdError)
     }
 }
+
+/// Void error type, for use when errors are statically impossible.
+#[derive(Debug)]
+pub enum Void {}
+
+impl fmt::Display for Void {
+    fn fmt(&self, _f: &mut fmt::Formatter) -> fmt::Result {
+        unreachable!()
+    }
+}
+
+impl From<Void> for Error {
+    fn from(_self: Void) -> Error {
+        unreachable!()
+    }
+}

rand-core/src/impls.rs

@@ -25,7 +25,7 @@ use core::ptr::copy_nonoverlapping;
 use core::{fmt, slice};
 use core::cmp::min;
 use core::mem::size_of;
-use {RngCore, BlockRngCore, CryptoRng, SeedableRng, Error};
+use {RngCore, BlockRngCore, CryptoRng, SeedableRng};
 
 /// Implement `next_u64` via `next_u32`, little-endian order.
 pub fn next_u64_via_u32<R: RngCore + ?Sized>(rng: &mut R) -> u64 {
@@ -204,10 +204,13 @@ impl<R: BlockRngCore + fmt::Debug> fmt::Debug for BlockRng<R> {
 impl<R: BlockRngCore<Item=u32>> RngCore for BlockRng<R>
 where <R as BlockRngCore>::Results: AsRef<[u32]>
 {
+    type Error = <R as BlockRngCore>::Error;
+
     #[inline(always)]
     fn next_u32(&mut self) -> u32 {
         if self.index >= self.results.as_ref().len() {
-            self.core.generate(&mut self.results);
+            self.core.generate(&mut self.results).unwrap_or_else(|err|
+                panic!("BlockRng: error generating results: {}", err));
             self.index = 0;
         }
 
@@ -237,23 +240,30 @@ where <R as BlockRngCore>::Results: AsRef<[u32]>
             // Read an u64 from the current index
             read_u64(self.results.as_ref(), index)
         } else if index >= len {
-            self.core.generate(&mut self.results);
+            self.core.generate(&mut self.results).unwrap_or_else(|err|
+                panic!("BlockRng: error generating results: {}", err));
             self.index = 2;
             read_u64(self.results.as_ref(), 0)
         } else {
             let x = self.results.as_ref()[len-1] as u64;
-            self.core.generate(&mut self.results);
+            self.core.generate(&mut self.results).unwrap_or_else(|err|
+                panic!("BlockRng: error generating results: {}", err));
             self.index = 1;
             let y = self.results.as_ref()[0] as u64;
             (y << 32) | x
         }
     }
+
+    fn fill_bytes(&mut self, dest: &mut [u8]) {
+        self.try_fill_bytes(dest).unwrap_or_else(|err|
+                panic!("BlockRng: error generating results: {}", err));
+    }
 
     // As an optimization we try to write directly into the output buffer.
     // This is only enabled for little-endian platforms where unaligned writes
     // are known to be safe and fast.
     #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
-    fn fill_bytes(&mut self, dest: &mut [u8]) {
+    fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Self::Error> {
         let mut filled = 0;
 
         // Continue filling from the current set of results
@@ -274,27 +284,29 @@ where <R as BlockRngCore>::Results: AsRef<[u32]>
             let dest_u32: &mut R::Results = unsafe {
                 ::core::mem::transmute(dest[filled..].as_mut_ptr())
             };
-            self.core.generate(dest_u32);
+            self.core.generate(dest_u32)?;
             filled += self.results.as_ref().len() * 4;
         }
         self.index = self.results.as_ref().len();
 
         if len_remainder > 0 {
-            self.core.generate(&mut self.results);
+            self.core.generate(&mut self.results)?;
             let (consumed_u32, _) =
                 fill_via_u32_chunks(&mut self.results.as_ref(),
                                     &mut dest[filled..]);
 
             self.index = consumed_u32;
         }
+
+        Ok(())
     }
 
     #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
-    fn fill_bytes(&mut self, dest: &mut [u8]) {
+    fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Self::Error> {
         let mut read_len = 0;
         while read_len < dest.len() {
             if self.index >= self.results.as_ref().len() {
-                self.core.generate(&mut self.results);
+                self.core.generate(&mut self.results)?;
                 self.index = 0;
             }
             let (consumed_u32, filled_u8) =
@@ -304,10 +316,8 @@ where <R as BlockRngCore>::Results: AsRef<[u32]>
             self.index += consumed_u32;
             read_len += filled_u8;
         }
-    }
-
-    fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
-        Ok(self.fill_bytes(dest))
+
+        Ok(())
     }
 }
 
@@ -323,7 +333,7 @@ impl<R: BlockRngCore + SeedableRng> SeedableRng for BlockRng<R> {
         }
     }
 
-    fn from_rng<RNG: RngCore>(rng: &mut RNG) -> Result<Self, Error> {
+    fn from_rng<RNG: RngCore>(rng: &mut RNG) -> Result<Self, <RNG as RngCore>::Error> {
         let results_empty = R::Results::default();
         Ok(Self {
             core: R::from_rng(rng)?,

rand-core/src/lib.rs

@@ -43,10 +43,11 @@
 
 use core::default::Default;
 use core::convert::AsMut;
+use core::fmt::Display;
 
 #[cfg(all(feature="alloc", not(feature="std")))] use alloc::boxed::Box;
 
-pub use error::{ErrorKind, Error};
+pub use error::{ErrorKind, Error, Void};
 
 
 mod error;
@@ -86,11 +87,13 @@ pub mod le;
 /// A simple example, obviously not generating very *random* output:
 /// 
 /// ```rust
-/// use rand_core::{RngCore, Error, impls};
+/// use rand_core::{RngCore, Void, impls};
 /// 
 /// struct CountingRng(u64);
 /// 
 /// impl RngCore for CountingRng {
+///     type Error = Void;
+/// 
 ///     fn next_u32(&mut self) -> u32 {
 ///         self.next_u64() as u32
 ///     }
@@ -104,7 +107,7 @@ pub mod le;
 ///         impls::fill_bytes_via_u64(self, dest)
 ///     }
 ///     
-///     fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
+///     fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Void> {
 ///         Ok(self.fill_bytes(dest))
 ///     }
 /// }
@@ -114,6 +117,10 @@ pub mod le;
 /// [`Rng`]: https://docs.rs/rand/0.5/rand/trait.Rng.html
 /// [`impls`]: impls/index.html
 pub trait RngCore {
+    /// Error type. May be a void type (i.e. enum with no variants) if no
+    /// errors are possible.
+    type Error: Display + Into<Error>;
+
     /// Return the next random `u32`.
     ///
     /// RNGs must implement at least one method from this trait directly. In
@@ -159,7 +166,7 @@ pub trait RngCore {
     /// `self.try_fill_bytes(dest).unwrap()` or more specific error handling.
     /// 
     /// [`fill_bytes`]: trait.RngCore.html#method.fill_bytes
-    fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>;
+    fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Self::Error>;
 }
 
 /// A trait for RNGs which do not generate random numbers individually, but in
@@ -201,15 +208,24 @@ pub trait RngCore {
 /// type MyRng = BlockRng<u32, MyRngCore>;
 /// ```
 pub trait BlockRngCore {
-    /// Results element type, e.g. `u32`.
+    /// Results element type, e.g. `u32`. [`BlockRng`] must have a
+    /// corresponding impl of `RngCore` for the item type, which means
+    /// currently only `u32` is supported.
+    /// 
+    /// [`BlockRng`]: impls/struct.BlockRng.html
     type Item;
 
     /// Results type. This is the 'block' an RNG implementing `BlockRngCore`
     /// generates, which will usually be an array like `[u32; 16]`.
     type Results: AsRef<[Self::Item]> + Default;
+
+    /// Error type. May be a void type (i.e. enum with no variants) if no
+    /// errors are possible.
+    type Error: Display + Into<Error>;
 
     /// Generate a new block of results.
-    fn generate(&mut self, results: &mut Self::Results);
+    fn generate(&mut self, results: &mut Self::Results)
+            -> Result<(), Self::Error>;
 }
 
 /// A marker trait used to indicate that an `RngCore` or `BlockRngCore`
@@ -304,7 +320,7 @@ pub trait SeedableRng: Sized {
     /// [`NewRng`]: https://docs.rs/rand/0.5/rand/trait.NewRng.html
     /// [`OsRng`]: https://docs.rs/rand/0.5/rand/os/struct.OsRng.html
     /// [`XorShiftRng`]: https://docs.rs/rand/0.5/rand/prng/xorshift/struct.XorShiftRng.html
-    fn from_rng<R: RngCore>(rng: &mut R) -> Result<Self, Error> {
+    fn from_rng<R: RngCore>(rng: &mut R) -> Result<Self, <R as RngCore>::Error> {
         let mut seed = Self::Seed::default();
         rng.try_fill_bytes(seed.as_mut())?;
         Ok(Self::from_seed(seed))
@@ -313,6 +329,8 @@ pub trait SeedableRng: Sized {
 
 
 impl<'a, R: RngCore + ?Sized> RngCore for &'a mut R {
+    type Error = <R as RngCore>::Error;
+
     #[inline(always)]
     fn next_u32(&mut self) -> u32 {
         (**self).next_u32()
@@ -327,13 +345,15 @@ impl<'a, R: RngCore + ?Sized> RngCore for &'a mut R {
         (**self).fill_bytes(dest)
     }
 
-    fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
+    fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Self::Error> {
         (**self).try_fill_bytes(dest)
     }
 }
 
 #[cfg(any(feature="std", feature="alloc"))]
 impl<R: RngCore + ?Sized> RngCore for Box<R> {
+    type Error = <R as RngCore>::Error;
+
     #[inline(always)]
     fn next_u32(&mut self) -> u32 {
         (**self).next_u32()
@@ -348,7 +368,7 @@ impl<R: RngCore + ?Sized> RngCore for Box<R> {
         (**self).fill_bytes(dest)
     }
 
-    fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
+    fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Self::Error> {
         (**self).try_fill_bytes(dest)
     }
 }

src/distributions/mod.rs

@@ -173,11 +173,11 @@ impl<'a, T, D: Distribution<T>> Distribution<T> for &'a D {
 /// With dynamic dispatch (type erasure of `Rng`):
 /// 
 /// ```rust
-/// use rand::{thread_rng, Rng, RngCore};
+/// use rand::{thread_rng, Rng, RngCore, Void};
 /// use rand::distributions::Uniform;
 ///
 /// let mut rng = thread_rng();
-/// let mut erased_rng: &mut RngCore = &mut rng;
+/// let mut erased_rng: &mut RngCore<Error=Void> = &mut rng;
 /// let val: f32 = erased_rng.sample(Uniform);
 /// println!("f32 from [0,1): {}", val);
 /// ```

src/distributions/other.rs

@@ -160,12 +160,12 @@ impl<T> Distribution<Option<T>> for Uniform where Uniform: Distribution<T> {
 
 #[cfg(test)]
 mod tests {
-    use {Rng, RngCore, Uniform};
+    use {Rng, RngCore, Uniform, Void};
     #[cfg(all(not(feature="std"), feature="alloc"))] use alloc::String;
 
     #[test]
     fn test_misc() {
-        let mut rng: &mut RngCore = &mut ::test::rng(820);
+        let mut rng: &mut RngCore<Error=Void> = &mut ::test::rng(820);
 
         rng.sample::<char, _>(Uniform);
         rng.sample::<bool, _>(Uniform);

src/entropy_rng.rs

@@ -52,6 +52,8 @@ impl EntropyRng {
 }
 
 impl RngCore for EntropyRng {
+    type Error = Error;
+
     fn next_u32(&mut self) -> u32 {
         impls::next_u32_via_fill(self)
     }

src/jitter.rs

@@ -752,6 +752,8 @@ fn black_box<T>(dummy: T) -> T {
 }
 
 impl RngCore for JitterRng {
+    type Error = Error;
+
     fn next_u32(&mut self) -> u32 {
         // We want to use both parts of the generated entropy
         if self.data_half_used {