thread_rng() → rand::rng() (#1506)

- Rename `rand::thread_rng()` → `rand::rng()`
- Remove `thread_rng()` and `random()` from the prelude

Author: dhardy

CHANGELOG.md

@@ -28,6 +28,8 @@ You may also find the [Upgrade Guide](https://rust-random.github.io/book/update.
 - Implement `Distribution<u64>` for `Poisson<f64>` (#1498)
 - Limit the maximal acceptable lambda for `Poisson` to solve (#1312) (#1498)
 - Rename `Rng::gen_iter` to `random_iter` (#1500)
+- Rename `rand::thread_rng()` to `rand::rng()`, and remove from the prelude (#1506)
+- Remove `rand::random()` from the prelude (#1506)
 
 ## [0.9.0-alpha.1] - 2024-03-18
 - Add the `Slice::num_choices` method to the Slice distribution (#1402)

README.md

@@ -11,7 +11,7 @@ Rand is a Rust library supporting random generators:
 -   A standard RNG trait: [`rand_core::RngCore`](https://docs.rs/rand_core/latest/rand_core/trait.RngCore.html)
 -   Fast implementations of the best-in-class [cryptographic](https://rust-random.github.io/book/guide-rngs.html#cryptographically-secure-pseudo-random-number-generators-csprngs) and
     [non-cryptographic](https://rust-random.github.io/book/guide-rngs.html#basic-pseudo-random-number-generators-prngs) generators: [`rand::rngs`](https://docs.rs/rand/latest/rand/rngs/index.html), and more RNGs: [`rand_chacha`](https://docs.rs/rand_chacha), [`rand_xoshiro`](https://docs.rs/rand_xoshiro/), [`rand_pcg`](https://docs.rs/rand_pcg/), [rngs repo](https://github.com/rust-random/rngs/)
--   [`rand::thread_rng`](https://docs.rs/rand/latest/rand/fn.thread_rng.html) is an asymtotically-fast, reasonably secure generator available on all `std` targets
+-   [`rand::rng`](https://docs.rs/rand/latest/rand/fn.rng.html) is an asymtotically-fast, reasonably secure generator available on all `std` targets
 -   Secure seeding via the [`getrandom` crate](https://crates.io/crates/getrandom)
 
 Supporting random value generation and random processes:
@@ -78,7 +78,7 @@ Rand is built with these features enabled by default:
 -   `alloc` (implied by `std`) enables functionality requiring an allocator
 -   `getrandom` (implied by `std`) is an optional dependency providing the code
     behind `rngs::OsRng`
--   `std_rng` enables inclusion of `StdRng`, `thread_rng`
+-   `std_rng` enables inclusion of `StdRng`, `ThreadRng`
 
 Optionally, the following dependencies can be enabled:
 
@@ -98,7 +98,7 @@ experimental `simd_support` feature.
 Rand supports limited functionality in `no_std` mode (enabled via
 `default-features = false`). In this case, `OsRng` and `from_os_rng` are
 unavailable (unless `getrandom` is enabled), large parts of `seq` are
-unavailable (unless `alloc` is enabled), and `thread_rng` is unavailable.
+unavailable (unless `alloc` is enabled), and `ThreadRng` is unavailable.
 
 ## Portability and platform support
 

SECURITY.md

@@ -52,12 +52,12 @@ Explanation of exceptions:
 -   Jitter: `JitterRng` is used as an entropy source when the primary source
     fails; this source may not be secure against side-channel attacks, see #699.
 -   ISAAC: the [ISAAC](https://burtleburtle.net/bob/rand/isaacafa.html) RNG used
-    to implement `thread_rng` is difficult to analyse and thus cannot provide
+    to implement `ThreadRng` is difficult to analyse and thus cannot provide
     strong assertions of security.
 
 ## Known issues
 
-In `rand` version 0.3 (0.3.18 and later), if `OsRng` fails, `thread_rng` is
+In `rand` version 0.3 (0.3.18 and later), if `OsRng` fails, `ThreadRng` is
 seeded from the system time in an insecure manner.
 
 ## Reporting a Vulnerability

benches/benches/array.rs

@@ -26,31 +26,31 @@ pub fn bench(c: &mut Criterion) {
 
     g.bench_function("u16_iter_repeat", |b| {
         use core::iter;
-        let mut rng = Pcg64Mcg::from_rng(&mut thread_rng());
+        let mut rng = Pcg64Mcg::from_rng(&mut rand::rng());
         b.iter(|| {
             let v: Vec<u16> = iter::repeat(()).map(|()| rng.random()).take(512).collect();
             v
         });
     });
 
     g.bench_function("u16_sample_iter", |b| {
-        let mut rng = Pcg64Mcg::from_rng(&mut thread_rng());
+        let mut rng = Pcg64Mcg::from_rng(&mut rand::rng());
         b.iter(|| {
             let v: Vec<u16> = Standard.sample_iter(&mut rng).take(512).collect();
             v
         });
     });
 
     g.bench_function("u16_gen_array", |b| {
-        let mut rng = Pcg64Mcg::from_rng(&mut thread_rng());
+        let mut rng = Pcg64Mcg::from_rng(&mut rand::rng());
         b.iter(|| {
             let v: [u16; 512] = rng.random();
             v
         });
     });
 
     g.bench_function("u16_fill", |b| {
-        let mut rng = Pcg64Mcg::from_rng(&mut thread_rng());
+        let mut rng = Pcg64Mcg::from_rng(&mut rand::rng());
         let mut buf = [0u16; 512];
         b.iter(|| {
             rng.fill(&mut buf[..]);
@@ -60,31 +60,31 @@ pub fn bench(c: &mut Criterion) {
 
     g.bench_function("u64_iter_repeat", |b| {
         use core::iter;
-        let mut rng = Pcg64Mcg::from_rng(&mut thread_rng());
+        let mut rng = Pcg64Mcg::from_rng(&mut rand::rng());
         b.iter(|| {
             let v: Vec<u64> = iter::repeat(()).map(|()| rng.random()).take(128).collect();
             v
         });
     });
 
     g.bench_function("u64_sample_iter", |b| {
-        let mut rng = Pcg64Mcg::from_rng(&mut thread_rng());
+        let mut rng = Pcg64Mcg::from_rng(&mut rand::rng());
         b.iter(|| {
             let v: Vec<u64> = Standard.sample_iter(&mut rng).take(128).collect();
             v
         });
     });
 
     g.bench_function("u64_gen_array", |b| {
-        let mut rng = Pcg64Mcg::from_rng(&mut thread_rng());
+        let mut rng = Pcg64Mcg::from_rng(&mut rand::rng());
         b.iter(|| {
             let v: [u64; 128] = rng.random();
             v
         });
     });
 
     g.bench_function("u64_fill", |b| {
-        let mut rng = Pcg64Mcg::from_rng(&mut thread_rng());
+        let mut rng = Pcg64Mcg::from_rng(&mut rand::rng());
         let mut buf = [0u64; 128];
         b.iter(|| {
             rng.fill(&mut buf[..]);

benches/benches/bool.rs

@@ -27,41 +27,41 @@ pub fn bench(c: &mut Criterion) {
     g.measurement_time(core::time::Duration::from_millis(1000));
 
     g.bench_function("standard", |b| {
-        let mut rng = Pcg32::from_rng(&mut thread_rng());
+        let mut rng = Pcg32::from_rng(&mut rand::rng());
         b.iter(|| rng.sample::<bool, _>(rand::distr::Standard))
     });
 
     g.bench_function("const", |b| {
-        let mut rng = Pcg32::from_rng(&mut thread_rng());
+        let mut rng = Pcg32::from_rng(&mut rand::rng());
         b.iter(|| rng.gen_bool(0.18))
     });
 
     g.bench_function("var", |b| {
-        let mut rng = Pcg32::from_rng(&mut thread_rng());
+        let mut rng = Pcg32::from_rng(&mut rand::rng());
         let p = rng.random();
         b.iter(|| rng.gen_bool(p))
     });
 
     g.bench_function("ratio_const", |b| {
-        let mut rng = Pcg32::from_rng(&mut thread_rng());
+        let mut rng = Pcg32::from_rng(&mut rand::rng());
         b.iter(|| rng.gen_ratio(2, 3))
     });
 
     g.bench_function("ratio_var", |b| {
-        let mut rng = Pcg32::from_rng(&mut thread_rng());
+        let mut rng = Pcg32::from_rng(&mut rand::rng());
         let d = rng.gen_range(1..=100);
         let n = rng.gen_range(0..=d);
         b.iter(|| rng.gen_ratio(n, d));
     });
 
     g.bench_function("bernoulli_const", |b| {
-        let mut rng = Pcg32::from_rng(&mut thread_rng());
+        let mut rng = Pcg32::from_rng(&mut rand::rng());
         let d = Bernoulli::new(0.18).unwrap();
         b.iter(|| rng.sample(d))
     });
 
     g.bench_function("bernoulli_var", |b| {
-        let mut rng = Pcg32::from_rng(&mut thread_rng());
+        let mut rng = Pcg32::from_rng(&mut rand::rng());
         let p = rng.random();
         let d = Bernoulli::new(p).unwrap();
         b.iter(|| rng.sample(d))

benches/benches/generators.rs

@@ -50,7 +50,7 @@ pub fn gen_bytes(c: &mut Criterion) {
     bench(&mut g, "std", StdRng::from_os_rng());
     bench(&mut g, "small", SmallRng::from_thread_rng());
     bench(&mut g, "os", UnwrapErr(OsRng));
-    bench(&mut g, "thread", thread_rng());
+    bench(&mut g, "thread", rand::rng());
 
     g.finish()
 }
@@ -79,7 +79,7 @@ pub fn gen_u32(c: &mut Criterion) {
     bench(&mut g, "std", StdRng::from_os_rng());
     bench(&mut g, "small", SmallRng::from_thread_rng());
     bench(&mut g, "os", UnwrapErr(OsRng));
-    bench(&mut g, "thread", thread_rng());
+    bench(&mut g, "thread", rand::rng());
 
     g.finish()
 }
@@ -108,7 +108,7 @@ pub fn gen_u64(c: &mut Criterion) {
     bench(&mut g, "std", StdRng::from_os_rng());
     bench(&mut g, "small", SmallRng::from_thread_rng());
     bench(&mut g, "os", UnwrapErr(OsRng));
-    bench(&mut g, "thread", thread_rng());
+    bench(&mut g, "thread", rand::rng());
 
     g.finish()
 }

benches/benches/seq_choose.rs

@@ -20,7 +20,7 @@ criterion_main!(benches);
 
 pub fn bench(c: &mut Criterion) {
     c.bench_function("seq_slice_choose_1_of_100", |b| {
-        let mut rng = Pcg32::from_rng(&mut thread_rng());
+        let mut rng = Pcg32::from_rng(&mut rand::rng());
         let mut buf = [0i32; 100];
         rng.fill(&mut buf);
         let x = black_box(&mut buf);
@@ -32,7 +32,7 @@ pub fn bench(c: &mut Criterion) {
     for (amount, len) in lens {
         let name = format!("seq_slice_choose_multiple_{}_of_{}", amount, len);
         c.bench_function(name.as_str(), |b| {
-            let mut rng = Pcg32::from_rng(&mut thread_rng());
+            let mut rng = Pcg32::from_rng(&mut rand::rng());
             let mut buf = [0i32; 1000];
             rng.fill(&mut buf);
             let x = black_box(&buf[..len]);
@@ -53,15 +53,15 @@ pub fn bench(c: &mut Criterion) {
     }
 
     c.bench_function("seq_iter_choose_multiple_10_of_100", |b| {
-        let mut rng = Pcg32::from_rng(&mut thread_rng());
+        let mut rng = Pcg32::from_rng(&mut rand::rng());
         let mut buf = [0i32; 100];
         rng.fill(&mut buf);
         let x = black_box(&buf);
         b.iter(|| x.iter().cloned().choose_multiple(&mut rng, 10))
     });
 
     c.bench_function("seq_iter_choose_multiple_fill_10_of_100", |b| {
-        let mut rng = Pcg32::from_rng(&mut thread_rng());
+        let mut rng = Pcg32::from_rng(&mut rand::rng());
         let mut buf = [0i32; 100];
         rng.fill(&mut buf);
         let x = black_box(&buf);

benches/benches/shuffle.rs

@@ -20,7 +20,7 @@ criterion_main!(benches);
 
 pub fn bench(c: &mut Criterion) {
     c.bench_function("seq_shuffle_100", |b| {
-        let mut rng = Pcg32::from_rng(&mut thread_rng());
+        let mut rng = Pcg32::from_rng(&mut rand::rng());
         let mut buf = [0i32; 100];
         rng.fill(&mut buf);
         let x = black_box(&mut buf);

benches/benches/uniform.rs

@@ -23,7 +23,7 @@ const N_RESAMPLES: usize = 10_000;
 macro_rules! sample {
     ($R:ty, $T:ty, $U:ty, $g:expr) => {
         $g.bench_function(BenchmarkId::new(stringify!($R), "single"), |b| {
-            let mut rng = <$R>::from_rng(&mut thread_rng());
+            let mut rng = <$R>::from_rng(&mut rand::rng());
             let x = rng.random::<$U>();
             let bits = (<$T>::BITS / 2);
             let mask = (1 as $U).wrapping_neg() >> bits;
@@ -35,7 +35,7 @@ macro_rules! sample {
         });
 
         $g.bench_function(BenchmarkId::new(stringify!($R), "distr"), |b| {
-            let mut rng = <$R>::from_rng(&mut thread_rng());
+            let mut rng = <$R>::from_rng(&mut rand::rng());
             let x = rng.random::<$U>();
             let bits = (<$T>::BITS / 2);
             let mask = (1 as $U).wrapping_neg() >> bits;

benches/benches/uniform_float.rs

@@ -27,7 +27,7 @@ const N_RESAMPLES: usize = 10_000;
 macro_rules! single_random {
     ($R:ty, $T:ty, $g:expr) => {
         $g.bench_function(BenchmarkId::new(stringify!($T), stringify!($R)), |b| {
-            let mut rng = <$R>::from_rng(&mut thread_rng());
+            let mut rng = <$R>::from_rng(&mut rand::rng());
             let (mut low, mut high);
             loop {
                 low = <$T>::from_bits(rng.random());
@@ -63,7 +63,7 @@ fn single_random(c: &mut Criterion) {
 macro_rules! distr_random {
     ($R:ty, $T:ty, $g:expr) => {
         $g.bench_function(BenchmarkId::new(stringify!($T), stringify!($R)), |b| {
-            let mut rng = <$R>::from_rng(&mut thread_rng());
+            let mut rng = <$R>::from_rng(&mut rand::rng());
             let dist = loop {
                 let low = <$T>::from_bits(rng.random());
                 let high = <$T>::from_bits(rng.random());

benches/benches/weighted.rs

@@ -20,7 +20,7 @@ criterion_main!(benches);
 
 pub fn bench(c: &mut Criterion) {
     c.bench_function("weighted_index_creation", |b| {
-        let mut rng = rand::thread_rng();
+        let mut rng = rand::rng();
         let weights = black_box([1u32, 2, 4, 0, 5, 1, 7, 1, 2, 3, 4, 5, 6, 7]);
         b.iter(|| {
             let distr = WeightedIndex::new(weights.to_vec()).unwrap();
@@ -29,7 +29,7 @@ pub fn bench(c: &mut Criterion) {
     });
 
     c.bench_function("weighted_index_modification", |b| {
-        let mut rng = rand::thread_rng();
+        let mut rng = rand::rng();
         let weights = black_box([1u32, 2, 3, 0, 5, 6, 7, 1, 2, 3, 4, 5, 6, 7]);
         let mut distr = WeightedIndex::new(weights.to_vec()).unwrap();
         b.iter(|| {
@@ -53,7 +53,7 @@ pub fn bench(c: &mut Criterion) {
         c.bench_function(name.as_str(), |b| {
             let length = black_box(length);
             let amount = black_box(amount);
-            let mut rng = SmallRng::from_rng(&mut thread_rng());
+            let mut rng = SmallRng::from_rng(&mut rand::rng());
             b.iter(|| sample_weighted(&mut rng, length, |idx| (1 + (idx % 100)) as u32, amount))
         });
     }

examples/monte-carlo.rs

@@ -27,7 +27,7 @@ use rand::distr::{Distribution, Uniform};
 
 fn main() {
     let range = Uniform::new(-1.0f64, 1.0).unwrap();
-    let mut rng = rand::thread_rng();
+    let mut rng = rand::rng();
 
     let total = 1_000_000;
     let mut in_circle = 0;

examples/monty-hall.rs

@@ -77,7 +77,7 @@ fn main() {
     // The estimation will be more accurate with more simulations
     let num_simulations = 10000;
 
-    let mut rng = rand::thread_rng();
+    let mut rng = rand::rng();
     let random_door = Uniform::new(0u32, 3).unwrap();
 
     let (mut switch_wins, mut switch_losses) = (0, 0);

rand_chacha/src/lib.rs

@@ -41,7 +41,7 @@
 //!     let rng = ChaCha12Rng::from_os_rng();
 //!     # let _: ChaCha12Rng = rng;
 //!     ```
-//! 2.  **From a master generator.** This could be [`rand::thread_rng`]
+//! 2.  **From a master generator.** This could be [`rand::rng`]
 //!     (effectively a fresh seed without the need for a syscall on each usage)
 //!     or a deterministic generator such as [`ChaCha20Rng`].
 //!     Beware that should a weak master generator be used, correlations may be
@@ -74,7 +74,7 @@
 //! [`RngCore`]: rand_core::RngCore
 //! [`SeedableRng`]: rand_core::SeedableRng
 //! [`SeedableRng::from_os_rng`]: rand_core::SeedableRng::from_os_rng
-//! [`rand::thread_rng`]: https://docs.rs/rand/latest/rand/fn.thread_rng.html
+//! [`rand::rng`]: https://docs.rs/rand/latest/rand/fn.rng.html
 //! [`rand::Rng`]: https://docs.rs/rand/latest/rand/trait.Rng.html
 
 #![doc(

rand_core/src/lib.rs

@@ -487,7 +487,7 @@ pub trait SeedableRng: Sized {
     ///
     /// In case the overhead of using [`getrandom`] to seed *many* PRNGs is an
     /// issue, one may prefer to seed from a local PRNG, e.g.
-    /// `from_rng(thread_rng()).unwrap()`.
+    /// `from_rng(rand::rng()).unwrap()`.
     ///
     /// # Panics
     ///
@@ -508,7 +508,7 @@ pub trait SeedableRng: Sized {
     ///
     /// In case the overhead of using [`getrandom`] to seed *many* PRNGs is an
     /// issue, one may prefer to seed from a local PRNG, e.g.
-    /// `from_rng(&mut thread_rng()).unwrap()`.
+    /// `from_rng(&mut rand::rng()).unwrap()`.
     ///
     /// [`getrandom`]: https://docs.rs/getrandom
     #[cfg(feature = "getrandom")]

rand_distr/src/beta.rs

@@ -73,7 +73,7 @@ struct BC<N> {
 /// use rand_distr::{Distribution, Beta};
 ///
 /// let beta = Beta::new(2.0, 5.0).unwrap();
-/// let v = beta.sample(&mut rand::thread_rng());
+/// let v = beta.sample(&mut rand::rng());
 /// println!("{} is from a Beta(2, 5) distribution", v);
 /// ```
 #[derive(Clone, Copy, Debug, PartialEq)]

rand_distr/src/binomial.rs

@@ -40,7 +40,7 @@ use rand::Rng;
 /// use rand_distr::{Binomial, Distribution};
 ///
 /// let bin = Binomial::new(20, 0.3).unwrap();
-/// let v = bin.sample(&mut rand::thread_rng());
+/// let v = bin.sample(&mut rand::rng());
 /// println!("{} is from a binomial distribution", v);
 /// ```
 #[derive(Clone, Copy, Debug, PartialEq)]

rand_distr/src/cauchy.rs

@@ -45,7 +45,7 @@ use rand::Rng;
 /// use rand_distr::{Cauchy, Distribution};
 ///
 /// let cau = Cauchy::new(2.0, 5.0).unwrap();
-/// let v = cau.sample(&mut rand::thread_rng());
+/// let v = cau.sample(&mut rand::rng());
 /// println!("{} is from a Cauchy(2, 5) distribution", v);
 /// ```
 ///

rand_distr/src/chi_squared.rs

@@ -41,7 +41,7 @@ use serde::{Deserialize, Serialize};
 /// use rand_distr::{ChiSquared, Distribution};
 ///
 /// let chi = ChiSquared::new(11.0).unwrap();
-/// let v = chi.sample(&mut rand::thread_rng());
+/// let v = chi.sample(&mut rand::rng());
 /// println!("{} is from a χ²(11) distribution", v)
 /// ```
 #[derive(Clone, Copy, Debug, PartialEq)]