vendor/rand/src/rngs/small.rs

   1 // Copyright 2018 Developers of the Rand project.
   2 //
   3 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   4 // https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   5 // <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
   6 // option. This file may not be copied, modified, or distributed
   7 // except according to those terms.
   8
   9 //! A small fast RNG
  10
  11 use rand_core::{Error, RngCore, SeedableRng};
  12
  13 #[cfg(all(not(target_os = "emscripten"), target_pointer_width = "64"))]
  14 type Rng = rand_pcg::Pcg64Mcg;
  15 #[cfg(not(all(not(target_os = "emscripten"), target_pointer_width = "64")))]
  16 type Rng = rand_pcg::Pcg32;
  17
  18 /// A small-state, fast non-crypto PRNG
  19 ///
  20 /// `SmallRng` may be a good choice when a PRNG with small state, cheap
  21 /// initialization, good statistical quality and good performance are required.
  22 /// It is **not** a good choice when security against prediction or
  23 /// reproducibility are important.
  24 ///
  25 /// This PRNG is **feature-gated**: to use, you must enable the crate feature
  26 /// `small_rng`.
  27 ///
  28 /// The algorithm is deterministic but should not be considered reproducible
  29 /// due to dependence on platform and possible replacement in future
  30 /// library versions. For a reproducible generator, use a named PRNG from an
  31 /// external crate, e.g. [rand_pcg] or [rand_chacha].
  32 /// Refer also to [The Book](https://rust-random.github.io/book/guide-rngs.html).
  33 ///
  34 /// The PRNG algorithm in `SmallRng` is chosen to be
  35 /// efficient on the current platform, without consideration for cryptography
  36 /// or security. The size of its state is much smaller than [`StdRng`].
  37 /// The current algorithm is [`Pcg64Mcg`](rand_pcg::Pcg64Mcg) on 64-bit
  38 /// platforms and [`Pcg32`](rand_pcg::Pcg32) on 32-bit platforms. Both are
  39 /// implemented by the [rand_pcg] crate.
  40 ///
  41 /// # Examples
  42 ///
  43 /// Initializing `SmallRng` with a random seed can be done using [`SeedableRng::from_entropy`]:
  44 ///
  45 /// ```
  46 /// use rand::{Rng, SeedableRng};
  47 /// use rand::rngs::SmallRng;
  48 ///
  49 /// // Create small, cheap to initialize and fast RNG with a random seed.
  50 /// // The randomness is supplied by the operating system.
  51 /// let mut small_rng = SmallRng::from_entropy();
  52 /// # let v: u32 = small_rng.gen();
  53 /// ```
  54 ///
  55 /// When initializing a lot of `SmallRng`'s, using [`thread_rng`] can be more
  56 /// efficient:
  57 ///
  58 /// ```
  59 /// use rand::{SeedableRng, thread_rng};
  60 /// use rand::rngs::SmallRng;
  61 ///
  62 /// // Create a big, expensive to initialize and slower, but unpredictable RNG.
  63 /// // This is cached and done only once per thread.
  64 /// let mut thread_rng = thread_rng();
  65 /// // Create small, cheap to initialize and fast RNGs with random seeds.
  66 /// // One can generally assume this won't fail.
  67 /// let rngs: Vec<SmallRng> = (0..10)
  68 ///     .map(|_| SmallRng::from_rng(&mut thread_rng).unwrap())
  69 ///     .collect();
  70 /// ```
  71 ///
  72 /// [`StdRng`]: crate::rngs::StdRng
  73 /// [`thread_rng`]: crate::thread_rng
  74 /// [rand_chacha]: https://crates.io/crates/rand_chacha
  75 /// [rand_pcg]: https://crates.io/crates/rand_pcg
  76 #[derive(Clone, Debug)]
  77 pub struct SmallRng(Rng);
  78
  79 impl RngCore for SmallRng {
  80     #[inline(always)]
  81     fn next_u32(&mut self) -> u32 {
  82         self.0.next_u32()
  83     }
  84
  85     #[inline(always)]
  86     fn next_u64(&mut self) -> u64 {
  87         self.0.next_u64()
  88     }
  89
  90     #[inline(always)]
  91     fn fill_bytes(&mut self, dest: &mut [u8]) {
  92         self.0.fill_bytes(dest);
  93     }
  94
  95     #[inline(always)]
  96     fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
  97         self.0.try_fill_bytes(dest)
  98     }
  99 }
 100
 101 impl SeedableRng for SmallRng {
 102     type Seed = <Rng as SeedableRng>::Seed;
 103
 104     #[inline(always)]
 105     fn from_seed(seed: Self::Seed) -> Self {
 106         SmallRng(Rng::from_seed(seed))
 107     }
 108
 109     #[inline(always)]
 110     fn from_rng<R: RngCore>(rng: R) -> Result<Self, Error> {
 111         Rng::from_rng(rng).map(SmallRng)
 112     }
 113 }