1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51
#![stable(feature = "core_hint", since = "1.27.0")] //! Hints to compiler that affects how code should be emitted or optimized. use intrinsics; /// Informs the compiler that this point in the code is not reachable, enabling /// further optimizations. /// /// # Safety /// /// Reaching this function is completely *undefined behavior* (UB). In /// particular, the compiler assumes that all UB must never happen, and /// therefore will eliminate all branches that reach to a call to /// `unreachable_unchecked()`. /// /// Like all instances of UB, if this assumption turns out to be wrong, i.e., the /// `unreachable_unchecked()` call is actually reachable among all possible /// control flow, the compiler will apply the wrong optimization strategy, and /// may sometimes even corrupt seemingly unrelated code, causing /// difficult-to-debug problems. /// /// Use this function only when you can prove that the code will never call it. /// /// The [`unreachable!()`] macro is the safe counterpart of this function, which /// will panic instead when executed. /// /// [`unreachable!()`]: ../macro.unreachable.html /// /// # Example /// /// ``` /// fn div_1(a: u32, b: u32) -> u32 { /// use std::hint::unreachable_unchecked; /// /// // `b.saturating_add(1)` is always positive (not zero), /// // hence `checked_div` will never return None. /// // Therefore, the else branch is unreachable. /// a.checked_div(b.saturating_add(1)) /// .unwrap_or_else(|| unsafe { unreachable_unchecked() }) /// } /// /// assert_eq!(div_1(7, 0), 7); /// assert_eq!(div_1(9, 1), 4); /// assert_eq!(div_1(11, std::u32::MAX), 0); /// ``` #[inline] #[stable(feature = "unreachable", since = "1.27.0")] pub unsafe fn unreachable_unchecked() -> ! { intrinsics::unreachable() }