Always use std::hint::black_box(). (#794)

This has been stable since Rust 1.66 and our MSRV is now 1.70.

The feature is kept around for now as removing it would break
people's configurations if they were enabling it.

It can be removed at the next semver break.

Supercedes #701.
Fixes #633.
Fixes #700.

CHANGELOG.md

@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ## [Unreleased]
 - MSRV bumped to 1.70
 
+### Changed
+- The `real_blackbox` feature no longer has any impact. Criterion always uses `std::hint::black_box()` now.
+  Users of `criterion::black_box()` should switch to `std::hint::black_box()`.
+
 ### Fixed
 
 - gnuplot version is now correctly detected when using certain Windows binaries/configurations that used to fail

Cargo.toml

@@ -72,7 +72,7 @@ stable = [
 ]
 default = ["rayon", "plotters", "cargo_bench_support"]
 
-# Enable use of the nightly-only test::black_box function to discourage compiler optimizations.
+# This is a legacy feature that no longer does anything, but removing it would be a semver break.
 real_blackbox = []
 
 # Enable async/await support

README.md

@@ -63,7 +63,8 @@ harness = false
 Next, define a benchmark by creating a file at `$PROJECT/benches/my_benchmark.rs` with the following contents:
 
 ```rust
-use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use std::hint::black_box;
+use criterion::{criterion_group, criterion_main, Criterion};
 
 fn fibonacci(n: u64) -> u64 {
     match n {

bencher_compat/src/lib.rs

@@ -1,7 +1,7 @@
 extern crate criterion;
 
+pub use std::hint::black_box;
 pub use criterion::Criterion;
-pub use criterion::black_box;
 use criterion::measurement::WallTime;
 
 /// Stand-in for `bencher::Bencher` which uses Criterion.rs to perform the benchmark instead.
@@ -60,4 +60,4 @@ macro_rules! benchmark_main {
     ($($group_name:path,)+) => {
         benchmark_main!($($group_name),+);
     };
-}
+}

benches/benchmarks/custom_measurement.rs

@@ -1,8 +1,9 @@
 use criterion::{
-    black_box, criterion_group,
+    criterion_group,
     measurement::{Measurement, ValueFormatter},
     Criterion, Throughput,
 };
+use std::hint::black_box;
 use std::time::{Duration, Instant};
 
 struct HalfSecFormatter;

book/src/faq.md

@@ -77,13 +77,11 @@ To see this, consider the following benchmark:
 
 ```rust
 fn compare_small(c: &mut Criterion) {
-    use criterion::black_box;
-
     let mut group = c.benchmark_group("small");
     group.bench_with_input("unlooped", 10, |b, i| b.iter(|| i + 10));
     group.bench_with_input("looped", 10, |b, i| b.iter(|| {
         for _ in 0..10000 {
-            black_box(i + 10);
+            std::hint::black_box(i + 10);
         }
     }));
     group.finish();
@@ -111,7 +109,7 @@ Process](./analysis.md) page for more details on how Criterion.rs performs its m
 the [Timing Loops](./user_guide/timing_loops.md) page for details on choosing a timing loop to minimize
 measurement overhead.
 
-### When Should I Use `criterion::black_box`?
+### When Should I Use `std::hint::black_box`?
 
 `black_box` is a function which prevents certain compiler optimizations. Benchmarks are often
 slightly artificial in nature and the compiler can take advantage of that to generate faster code

book/src/getting_started.md

@@ -39,7 +39,8 @@ file at `$PROJECT/benches/my_benchmark.rs` with the following contents (see the
 below for an explanation of this code):
 
 ```rust
-use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use criterion::{criterion_group, criterion_main, Criterion};
+use std::hint::black_box;
 use mycrate::fibonacci;
 
 fn criterion_benchmark(c: &mut Criterion) {
@@ -78,7 +79,8 @@ median [25.733 us 25.988 us] med. abs. dev. [234.09 ns 544.07 ns]
 Let's go back and walk through that benchmark code in more detail.
 
 ```rust
-use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use criterion::{criterion_group, criterion_main, Criterion};
+use std::hint::black_box;
 use mycrate::fibonacci;
 ```
 

book/src/user_guide/comparing_functions.md

@@ -5,7 +5,8 @@ graphs to show the differences in performance between them. First, lets create a
 benchmark. We can even combine this with benchmarking over a range of inputs.
 
 ```rust
-use criterion::{black_box, criterion_group, criterion_main, Criterion, BenchmarkId};
+use criterion::{criterion_group, criterion_main, Criterion, BenchmarkId};
+use std::hint::black_box;
 
 fn fibonacci_slow(n: u64) -> u64 {
     match n {

book/src/user_guide/custom_test_framework.md

@@ -28,8 +28,9 @@ Let's take a look at an example benchmark (note that this example assumes you're
 #![feature(custom_test_frameworks)]
 #![test_runner(criterion::runner)]
 
-use criterion::{Criterion, black_box};
+use criterion::Criterion;
 use criterion_macro::criterion;
+use std::hint::black_box;
 
 fn fibonacci(n: u64) -> u64 {
     match n {

book/src/user_guide/known_limitations.md

@@ -14,11 +14,3 @@ This results in several limitations:
 * It is not possible to benchmark functions in crates that do not provide an `rlib`.
 
 Criterion.rs cannot currently solve these issues. An [experimental RFC](https://github.com/rust-lang/rust/issues/50297) is being implemented to enable custom test and benchmarking frameworks.
-
-Second, Criterion.rs provides a stable-compatible replacement for the `black_box` function provided by the standard test crate. This replacement is not as reliable as the official one, and it may allow dead-code-elimination to affect the benchmarks in some circumstances. If you're using a Nightly build of Rust, you can add the `real_blackbox` feature to your dependency on Criterion.rs to use the standard `black_box` function instead.
-
-Example:
-
-```toml
-criterion = { version = '...', features=['real_blackbox'] }
-```

book/src/user_guide/migrating_from_libtest.md

@@ -48,7 +48,8 @@ criterion = "0.5.1"
 The next step is to update the imports:
 
 ```rust
-use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use criterion::{criterion_group, criterion_main, Criterion};
+use std::hint::black_box;
 ```
 
 Then, we can change the `bench_fib` function. Remove the `#[bench]` and change
@@ -72,7 +73,8 @@ criterion_main!(benches);
 And that's it! The complete migrated benchmark code is below:
 
 ```rust
-use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use criterion::{criterion_group, criterion_main, Criterion};
+use std::hint::black_box;
 
 fn fibonacci(n: u64) -> u64 {
     match n {

macro/benches/test_macro_bench.rs

@@ -1,7 +1,8 @@
 #![feature(custom_test_frameworks)]
 #![test_runner(criterion::runner)]
 
-use criterion::{Criterion, black_box};
+use std::hint::black_box;
+use criterion::Criterion;
 use criterion_macro::criterion;
 
 fn fibonacci(n: u64) -> u64 {
@@ -24,4 +25,4 @@ fn bench_simple(c: &mut Criterion) {
 #[criterion(custom_criterion())]
 fn bench_custom(c: &mut Criterion) {
     c.bench_function("Fibonacci-Custom", |b| b.iter(|| fibonacci(black_box(20))));
-}
+}

src/bencher.rs

@@ -1,7 +1,7 @@
+use std::hint::black_box;
 use std::time::Duration;
 use std::time::Instant;
 
-use crate::black_box;
 use crate::measurement::{Measurement, WallTime};
 use crate::BatchSize;
 
@@ -103,7 +103,6 @@ impl<'a, M: Measurement> Bencher<'a, M> {
     /// ```rust
     /// #[macro_use] extern crate criterion;
     /// use criterion::*;
-    /// use criterion::black_box;
     /// use std::time::Instant;
     ///
     /// fn foo() {
@@ -115,7 +114,7 @@ impl<'a, M: Measurement> Bencher<'a, M> {
     ///         b.iter_custom(|iters| {
     ///             let start = Instant::now();
     ///             for _i in 0..iters {
-    ///                 black_box(foo());
+    ///                 std::hint::black_box(foo());
     ///             }
     ///             start.elapsed()
     ///         })
@@ -461,7 +460,6 @@ impl<'a, 'b, A: AsyncExecutor, M: Measurement> AsyncBencher<'a, 'b, A, M> {
     /// ```rust
     /// #[macro_use] extern crate criterion;
     /// use criterion::*;
-    /// use criterion::black_box;
     /// use criterion::async_executor::FuturesExecutor;
     /// use std::time::Instant;
     ///
@@ -475,7 +473,7 @@ impl<'a, 'b, A: AsyncExecutor, M: Measurement> AsyncBencher<'a, 'b, A, M> {
     ///             async move {
     ///                 let start = Instant::now();
     ///                 for _i in 0..iters {
-    ///                     black_box(foo().await);
+    ///                     std::hint::black_box(foo().await);
     ///                 }
     ///                 start.elapsed()
     ///             }

src/lib.rs

@@ -17,7 +17,6 @@
 
 #![warn(missing_docs)]
 #![warn(bare_trait_objects)]
-#![cfg_attr(feature = "real_blackbox", feature(test))]
 #![allow(
         clippy::just_underscores_and_digits, // Used in the stats code
         clippy::transmute_ptr_to_ptr, // Used in the stats code
@@ -36,9 +35,6 @@ extern crate quickcheck;
 use regex::Regex;
 use serde::{Deserialize, Serialize};
 
-#[cfg(feature = "real_blackbox")]
-extern crate test;
-
 // Needs to be declared before other modules
 // in order to be usable there.
 #[macro_use]
@@ -144,25 +140,9 @@ fn debug_enabled() -> bool {
 
 /// A function that is opaque to the optimizer, used to prevent the compiler from
 /// optimizing away computations in a benchmark.
-///
-/// This variant is backed by the (unstable) test::black_box function.
-#[cfg(feature = "real_blackbox")]
+#[deprecated(note = "use `std::hint::black_box()` instead")]
 pub fn black_box<T>(dummy: T) -> T {
-    test::black_box(dummy)
-}
-
-/// A function that is opaque to the optimizer, used to prevent the compiler from
-/// optimizing away computations in a benchmark.
-///
-/// This variant is stable-compatible, but it may cause some performance overhead
-/// or fail to prevent code from being eliminated.
-#[cfg(not(feature = "real_blackbox"))]
-pub fn black_box<T>(dummy: T) -> T {
-    unsafe {
-        let ret = std::ptr::read_volatile(&dummy);
-        std::mem::forget(dummy);
-        ret
-    }
+    std::hint::black_box(dummy)
 }
 
 /// Argument to [`Bencher::iter_batched`] and [`Bencher::iter_batched_ref`] which controls the

src/routine.rs

@@ -2,7 +2,8 @@ use crate::benchmark::BenchmarkConfig;
 use crate::connection::OutgoingMessage;
 use crate::measurement::Measurement;
 use crate::report::{BenchmarkId, Report, ReportContext};
-use crate::{black_box, ActualSamplingMode, Bencher, Criterion};
+use crate::{ActualSamplingMode, Bencher, Criterion};
+use std::hint::black_box;
 use std::marker::PhantomData;
 use std::time::Duration;