From a4b3dbe4c1b225b4b911438861e98e4b1aa70183 Mon Sep 17 00:00:00 2001 From: Edd Barrett Date: Tue, 23 Jul 2019 10:30:13 +0100 Subject: [PATCH] Improve the documentation for std::hint::black_box. --- src/libcore/hint.rs | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/src/libcore/hint.rs b/src/libcore/hint.rs index 519212bb6cb..3aba07f882d 100644 --- a/src/libcore/hint.rs +++ b/src/libcore/hint.rs @@ -104,11 +104,19 @@ pub fn spin_loop() { } } -/// A function that is opaque to the optimizer, to allow benchmarks to -/// pretend to use outputs to assist in avoiding dead-code -/// elimination. +/// An identity function that *__hints__* to the compiler to be maximally pessimistic about what +/// `black_box` could do. /// -/// This function is a no-op, and does not even read from `dummy`. +/// [`std::convert::identity`]: https://doc.rust-lang.org/core/convert/fn.identity.html +/// +/// Unlike [`std::convert::identity`], a Rust compiler is encouraged to assume that `black_box` can +/// use `x` in any possible valid way that Rust code is allowed to without introducing undefined +/// behavior in the calling code. This property makes `black_box` useful for writing code in which +/// certain optimizations are not desired, such as benchmarks. +/// +/// Note however, that `black_box` is only (and can only be) provided on a "best-effort" basis. The +/// extent to which it can block optimisations may vary depending upon the platform and code-gen +/// backend used. Programs cannot rely on `black_box` for *correctness* in any way. #[inline] #[unstable(feature = "test", issue = "27812")] #[allow(unreachable_code)] // this makes #[cfg] a bit easier below.