Debian Codegraph @

.cargo/vendor/rand/src/rngs/mod.rs

raw
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 //! Random number generators and adapters
10 //!
11 //! This crate provides a small selection of non-[portable] generators.
12 //! See also [Types of generators] and [Our RNGs] in the book.
13 //!
14 //! ## Generators
15 //!
16 //! This crate provides a small selection of non-[portable] random number generators:
17 //!
18 //! - [`OsRng`] is a stateless interface over the operating system's random number
19 //! source. This is typically secure with some form of periodic re-seeding.
20 //! - [`ThreadRng`], provided by [`crate::rng()`], is a handle to a
21 //! thread-local generator with periodic seeding from [`OsRng`]. Because this
22 //! is local, it is typically much faster than [`OsRng`]. It should be
23 //! secure, but see documentation on [`ThreadRng`].
24 //! - [`StdRng`] is a CSPRNG chosen for good performance and trust of security
25 //! (based on reviews, maturity and usage). The current algorithm is ChaCha12,
26 //! which is well established and rigorously analysed.
27 //! [`StdRng`] is the deterministic generator used by [`ThreadRng`] but
28 //! without the periodic reseeding or thread-local management.
29 //! - [`SmallRng`] is a relatively simple, insecure generator designed to be
30 //! fast, use little memory, and pass various statistical tests of
31 //! randomness quality.
32 //!
33 //! The algorithms selected for [`StdRng`] and [`SmallRng`] may change in any
34 //! release and may be platform-dependent, therefore they are not
35 //! [reproducible][portable].
36 //!
37 //! ### Additional generators
38 //!
39 //! - The [`rdrand`] crate provides an interface to the RDRAND and RDSEED
40 //! instructions available in modern Intel and AMD CPUs.
41 //! - The [`rand_jitter`] crate provides a user-space implementation of
42 //! entropy harvesting from CPU timer jitter, but is very slow and has
43 //! [security issues](https://github.com/rust-random/rand/issues/699).
44 //! - The [`rand_chacha`] crate provides [portable] implementations of
45 //! generators derived from the [ChaCha] family of stream ciphers
46 //! - The [`rand_pcg`] crate provides [portable] implementations of a subset
47 //! of the [PCG] family of small, insecure generators
48 //! - The [`rand_xoshiro`] crate provides [portable] implementations of the
49 //! [xoshiro] family of small, insecure generators
50 //!
51 //! For more, search [crates with the `rng` tag].
52 //!
53 //! ## Traits and functionality
54 //!
55 //! All generators implement [`RngCore`] and thus also [`Rng`][crate::Rng].
56 //! See also the [Random Values] chapter in the book.
57 //!
58 //! Secure RNGs may additionally implement the [`CryptoRng`] trait.
59 //!
60 //! Use the [`rand_core`] crate when implementing your own RNGs.
61 //!
62 //! [portable]: https://rust-random.github.io/book/crate-reprod.html
63 //! [Types of generators]: https://rust-random.github.io/book/guide-gen.html
64 //! [Our RNGs]: https://rust-random.github.io/book/guide-rngs.html
65 //! [Random Values]: https://rust-random.github.io/book/guide-values.html
66 //! [`Rng`]: crate::Rng
67 //! [`RngCore`]: crate::RngCore
68 //! [`CryptoRng`]: crate::CryptoRng
69 //! [`SeedableRng`]: crate::SeedableRng
70 //! [`rdrand`]: https://crates.io/crates/rdrand
71 //! [`rand_jitter`]: https://crates.io/crates/rand_jitter
72 //! [`rand_chacha`]: https://crates.io/crates/rand_chacha
73 //! [`rand_pcg`]: https://crates.io/crates/rand_pcg
74 //! [`rand_xoshiro`]: https://crates.io/crates/rand_xoshiro
75 //! [crates with the `rng` tag]: https://crates.io/keywords/rng
76 //! [chacha]: https://cr.yp.to/chacha.html
77 //! [PCG]: https://www.pcg-random.org/
78 //! [xoshiro]: https://prng.di.unimi.it/
79
80 mod reseeding;
81 pub use reseeding::ReseedingRng;
82
83 #[deprecated(since = "0.9.2")]
84 pub mod mock; // Public so we don't export `StepRng` directly, making it a bit
85 // more clear it is intended for testing.
86
87 #[cfg(feature = "small_rng")]
88 mod small;
89 #[cfg(all(
90 feature = "small_rng",
91 any(target_pointer_width = "32", target_pointer_width = "16")
92 ))]
93 mod xoshiro128plusplus;
94 #[cfg(all(feature = "small_rng", target_pointer_width = "64"))]
95 mod xoshiro256plusplus;
96
97 #[cfg(feature = "std_rng")]
98 mod std;
99 #[cfg(feature = "thread_rng")]
100 pub(crate) mod thread;
101
102 #[cfg(feature = "small_rng")]
103 pub use self::small::SmallRng;
104 #[cfg(feature = "std_rng")]
105 pub use self::std::StdRng;
106 #[cfg(feature = "thread_rng")]
107 pub use self::thread::ThreadRng;
108
109 #[cfg(feature = "os_rng")]
110 pub use rand_core::OsRng;