Merge branch 'master' into isaac_init

Author: pitdicker

benches/distributions.rs

@@ -25,25 +25,12 @@ fn distr_baseline(b: &mut Bencher) {
     b.bytes = size_of::<u64>() as u64 * ::RAND_BENCH_N;
 }
 
-#[bench]
-fn distr_range_int(b: &mut Bencher) {
-    let mut rng = XorShiftRng::new().unwrap();
-    let distr = Range::new(3i64, 134217671i64);
-
-    b.iter(|| {
-        for _ in 0..::RAND_BENCH_N {
-            black_box(distr.sample(&mut rng));
-        }
-    });
-    b.bytes = size_of::<i64>() as u64 * ::RAND_BENCH_N;
-}
-
-macro_rules! distr_range2_int {
+macro_rules! distr_range_int {
     ($fnn:ident, $ty:ty, $low:expr, $high:expr) => {
         #[bench]
         fn $fnn(b: &mut Bencher) {
             let mut rng = XorShiftRng::new().unwrap();
-            let distr = range2::Range::new($low, $high);
+            let distr = Range::new($low, $high);
 
             b.iter(|| {
                 for _ in 0..::RAND_BENCH_N {
@@ -56,10 +43,10 @@ macro_rules! distr_range2_int {
     }
 }
 
-distr_range2_int!(distr_range2_i8, i8, 20i8, 100);
-distr_range2_int!(distr_range2_i16, i16, -500i16, 2000);
-distr_range2_int!(distr_range2_i32, i32, -200_000_000i32, 800_000_000);
-distr_range2_int!(distr_range2_i64, i64, 3i64, 134217671);
+distr_range_int!(distr_range_i8, i8, 20i8, 100);
+distr_range_int!(distr_range_i16, i16, -500i16, 2000);
+distr_range_int!(distr_range_i32, i32, -200_000_000i32, 800_000_000);
+distr_range_int!(distr_range_i64, i64, 3i64, 134217671);
 
 macro_rules! distr_float {
     ($fnn:ident, $distr:expr) => {
@@ -83,7 +70,6 @@ distr_float!(distr_uniform01_float, Uniform01);
 distr_float!(distr_closed01_float, Closed01);
 distr_float!(distr_open01_float, Open01);
 distr_float!(distr_range_float, Range::new(2.26f64, 2.319f64));
-distr_float!(distr_range2_float, range2::Range::new(2.26f64, 2.319f64));
 distr_float!(distr_exp, Exp::new(2.71828 * 3.14159));
 distr_float!(distr_normal, Normal::new(-2.71828, 3.14159));
 distr_float!(distr_log_normal, LogNormal::new(-2.71828, 3.14159));

rand_core/src/impls.rs

@@ -24,7 +24,7 @@
 //! TODO: should we add more implementations?
 
 use core::intrinsics::transmute;
-use {Rng, Result};
+use Rng;
 
 /// Implement `next_u64` via `next_u32`, little-endian order.
 pub fn next_u64_via_u32<R: Rng+?Sized>(rng: &mut R) -> u64 {
@@ -45,7 +45,7 @@ pub fn next_u128_via_u64<R: Rng+?Sized>(rng: &mut R) -> u128 {
     (y << 64) | x
 }
 
-macro_rules! try_fill_via {
+macro_rules! fill_bytes_via {
     ($rng:ident, $next_u:ident, $BYTES:expr, $dest:ident) => {{
         let mut left = $dest;
         while left.len() >= $BYTES {
@@ -63,24 +63,46 @@ macro_rules! try_fill_via {
             };
             left.copy_from_slice(&chunk[..n]);
         }
-        Ok(())
     }}
 }
 
-/// Implement `try_fill` via `next_u32`, little-endian order.
-pub fn try_fill_via_u32<R: Rng+?Sized>(rng: &mut R, dest: &mut [u8]) -> Result<()> {
-    try_fill_via!(rng, next_u32, 4, dest)
+/// Implement `fill_bytes` via `next_u32`, little-endian order.
+pub fn fill_bytes_via_u32<R: Rng+?Sized>(rng: &mut R, dest: &mut [u8]) {
+    fill_bytes_via!(rng, next_u32, 4, dest)
 }
 
-/// Implement `try_fill` via `next_u64`, little-endian order.
-pub fn try_fill_via_u64<R: Rng+?Sized>(rng: &mut R, dest: &mut [u8]) -> Result<()> {
-    try_fill_via!(rng, next_u64, 8, dest)
+/// Implement `fill_bytes` via `next_u64`, little-endian order.
+pub fn fill_bytes_via_u64<R: Rng+?Sized>(rng: &mut R, dest: &mut [u8]) {
+    fill_bytes_via!(rng, next_u64, 8, dest)
 }
 
-/// Implement `try_fill` via `next_u128`, little-endian order.
+/// Implement `fill_bytes` via `next_u128`, little-endian order.
 #[cfg(feature = "i128_support")]
-pub fn try_fill_via_u128<R: Rng+?Sized>(rng: &mut R, dest: &mut [u8]) -> Result<()> {
-    try_fill_via!(rng, next_u128, 16, dest)
+pub fn fill_bytes_via_u128<R: Rng+?Sized>(rng: &mut R, dest: &mut [u8]) {
+    fill_bytes_via!(rng, next_u128, 16, dest)
+}
+
+macro_rules! impl_uint_from_fill {
+    ($self:expr, $ty:ty, $N:expr) => ({
+        // Transmute and convert from LE (i.e. byte-swap on BE)
+        debug_assert!($N == ::core::mem::size_of::<$ty>());
+        let mut buf = [0u8; $N];
+        $self.fill_bytes(&mut buf);
+        unsafe{ *(buf.as_ptr() as *const $ty) }.to_le()
+    });
+}
+
+pub fn next_u32_via_fill<R: Rng+?Sized>(rng: &mut R) -> u32 {
+    impl_uint_from_fill!(rng, u32, 4)
+}
+
+pub fn next_u64_via_fill<R: Rng+?Sized>(rng: &mut R) -> u64 {
+    impl_uint_from_fill!(rng, u64, 8)
+}
+
+#[cfg(feature = "i128_support")]
+pub fn next_u128_via_fill<R: Rng+?Sized>(rng: &mut R) -> u128 {
+    impl_uint_from_fill!(rng, u128, 16)
 }
 
 // TODO: implement tests for the above

rand_core/src/lib.rs

@@ -20,8 +20,8 @@
 //! `SeedFromRng` and `SeedableRng` are extension traits for construction and
 //! reseeding.
 //! 
-//! `Error` and `Result` are provided for error-handling. They are safe to use
-//! in `no_std` environments.
+//! `Error` is provided for error-handling. It is safe to use in `no_std`
+//! environments.
 //! 
 //! The `impls` sub-module includes a few small functions to assist
 //! implementation of `Rng`. Since this module is only of interest to `Rng`
@@ -43,6 +43,8 @@
 #[cfg(feature="std")]
 extern crate core;
 
+use core::fmt;
+
 pub mod impls;
 pub mod mock;
 
@@ -89,16 +91,29 @@ pub trait Rng {
     /// Return the next random u128.
     #[cfg(feature = "i128_support")]
     fn next_u128(&mut self) -> u128;
-    
+
+    /// Fill `dest` entirely with random data.
+    ///
+    /// This method does *not* have any requirement on how much of the
+    /// generated random number stream is consumed; e.g. `fill_bytes_via_u64`
+    /// implementation uses `next_u64` thus consuming 8 bytes even when only
+    /// 1 is required. A different implementation might use `next_u32` and
+    /// only consume 4 bytes; *however* any change affecting *reproducibility*
+    /// of output must be considered a breaking change.
+    fn fill_bytes(&mut self, dest: &mut [u8]);
+
     /// Fill `dest` entirely with random data.
     ///
+    /// If a RNG can encounter an error, this is the only method that reports
+    /// it. The other methods either handle the error, or panic.
+    ///
     /// This method does *not* have any requirement on how much of the
     /// generated random number stream is consumed; e.g. `try_fill_via_u64`
     /// implementation uses `next_u64` thus consuming 8 bytes even when only
     /// 1 is required. A different implementation might use `next_u32` and
     /// only consume 4 bytes; *however* any change affecting *reproducibility*
     /// of output must be considered a breaking change.
-    fn try_fill(&mut self, dest: &mut [u8]) -> Result<()>;
+    fn try_fill(&mut self, dest: &mut [u8]) -> Result<(), Error>;
 }
 
 impl<'a, R: Rng+?Sized> Rng for &'a mut R {
@@ -115,7 +130,11 @@ impl<'a, R: Rng+?Sized> Rng for &'a mut R {
         (**self).next_u128()
     }
 
-    fn try_fill(&mut self, dest: &mut [u8]) -> Result<()> {
+    fn fill_bytes(&mut self, dest: &mut [u8]) {
+        (**self).fill_bytes(dest)
+    }
+
+    fn try_fill(&mut self, dest: &mut [u8]) -> Result<(), Error> {
         (**self).try_fill(dest)
     }
 }
@@ -135,7 +154,11 @@ impl<R: Rng+?Sized> Rng for Box<R> {
         (**self).next_u128()
     }
 
-    fn try_fill(&mut self, dest: &mut [u8]) -> Result<()> {
+    fn fill_bytes(&mut self, dest: &mut [u8]) {
+        (**self).fill_bytes(dest)
+    }
+
+    fn try_fill(&mut self, dest: &mut [u8]) -> Result<(), Error> {
         (**self).try_fill(dest)
     }
 }
@@ -158,10 +181,9 @@ pub trait SeedFromRng: Sized {
     /// hand, seeding a simple numerical generator from another of the same
     /// type sometimes has serious side effects such as effectively cloning the
     /// generator.
-    fn from_rng<R: Rng+?Sized>(rng: &mut R) -> Result<Self>;
+    fn from_rng<R: Rng+?Sized>(rng: &mut R) -> Result<Self, Error>;
 }
 
-
 /// A random number generator that can be explicitly seeded to produce
 /// the same stream of randomness multiple times.
 /// 
@@ -180,21 +202,71 @@ pub trait SeedableRng<Seed>: Rng {
 }
 
 
-/// Error type for cryptographic generators. Technically external generators
-/// such as the operating system or hardware generators could fail. A PRNG
-/// (algorithm) could also fail if it detects cycles, though most PRNGs have
-/// sufficiently long cycles that looping is not usually feasible.
-/// 
-/// TODO: how should error details be reported?
-#[derive(Debug)]
-pub struct Error;
+/// Error kind which can be matched over.
+#[derive(PartialEq, Eq, Debug, Copy, Clone)]
+pub enum ErrorKind {
+    /// Permanent failure: likely not recoverable without user action.
+    Unavailable,
+    /// Temporary failure: recommended to retry a few times, but may also be
+    /// irrecoverable.
+    Transient,
+    /// Not ready yet: recommended to try again a little later.
+    NotReady,
+    /// Uncategorised error
+    Other,
+    #[doc(hidden)]
+    __Nonexhaustive,
+}
 
 #[cfg(feature="std")]
-impl From<::std::io::Error> for Error {
-    fn from(_: ::std::io::Error) -> Error {
-        Error
+#[derive(Debug)]
+pub struct Error {
+    pub kind: ErrorKind,
+    pub cause: Option<Box<std::error::Error>>,
+}
+
+#[cfg(not(feature="std"))]
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Error {
+    pub kind: ErrorKind,
+    pub cause: Option<&'static str>,
+}
+
+impl Error {
+    #[cfg(feature="std")]
+    pub fn new(kind: ErrorKind, cause: Option<Box<std::error::Error>>) -> Error {
+        Error {
+            kind: kind,
+            cause: cause,
+        }
     }
 }
 
-/// Result type (convenience type-def)
-pub type Result<T> = ::std::result::Result<T, Error>;
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match self.kind {
+            ErrorKind::Unavailable => write!(f, "RNG not available."),
+            ErrorKind::Transient => write!(f, "RNG has failed, probably temporary."),
+            ErrorKind::NotReady => write!(f, "RNG not ready yet."),
+            ErrorKind::Other => write!(f, "An unspecified RNG error occurred."),
+            ErrorKind::__Nonexhaustive => unreachable!(),
+        }
+    }
+}
+
+#[cfg(feature="std")]
+impl ::std::error::Error for Error {
+    fn description(&self) -> &str {
+        match self.kind {
+            ErrorKind::Unavailable => "not available",
+            ErrorKind::Transient => "temporary failure",
+            ErrorKind::NotReady => "not ready yet",
+            ErrorKind::Other => "Uncategorised rng error",
+            ErrorKind::__Nonexhaustive => unreachable!(),
+        }
+    }
+
+    fn cause(&self) -> Option<&::std::error::Error> {
+        self.cause.as_ref().map(|e| &**e)
+    }
+}

rand_core/src/mock.rs

@@ -16,7 +16,7 @@
 //! Instead maybe this should be yet another crate? Or just leave it here?
 
 use core::num::Wrapping as w;
-use {Rng, SeedableRng, impls, Result};
+use {Rng, SeedableRng, Error, impls};
 
 /// A simple implementation of `Rng`, purely for testing.
 /// Returns an arithmetic sequence (i.e. adds a constant each step).
@@ -57,8 +57,12 @@ impl Rng for MockAddRng<u32> {
         impls::next_u128_via_u64(self)
     }
 
-    fn try_fill(&mut self, dest: &mut [u8]) -> Result<()> {
-        impls::try_fill_via_u32(self, dest)
+    fn fill_bytes(&mut self, dest: &mut [u8]) {
+        impls::fill_bytes_via_u32(self, dest);
+    }
+
+    fn try_fill(&mut self, dest: &mut [u8]) -> Result<(), Error> {
+        Ok(self.fill_bytes(dest))
     }
 }
 
@@ -76,8 +80,12 @@ impl Rng for MockAddRng<u64> {
         impls::next_u128_via_u64(self)
     }
 
-    fn try_fill(&mut self, dest: &mut [u8]) -> Result<()> {
-        impls::try_fill_via_u32(self, dest)
+    fn fill_bytes(&mut self, dest: &mut [u8]) {
+        impls::fill_bytes_via_u64(self, dest);
+    }
+
+    fn try_fill(&mut self, dest: &mut [u8]) -> Result<(), Error> {
+        Ok(self.fill_bytes(dest))
     }
 }
 

src/distributions/range.rs

@@ -210,7 +210,7 @@ range_int_impl! { i16, i16, u16, i32, u32 }
 range_int_impl! { i32, i32, u32, i32, u32 }
 range_int_impl! { i64, i64, u64, i64, u64 }
 #[cfg(feature = "i128_support")]
-range_int_impl! { i128, i128, u128, u128 }
+range_int_impl! { i128, i128, u128, u128, u128 }
 range_int_impl! { isize, isize, usize, isize, usize }
 range_int_impl! { u8, i8, u8, i32, u32 }
 range_int_impl! { u16, i16, u16, i32, u32 }