Uniform sampling: use Canon's method

.github/workflows/test.yml

@@ -79,13 +79,13 @@ jobs:
         run: |
           cargo test --target ${{ matrix.target }} --features=nightly
           cargo test --target ${{ matrix.target }} --all-features
-          cargo test --target ${{ matrix.target }} --benches --features=nightly
+          cargo test --target ${{ matrix.target }} --benches --features=small_rng,nightly
           cargo test --target ${{ matrix.target }} --manifest-path rand_distr/Cargo.toml --benches
           cargo test --target ${{ matrix.target }} --lib --tests --no-default-features
       - name: Test rand
         run: |
           cargo test --target ${{ matrix.target }} --lib --tests --no-default-features
-          cargo build --target ${{ matrix.target }} --no-default-features --features alloc,getrandom,small_rng
+          cargo build --target ${{ matrix.target }} --no-default-features --features alloc,getrandom,small_rng,unbiased
           cargo test --target ${{ matrix.target }} --lib --tests --no-default-features --features=alloc,getrandom,small_rng
           cargo test --target ${{ matrix.target }} --examples
       - name: Test rand (all stable features)

CHANGELOG.md

@@ -12,6 +12,7 @@ You may also find the [Upgrade Guide](https://rust-random.github.io/book/update.
 ### Distributions
 - `{Uniform, UniformSampler}::{new, new_inclusive}` return a `Result` (instead of potentially panicking) (#1229)
 - `Uniform` implements `TryFrom` instead of `From` for ranges (#1229)
+- `Uniform` now uses Canon's method (single sampling) / Lemire's method (distribution sampling) for faster sampling (breaks value stability; #1287)
 
 ### Other
 - Simpler and faster implementation of Floyd's F2 (#1277). This

Cargo.toml

@@ -51,6 +51,11 @@ std_rng = ["rand_chacha"]
 # Option: enable SmallRng
 small_rng = []
 
+# Option: use unbiased sampling for algorithms supporting this option: Uniform distribution.
+# By default, bias affecting no more than one in  2^48 samples is accepted.
+# Note: enabling this option is expected to affect reproducibility of results.
+unbiased = []
+
 [workspace]
 members = [
     "rand_core",
@@ -76,6 +81,10 @@ bincode = "1.2.1"
 rayon = "1.5.3"
 criterion = { version = "0.4" }
 
+[[bench]]
+name = "uniform"
+harness = false
+
 [[bench]]
 name = "seq_choose"
 path = "benches/seq_choose.rs"
@@ -84,4 +93,4 @@ harness = false
 [[bench]]
 name = "shuffle"
 path = "benches/shuffle.rs"
-harness = false
+harness = false

benches/uniform.rs

@@ -0,0 +1,78 @@
+// Copyright 2021 Developers of the Rand project.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+//! Implement benchmarks for uniform distributions over integer types
+
+use core::time::Duration;
+use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion};
+use rand::distributions::uniform::{SampleRange, Uniform};
+use rand::prelude::*;
+use rand_chacha::ChaCha8Rng;
+use rand_pcg::{Pcg32, Pcg64};
+
+const WARM_UP_TIME: Duration = Duration::from_millis(1000);
+const MEASUREMENT_TIME: Duration = Duration::from_secs(3);
+const SAMPLE_SIZE: usize = 100_000;
+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_entropy();
+            let x = rng.gen::<$U>();
+            let bits = (<$T>::BITS / 2);
+            let mask = (1 as $U).wrapping_neg() >> bits;
+            let range = (x >> bits) * (x & mask);
+            let low = <$T>::MIN;
+            let high = low.wrapping_add(range as $T);
+
+            b.iter(|| (low..=high).sample_single(&mut rng));
+        });
+
+        $g.bench_function(BenchmarkId::new(stringify!($R), "distr"), |b| {
+            let mut rng = <$R>::from_entropy();
+            let x = rng.gen::<$U>();
+            let bits = (<$T>::BITS / 2);
+            let mask = (1 as $U).wrapping_neg() >> bits;
+            let range = (x >> bits) * (x & mask);
+            let low = <$T>::MIN;
+            let high = low.wrapping_add(range as $T);
+            let dist = Uniform::<$T>::new_inclusive(<$T>::MIN, high).unwrap();
+
+            b.iter(|| dist.sample(&mut rng));
+        });
+    };
+
+    ($c:expr, $T:ty, $U:ty) => {{
+        let mut g = $c.benchmark_group(concat!("sample", stringify!($T)));
+        g.sample_size(SAMPLE_SIZE);
+        g.warm_up_time(WARM_UP_TIME);
+        g.measurement_time(MEASUREMENT_TIME);
+        g.nresamples(N_RESAMPLES);
+        sample!(SmallRng, $T, $U, g);
+        sample!(ChaCha8Rng, $T, $U, g);
+        sample!(Pcg32, $T, $U, g);
+        sample!(Pcg64, $T, $U, g);
+        g.finish();
+    }};
+}
+
+fn sample(c: &mut Criterion) {
+    sample!(c, i8, u8);
+    sample!(c, i16, u16);
+    sample!(c, i32, u32);
+    sample!(c, i64, u64);
+    sample!(c, i128, u128);
+}
+
+criterion_group! {
+    name = benches;
+    config = Criterion::default();
+    targets = sample
+}
+criterion_main!(benches);