#![stable(feature = "core_hint", since = "1.27.0")]

//! 对编译器的提示，该提示会影响应如何发出或优化代码。
//! 提示可能是编译时或运行时。

use crate::intrinsics;

/// 通知编译器调用此函数的站点不可访问，可能会启用进一步优化。
///
/// # Safety
///
/// 达到这个函数是 *未定义的行为*。
///
/// 由于编译器假定所有形式的未定义行为永远不会发生，它将消除周围代码中的所有分支，它可以确定总是会导致调用 `unreachable_unchecked()`。
///
/// 如果使用这个函数的假设被证明是错误的 -- 也就是说，如果调用 `unreachable_unchecked()` 的站点在运行时实际上是可访问的 -- 编译器可能已经为这种情况生成了无意义的机器指令，包括看似不相关的代码，导致难以 - 调试问题。
///
///
/// 谨慎使用此功能。
/// 考虑使用 [`unreachable!`] 宏，这可能会阻止一些优化，但如果在运行时实际达到它会安全地 panic。对您的代码进行基准测试，以确定使用 `unreachable_unchecked()` 是否具有性能优势。
///
/// # Examples
///
/// `unreachable_unchecked()` 可用于编译器无法证明先前建立的不，变体，的情况。如果编译器无法分析的外部代码支持这些不，变体，则这种情况发生的可能性更高。
///
/// ```
/// fn prepare_inputs(divisors: &mut Vec<u32>) {
///     // 更改时，注意 future-self: 这里建立的不变量没有在 `do_computation()` 中检查; 如果这种情况发生变化，您必须更改 `do_computation()`。
/////
/////
///     divisors.retain(|divisor| *divisor != 0)
/// }
///
/// /// # Safety
/// /// `divisor` 的所有元素都必须非零。
/// unsafe fn do_computation(i: u32, divisors: &[u32]) -> u32 {
///     divisors.iter().fold(i, |acc, divisor| {
///         // 让编译器相信这里不会发生被零除，并且下面不需要检查。
/////
///         if *divisor == 0 {
///             // 安全性: 由于 `prepare_inputs`，`divisor` 不能为零，但编译器不知道这一点。
///             // 我们 *承诺* 我们总是调用 `prepare_inputs`。
/////
///             std::hint::unreachable_unchecked()
///         }
///         // 编译器通常会在此处引入一个检查，以防止被零除。
///         // 但是，如果 `divisor` 为零，则上面的分支将到达我们明确标记为不可达的地方。
///         // 编译器得出结论，此时 `divisor` 不能为零，并删除 - 现在证明无用 - 检查。
/////
/////
///         acc / divisor
///     })
/// }
///
/// let mut divisors = vec![2, 0, 4];
/// prepare_inputs(&mut divisors);
/// let result = unsafe {
///     // 安全性: prepare_inputs() 保证除数不为零
///     do_computation(100, &divisors)
/// };
/// assert_eq!(result, 12);
///
/// ```
///
/// 虽然在以下示例中使用 `unreachable_unchecked()` 是完美的，因为编译器能够证明除以零是不可能的，但基准测试显示 `unreachable_unchecked()` 与使用 [`unreachable!`] 相比没有任何好处，而后者不会引入未定义行为的可能性。
///
/// ```
/// fn div_1(a: u32, b: u32) -> u32 {
///     use std::hint::unreachable_unchecked;
///
///     // `b.saturating_add(1)` 始终为正 (非零)，因此 `checked_div` 永远不会返回 `None`。
/////
///     // 因此，else 分支不可访问。
///     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, u32::MAX), 0);
/// ```
///
///
///
///
///
///
///
///
///
///
///
///
///
///
#[inline]
#[stable(feature = "unreachable", since = "1.27.0")]
#[rustc_const_stable(feature = "const_unreachable_unchecked", since = "1.57.0")]
#[cfg_attr(miri, track_caller)] // 即使没有 panic，这也有助于 Miri 回溯
pub const unsafe fn unreachable_unchecked() -> ! {
    // SAFETY: 调用者必须遵守 `intrinsics::unreachable` 的安全保证。
    //
    unsafe {
        intrinsics::assert_unsafe_precondition!("hint::unreachable_unchecked must never be reached", () => false);
        intrinsics::unreachable()
    }
}

/// 发出一条机器指令，以向处理器发送信号，指示其正在忙于等待的自旋循环 (自旋锁) 中运行。
///
/// 在接收到自旋环信号后，处理器可以通过例如节省功率或切换 hyper 线程来优化其行为。
///
/// 此函数不同于 [`thread::yield_now`]，后者直接产生系统的调度程序，而 `spin_loop` 不与操作系统交互。
///
/// `spin_loop` 的一个常见用例是在同步原语的 CAS 循环中实现有界乐观旋转。
/// 为避免优先级倒置之类的问题，强烈建议在有限次数的迭代后终止旋转循环，并进行适当的阻塞系统调用。
///
///
/// **Note**: 在不支持接收自旋循环提示的平台上，此函数完全不执行任何操作。
///
/// # Examples
///
/// ```
/// use std::sync::atomic::{AtomicBool, Ordering};
/// use std::sync::Arc;
/// use std::{hint, thread};
///
/// // 线程将用于协调的共享原子值
/// let live = Arc::new(AtomicBool::new(false));
///
/// // 在后台线程中，我们最终将设置该值
/// let bg_work = {
///     let live = live.clone();
///     thread::spawn(move || {
///         // 做一些工作，然后创造值
///         do_some_work();
///         live.store(true, Ordering::Release);
///     })
/// };
///
/// // 回到我们当前的线程，我们等待该值被设置
/// while !live.load(Ordering::Acquire) {
///     // 自旋循环是对我们正在等待的 CPU 的提示，但可能不会持续很长时间
/////
///     hint::spin_loop();
/// }
///
/// // 现在设置该值
/// # fn do_some_work() {}
/// do_some_work();
/// bg_work.join()?;
/// # Ok::<(), Box<dyn core::any::Any + Send + 'static>>(())
/// ```
///
/// [`thread::yield_now`]: ../../std/thread/fn.yield_now.html
///
///
///
///
///
///
///
#[inline(always)]
#[stable(feature = "renamed_spin_loop", since = "1.49.0")]
pub fn spin_loop() {
    #[cfg(target_arch = "x86")]
    {
        // SAFETY: `cfg` 属性确保我们仅在 x86 目标上执行此操作。
        unsafe { crate::arch::x86::_mm_pause() };
    }

    #[cfg(target_arch = "x86_64")]
    {
        // SAFETY: `cfg` 属性确保我们仅在 x86_64 目标上执行此操作。
        unsafe { crate::arch::x86_64::_mm_pause() };
    }

    // RISC-V 平台自旋循环提示实现
    {
        // RISC-V RV32 和 RV64 共享相同的 PAUSE 指令，但它们位于 `core::arch` 中的不同模块中。
        //
        // 在这种情况下，我们在每个核心 arch 模块中调用 `pause` 函数。
        #[cfg(target_arch = "riscv32")]
        {
            crate::arch::riscv32::pause();
        }
        #[cfg(target_arch = "riscv64")]
        {
            crate::arch::riscv64::pause();
        }
    }

    #[cfg(any(target_arch = "aarch64", all(target_arch = "arm", target_feature = "v6")))]
    {
        #[cfg(target_arch = "aarch64")]
        {
            // SAFETY: `cfg` 属性确保我们仅在 aarch64 目标上执行此操作。
            unsafe { crate::arch::aarch64::__isb(crate::arch::aarch64::SY) };
        }
        #[cfg(target_arch = "arm")]
        {
            // SAFETY: `cfg` 属性确保我们仅在支持 v6 特性的 arm 目标上执行此操作。
            //
            unsafe { crate::arch::arm::__yield() };
        }
    }
}

/// 一个标识函数，*__hints__* 编译器对 `black_box` 能做的事情保持最大限度的悲观。
///
/// 与 [`std::convert::identity`] 不同，鼓励 Rust 编译器假定 `black_box` 可以以允许 Rust 代码使用的任何可能有效方式使用 `dummy`，而不会在调用代码中引入未定义的行为。
///
/// 此属性使 `black_box` 可用于编写不需要进行某些优化 (例如基准测试) 的代码。
///
/// 但是请注意，`black_box` 仅 (并且只能) 以 "best-effort" 为基础提供。它可以阻止优化的程度可能会有所不同，具体取决于所使用的平台和代码源后端。
/// 程序不能依赖 `black_box` 的*正确性*，除了它作为身份函数。
/// 因此，**不得依赖它来控制关键程序行为。**这立即排除了将此函数直接用于加密或安全目的的任何可能性。
///
/// [`std::convert::identity`]: crate::convert::identity
///
/// # 这什么时候有用?
///
/// 虽然不适合那些关键任务的情况，但通常可以依赖 black_box 的功能进行基准测试，并且应该在那里使用。
/// 它将尝试确保编译器不会根据上下文优化部分预期的测试代码。
/// 例如：
///
/// ```
/// fn contains(haystack: &[&str], needle: &str) -> bool {
///     haystack.iter().any(|x| x == &needle)
/// }
///
/// pub fn benchmark() {
///     let haystack = vec!["abc", "def", "ghi", "jkl", "mno"];
///     let needle = "ghi";
///     for _ in 0..10 {
///         contains(&haystack, needle);
///     }
/// }
/// ```
///
/// 编译器理论上可以进行如下优化:
///
/// - `needle` 和 `haystack` 一直一样，把调用移到循环外的 `contains`，删除循环
/// - Inline `contains`
/// - `needle` 和 `haystack` 的值在编译时已知，`contains` 始终为真。去掉调用，换成 `true`
/// - `contains` 的结果没有做任何事情: 完全删除这个函数调用
/// - `benchmark` 现在没有任何意义: 删除这个函数
///
/// 上述所有情况不太可能发生，但编译器肯定能够进行一些优化，这可能会导致基准测试非常不准确。这就是 `black_box` 的用武之地:
///
/// ```
/// use std::hint::black_box;
///
/// // 相同 `contains` 函数
/// fn contains(haystack: &[&str], needle: &str) -> bool {
///     haystack.iter().any(|x| x == &needle)
/// }
///
/// pub fn benchmark() {
///     let haystack = vec!["abc", "def", "ghi", "jkl", "mno"];
///     let needle = "ghi";
///     for _ in 0..10 {
///         // 调整我们的基准循环内容
///         black_box(contains(black_box(&haystack), black_box(needle)));
///     }
/// }
/// ```
///
/// 这实质上告诉编译器阻止对 `black_box` 的任何调用的优化。
/// 所以，它现在:
///
/// - 将参数到 `contains` 都视为不可预测: `contains` 的主体不能再根据参数值进行优化
/// - 将调用 `contains` 及其结果视为易变的: `benchmark` 的主体无法优化它
///
/// 这使我们的基准测试更现实地了解函数如何在原位使用，其中函数通常在编译时未知，结果以某种方式使用。
///
///
///
///
///
///
///
///
///
///
///
///
///
#[inline]
#[stable(feature = "bench_black_box", since = "1.66.0")]
#[rustc_const_unstable(feature = "const_black_box", issue = "none")]
pub const fn black_box<T>(dummy: T) -> T {
    crate::intrinsics::black_box(dummy)
}

/// 如果调用者未使用给定值 (返回、存储在变量中等)，则会触发 `unused_must_use` 警告的标识函数。
///
/// 这主要用于宏生成的代码，其中类型或函数上的 [`#[must_use]` 属性][must_use] 不方便。
///
/// [must_use]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-must_use-attribute
///
/// # Example
///
/// ```
/// #![feature(hint_must_use)]
///
/// use core::fmt;
///
/// pub struct Error(/* ... */);
///
/// #[macro_export]
/// macro_rules! make_error {
///     ($($args:expr),*) => {
///         core::hint::must_use({
///             let error = $crate::make_error(core::format_args!($($args),*));
///             error
///         })
///     };
/// }
///
/// // make_error 的实现细节! macro.
/// #[doc(hidden)]
/// pub fn make_error(args: fmt::Arguments<'_>) -> Error {
///     Error(/* ... */)
/// }
///
/// fn demo() -> Option<Error> {
///     if true {
///         // 哎呀，本来想写 `return Some(make_error!("..."));`
///         Some(make_error!("..."));
///     }
///     None
/// }
/// #
/// # // 使 rustdoc 不在 fn main 中包装整个片段，以便 $crate::make_error 工作
/// # fn main() {}
/// ```
///
/// 在上面的示例中，我们希望 `unused_must_use` lint 应用于 `make_error!` 创建的值。
/// 但是，结构体上的 `#[must_use]` 和函数上的 `#[must_use]` 都不适用于这里，因此宏使用 `core::hint::must_use` 进行扩展。
///
/// - 我们不希望在 `struct Error` 上使用 `#[must_use]`，因为这会使以下无问题的代码触发警告:
///
///   ```
///   # struct Error;
///   #
///   fn f(arg: &str) -> Result<(), Error>
///   # { Ok(()) }
///
///   #[test]
///   fn t() {
///       // 如果传递一个空字符串，则断言 `f` 将返回错误。
///       // 这里没有使用 `Error` 类型的值，但这不是问题。
///       f("").unwrap_err();
///   }
///   ```
///
/// - 在 `fn make_error` 上使用 `#[must_use]` 无济于事，因为返回值 *is* 被用作 `let` 语句的右侧。
/// `let` 语句看起来毫无用处，但实际上对于确保 `format_args` 扩展中的临时对象在创建 `Error` 之后不会保持活动状态是必要的，因为在创建 `Error` 之后保持它们活动可能会导致异步代码中的 autotrait 问题:
///
///
///   ```
///   # #![feature(hint_must_use)]
///   #
///   # struct Error;
///   #
///   # macro_rules! make_error {
///   #     ($($args:expr),*) => {
///   #         core::hint::must_use({
///   #             // 如果不使用 `let`，则 `f()` 生成一个不发送的 future。
///   #             let error = make_error(core::format_args!($($args),*));
///   #             error
///   #         })
///   #     };
///   # }
///   #
///   # fn make_error(args: core::fmt::Arguments<'_>) -> Error {
///   #     Error
///   # }
///   #
///   async fn f() {
///       // 在 make_error 扩展中使用 `let` 会导致诸如 `unsync()` 之类的临时变量在 `let` 语句的分号处，该分号位于 await 点之前。
///       // 否则它们会一直停留在 *this* 语句的分号上，也就是在 await 点之后，并且封闭的 Future 不会实现 Send。
/////
/////
/////
///       log(make_error!("look: {:p}", unsync())).await;
///   }
///
///   async fn log(error: Error) {/* ... */}
///
///   // 返回没有 Sync impl 的内容。
///   fn unsync() -> *const () {
///       0 as *const ()
///   }
///   #
///   # fn test() {
///   #     fn assert_send(_: impl Send) {}
///   #     assert_send(f());
///   # }
///   ```
///
///
///
///
///
///
///
///
///
///
#[unstable(feature = "hint_must_use", issue = "94745")]
#[rustc_const_unstable(feature = "hint_must_use", issue = "94745")]
#[must_use] // <-- :)
#[inline(always)]
pub const fn must_use<T>(value: T) -> T {
    value
}