62 lines
2.2 KiB
Rust
62 lines
2.2 KiB
Rust
// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
|
|
// file at the top-level directory of this distribution and at
|
|
// http://rust-lang.org/COPYRIGHT.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
|
|
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
|
|
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
|
|
// option. This file may not be copied, modified, or distributed
|
|
// except according to those terms.
|
|
|
|
#![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()
|
|
}
|