Add rand_core::InfallibleRng marker trait

Author: newpavlov

rand_chacha/src/chacha.rs

@@ -14,7 +14,7 @@
 use self::core::fmt;
 use crate::guts::ChaCha;
 use rand_core::block::{BlockRng, BlockRngCore, CryptoBlockRng};
-use rand_core::{CryptoRng, Error, RngCore, SeedableRng};
+use rand_core::{CryptoRng, Error, InfallibleRng, RngCore, SeedableRng};
 
 #[cfg(feature = "serde1")] use serde::{Serialize, Deserialize, Serializer, Deserializer};
 
@@ -101,6 +101,8 @@ macro_rules! chacha_impl {
 
         impl CryptoBlockRng for $ChaChaXCore {}
 
+        impl InfallibleRng for $ChaChaXRng {}
+
         /// A cryptographically secure random number generator that uses the ChaCha algorithm.
         ///
         /// ChaCha is a stream cipher designed by Daniel J. Bernstein[^1], that we use as an RNG. It is

rand_core/src/lib.rs

@@ -212,6 +212,14 @@ pub trait RngCore {
 /// [`BlockRngCore`]: block::BlockRngCore
 pub trait CryptoRng: RngCore {}
 
+/// A marker trait used to indicate that an [`RngCore`] implementation is
+/// supposed to never return errors from the [`RngCore::try_fill_bytes`] method
+/// and never panic on unwrapping [`Error`] while calling other methods.
+///
+/// This trait is usually implemented by PRNGs, as opposed to OS, hardware,
+/// and periodically-reseeded RNGs, which may fail with IO errors.
+pub trait InfallibleRng: RngCore {}
+
 /// A random number generator that can be explicitly seeded.
 ///
 /// This trait encapsulates the low-level functionality common to all

rand_pcg/src/pcg128.rs

@@ -14,7 +14,7 @@
 const MULTIPLIER: u128 = 0x2360_ED05_1FC6_5DA4_4385_DF64_9FCC_F645;
 
 use core::fmt;
-use rand_core::{impls, le, Error, RngCore, SeedableRng};
+use rand_core::{impls, le, Error, InfallibleRng, RngCore, SeedableRng};
 #[cfg(feature = "serde1")] use serde::{Deserialize, Serialize};
 
 /// A PCG random number generator (XSL RR 128/64 (LCG) variant).
@@ -159,6 +159,7 @@ impl RngCore for Lcg128Xsl64 {
     }
 }
 
+impl InfallibleRng for Lcg128Xsl64 {}
 
 /// A PCG random number generator (XSL 128/64 (MCG) variant).
 ///
@@ -269,6 +270,8 @@ impl RngCore for Mcg128Xsl64 {
     }
 }
 
+impl InfallibleRng for Mcg128Xsl64 {}
+
 #[inline(always)]
 fn output_xsl_rr(state: u128) -> u64 {
     // Output function XSL RR ("xorshift low (bits), random rotation")

rand_pcg/src/pcg128cm.rs

@@ -14,7 +14,7 @@
 const MULTIPLIER: u64 = 15750249268501108917;
 
 use core::fmt;
-use rand_core::{impls, le, Error, RngCore, SeedableRng};
+use rand_core::{impls, le, Error, InfallibleRng, RngCore, SeedableRng};
 #[cfg(feature = "serde1")] use serde::{Deserialize, Serialize};
 
 /// A PCG random number generator (CM DXSM 128/64 (LCG) variant).
@@ -165,6 +165,8 @@ impl RngCore for Lcg128CmDxsm64 {
     }
 }
 
+impl InfallibleRng for Lcg128CmDxsm64 {}
+
 #[inline(always)]
 fn output_dxsm(state: u128) -> u64 {
     // See https://github.com/imneme/pcg-cpp/blob/ffd522e7188bef30a00c74dc7eb9de5faff90092/include/pcg_random.hpp#L1016

rand_pcg/src/pcg64.rs

@@ -11,7 +11,7 @@
 //! PCG random number generators
 
 use core::fmt;
-use rand_core::{impls, le, Error, RngCore, SeedableRng};
+use rand_core::{impls, le, Error, InfallibleRng, RngCore, SeedableRng};
 #[cfg(feature = "serde1")] use serde::{Deserialize, Serialize};
 
 // This is the default multiplier used by PCG for 64-bit state.
@@ -167,3 +167,5 @@ impl RngCore for Lcg64Xsh32 {
         Ok(())
     }
 }
+
+impl InfallibleRng for Lcg64Xsh32 {}

src/lib.rs

@@ -92,7 +92,7 @@ macro_rules! error { ($($x:tt)*) => (
 ) }
 
 // Re-exports from rand_core
-pub use rand_core::{CryptoRng, Error, RngCore, SeedableRng};
+pub use rand_core::{CryptoRng, Error, InfallibleRng, RngCore, SeedableRng};
 
 // Public modules
 pub mod distributions;

src/rngs/mock.rs

@@ -8,7 +8,7 @@
 
 //! Mock random number generator
 
-use rand_core::{impls, Error, RngCore};
+use rand_core::{impls, Error, InfallibleRng, RngCore};
 
 #[cfg(feature = "serde1")]
 use serde::{Serialize, Deserialize};
@@ -81,6 +81,8 @@ impl RngCore for StepRng {
     }
 }
 
+impl InfallibleRng for StepRng {}
+
 #[cfg(test)]
 mod tests {
     #[cfg(any(feature = "alloc", feature = "serde1"))]

src/rngs/small.rs

@@ -8,7 +8,7 @@
 
 //! A small fast RNG
 
-use rand_core::{Error, RngCore, SeedableRng};
+use rand_core::{Error, InfallibleRng, RngCore, SeedableRng};
 
 #[cfg(target_pointer_width = "64")]
 type Rng = super::xoshiro256plusplus::Xoshiro256PlusPlus;
@@ -64,6 +64,8 @@ impl RngCore for SmallRng {
     }
 }
 
+impl InfallibleRng for SmallRng {}
+
 impl SmallRng {
     /// Construct an instance seeded from another `Rng`
     ///

src/rngs/std.rs

@@ -8,7 +8,7 @@
 
 //! The standard RNG
 
-use crate::{CryptoRng, Error, RngCore, SeedableRng};
+use rand_core::{CryptoRng, Error, InfallibleRng, RngCore, SeedableRng};
 
 #[cfg(any(test, feature = "getrandom"))]
 pub(crate) use rand_chacha::ChaCha12Core as Core;
@@ -73,6 +73,7 @@ impl SeedableRng for StdRng {
 
 impl CryptoRng for StdRng {}
 
+impl InfallibleRng for StdRng {}
 
 #[cfg(test)]
 mod test {

src/rngs/xoshiro128plusplus.rs

@@ -9,7 +9,7 @@
 #[cfg(feature="serde1")] use serde::{Serialize, Deserialize};
 use rand_core::impls::{next_u64_via_u32, fill_bytes_via_next};
 use rand_core::le::read_u32_into;
-use rand_core::{SeedableRng, RngCore, Error};
+use rand_core::{Error, InfallibleRng, RngCore, SeedableRng};
 
 /// A xoshiro128++ random number generator.
 ///
@@ -97,6 +97,8 @@ impl RngCore for Xoshiro128PlusPlus {
     }
 }
 
+impl InfallibleRng for Xoshiro128PlusPlus {}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src/rngs/xoshiro256plusplus.rs

@@ -9,7 +9,7 @@
 #[cfg(feature="serde1")] use serde::{Serialize, Deserialize};
 use rand_core::impls::fill_bytes_via_next;
 use rand_core::le::read_u64_into;
-use rand_core::{SeedableRng, RngCore, Error};
+use rand_core::{Error, InfallibleRng, RngCore, SeedableRng};
 
 /// A xoshiro256++ random number generator.
 ///
@@ -99,6 +99,8 @@ impl RngCore for Xoshiro256PlusPlus {
     }
 }
 
+impl InfallibleRng for Xoshiro256PlusPlus {}
+
 #[cfg(test)]
 mod tests {
     use super::*;