library/core/src/hint.rs

   1 #![stable(feature = "core_hint", since = "1.27.0")]
   2
   3 //! Hints to compiler that affects how code should be emitted or optimized.
   4 //! Hints may be compile time or runtime.
   5
   6 use crate::intrinsics;
   7
   8 /// Informs the compiler that this point in the code is not reachable, enabling
   9 /// further optimizations.
  10 ///
  11 /// # Safety
  12 ///
  13 /// Reaching this function is completely *undefined behavior* (UB). In
  14 /// particular, the compiler assumes that all UB must never happen, and
  15 /// therefore will eliminate all branches that reach to a call to
  16 /// `unreachable_unchecked()`.
  17 ///
  18 /// Like all instances of UB, if this assumption turns out to be wrong, i.e., the
  19 /// `unreachable_unchecked()` call is actually reachable among all possible
  20 /// control flow, the compiler will apply the wrong optimization strategy, and
  21 /// may sometimes even corrupt seemingly unrelated code, causing
  22 /// difficult-to-debug problems.
  23 ///
  24 /// Use this function only when you can prove that the code will never call it.
  25 /// Otherwise, consider using the [`unreachable!`] macro, which does not allow
  26 /// optimizations but will panic when executed.
  27 ///
  28 /// # Example
  29 ///
  30 /// ```
  31 /// fn div_1(a: u32, b: u32) -> u32 {
  32 ///     use std::hint::unreachable_unchecked;
  33 ///
  34 ///     // `b.saturating_add(1)` is always positive (not zero),
  35 ///     // hence `checked_div` will never return `None`.
  36 ///     // Therefore, the else branch is unreachable.
  37 ///     a.checked_div(b.saturating_add(1))
  38 ///         .unwrap_or_else(|| unsafe { unreachable_unchecked() })
  39 /// }
  40 ///
  41 /// assert_eq!(div_1(7, 0), 7);
  42 /// assert_eq!(div_1(9, 1), 4);
  43 /// assert_eq!(div_1(11, u32::MAX), 0);
  44 /// ```
  45 #[inline]
  46 #[stable(feature = "unreachable", since = "1.27.0")]
  47 #[rustc_const_stable(feature = "const_unreachable_unchecked", since = "1.57.0")]
  48 pub const unsafe fn unreachable_unchecked() -> ! {
  49     // SAFETY: the safety contract for `intrinsics::unreachable` must
  50     // be upheld by the caller.
  51     unsafe { intrinsics::unreachable() }
  52 }
  53
  54 /// Emits a machine instruction to signal the processor that it is running in
  55 /// a busy-wait spin-loop ("spin lock").
  56 ///
  57 /// Upon receiving the spin-loop signal the processor can optimize its behavior by,
  58 /// for example, saving power or switching hyper-threads.
  59 ///
  60 /// This function is different from [`thread::yield_now`] which directly
  61 /// yields to the system's scheduler, whereas `spin_loop` does not interact
  62 /// with the operating system.
  63 ///
  64 /// A common use case for `spin_loop` is implementing bounded optimistic
  65 /// spinning in a CAS loop in synchronization primitives. To avoid problems
  66 /// like priority inversion, it is strongly recommended that the spin loop is
  67 /// terminated after a finite amount of iterations and an appropriate blocking
  68 /// syscall is made.
  69 ///
  70 /// **Note**: On platforms that do not support receiving spin-loop hints this
  71 /// function does not do anything at all.
  72 ///
  73 /// # Examples
  74 ///
  75 /// ```
  76 /// use std::sync::atomic::{AtomicBool, Ordering};
  77 /// use std::sync::Arc;
  78 /// use std::{hint, thread};
  79 ///
  80 /// // A shared atomic value that threads will use to coordinate
  81 /// let live = Arc::new(AtomicBool::new(false));
  82 ///
  83 /// // In a background thread we'll eventually set the value
  84 /// let bg_work = {
  85 ///     let live = live.clone();
  86 ///     thread::spawn(move || {
  87 ///         // Do some work, then make the value live
  88 ///         do_some_work();
  89 ///         live.store(true, Ordering::Release);
  90 ///     })
  91 /// };
  92 ///
  93 /// // Back on our current thread, we wait for the value to be set
  94 /// while !live.load(Ordering::Acquire) {
  95 ///     // The spin loop is a hint to the CPU that we're waiting, but probably
  96 ///     // not for very long
  97 ///     hint::spin_loop();
  98 /// }
  99 ///
 100 /// // The value is now set
 101 /// # fn do_some_work() {}
 102 /// do_some_work();
 103 /// bg_work.join()?;
 104 /// # Ok::<(), Box<dyn core::any::Any + Send + 'static>>(())
 105 /// ```
 106 ///
 107 /// [`thread::yield_now`]: ../../std/thread/fn.yield_now.html
 108 #[inline]
 109 #[stable(feature = "renamed_spin_loop", since = "1.49.0")]
 110 pub fn spin_loop() {
 111     #[cfg(all(any(target_arch = "x86", target_arch = "x86_64"), target_feature = "sse2"))]
 112     {
 113         #[cfg(target_arch = "x86")]
 114         {
 115             // SAFETY: the `cfg` attr ensures that we only execute this on x86 targets.
 116             unsafe { crate::arch::x86::_mm_pause() };
 117         }
 118
 119         #[cfg(target_arch = "x86_64")]
 120         {
 121             // SAFETY: the `cfg` attr ensures that we only execute this on x86_64 targets.
 122             unsafe { crate::arch::x86_64::_mm_pause() };
 123         }
 124     }
 125
 126     // RISC-V platform spin loop hint implementation
 127     {
 128         // RISC-V RV32 and RV64 share the same PAUSE instruction, but they are located in different
 129         // modules in `core::arch`.
 130         // In this case, here we call `pause` function in each core arch module.
 131         #[cfg(target_arch = "riscv32")]
 132         {
 133             crate::arch::riscv32::pause();
 134         }
 135         #[cfg(target_arch = "riscv64")]
 136         {
 137             crate::arch::riscv64::pause();
 138         }
 139     }
 140
 141     #[cfg(any(target_arch = "aarch64", all(target_arch = "arm", target_feature = "v6")))]
 142     {
 143         #[cfg(target_arch = "aarch64")]
 144         {
 145             // SAFETY: the `cfg` attr ensures that we only execute this on aarch64 targets.
 146             unsafe { crate::arch::aarch64::__isb(crate::arch::aarch64::SY) };
 147         }
 148         #[cfg(target_arch = "arm")]
 149         {
 150             // SAFETY: the `cfg` attr ensures that we only execute this on arm targets
 151             // with support for the v6 feature.
 152             unsafe { crate::arch::arm::__yield() };
 153         }
 154     }
 155 }
 156
 157 /// An identity function that *__hints__* to the compiler to be maximally pessimistic about what
 158 /// `black_box` could do.
 159 ///
 160 /// Unlike [`std::convert::identity`], a Rust compiler is encouraged to assume that `black_box` can
 161 /// use `dummy` in any possible valid way that Rust code is allowed to without introducing undefined
 162 /// behavior in the calling code. This property makes `black_box` useful for writing code in which
 163 /// certain optimizations are not desired, such as benchmarks.
 164 ///
 165 /// Note however, that `black_box` is only (and can only be) provided on a "best-effort" basis. The
 166 /// extent to which it can block optimisations may vary depending upon the platform and code-gen
 167 /// backend used. Programs cannot rely on `black_box` for *correctness* in any way.
 168 ///
 169 /// [`std::convert::identity`]: crate::convert::identity
 170 #[inline]
 171 #[unstable(feature = "bench_black_box", issue = "64102")]
 172 #[rustc_const_unstable(feature = "const_black_box", issue = "none")]
 173 pub const fn black_box<T>(dummy: T) -> T {
 174     crate::intrinsics::black_box(dummy)
 175 }