//! 原生线程。
//!
//! ## 线程模型
//!
//! 一个正在执行的 Rust 程序由一组原生操作系统线程组成​​，每个线程都有自己的栈和本地状态。线程可以被命名，并为底层同步提供一些内置支持。
//!
//! 线程之间的通信可以通过 [通道][channels]、Rust 的消息传递类型、以及 [其他形式的线程同步](../../std/sync/index.html) 和共享内存数据结构来完成。
//! 特别是，可以使用原子引用计数容器 [`Arc`] 在线程之间轻松共享保证线程安全的类型。
//!
//! Rust 中的致命逻辑错误导致 *线程 panic*，在此期间，线程将展开栈，运行析构函数并释放所拥有的资源。
//! 尽管不是 'try/catch' 机制，但仍可以使用 [`catch_unwind`](../../std/panic/fn.catch_unwind.html) 捕获 Rust 中的 panics (除非使用 `panic=abort` 进行编译) 并从中恢复，或者使用 [`resume_unwind`](../../std/panic/fn.resume_unwind.html) 恢复。
//!
//! 如果未捕获到 panic，则线程将退出，但是可以选择使用 [`join`] 从其他线程中检测到 panic。
//! 如果主线程 panic 而没有捕获 panic，应用程序将以非零退出码退出。
//!
//! 当 Rust 程序的主线程终止时，整个程序将关闭，即使其他线程仍在运行也不例外。然而，这个模块为自动等待线程终止 (即 join) 提供了便利。
//!
//! ## 生成一个线程
//!
//! 可以使用 [`thread::spawn`][`spawn`] 函数来生成一个新线程：
//!
//! ```rust
//! use std::thread;
//!
//! thread::spawn(move || {
//!     // 这里一些工作
//! });
//! ```
//!
//! 在此示例中，新建线程是 "detached,"，这意味着程序无法了解新建线程何时完成或以其他方式终止。
//!
//! 要了解线程何时完成，需要捕获调用返回给 [`spawn`] 的 [`JoinHandle`] 对象，它提供了一个 `join` 方法，允许调用者等待新建线程的完成：
//!
//! ```rust
//! use std::thread;
//!
//! let thread_join_handle = thread::spawn(move || {
//!     // 这里一些工作
//! });
//! // 这里一些工作
//! let res = thread_join_handle.join();
//! ```
//!
//! [`join`] 方法返回一个 [`thread::Result`]，其中包含由新建线程生成的最终值的 [`Ok`]，或者如果线程 panicked，则返回给 [`panic!`] 的调用值的 [`Err`]。
//!
//! 请注意，生成新线程的线程与生成的线程之间没有 parent/child 关系。特别是，除非生成线程是主线程，否则新建线程可能会也可能不会比生成线程的生命周期长。
//!
//! ## 配置线程
//!
//! 一个新线程可以在通过 [`Builder`] 类型生成之前进行配置，目前允许您设置线程的名称和栈大小：
//!
//! ```rust
//! # #![allow(unused_must_use)]
//! use std::thread;
//!
//! thread::Builder::new().name("thread1".to_string()).spawn(move || {
//!     println!("Hello, world!");
//! });
//! ```
//!
//! ## `Thread` 的类型
//!
//! 线程是通过 [`Thread`] 类型来表示的，您可以通过以下两种方式之一获得该类型：
//!
//! * 通过生成一个新线程，例如使用 [`thread::spawn`][`spawn`] 函数，并在 [`JoinHandle`] 上调用 [`thread`][`JoinHandle::thread`]。
//! * 通过使用 [`thread::current`] 函数来请求当前线程。
//!
//! [`thread::current`] 函数甚至可用于不是由该模块的 API 生成的线程。
//!
//! ## 线程本地存储
//!
//! 该模块还为 Rust 程序提供了线程本地存储的实现。线程本地存储是一种将数据存储到全局变量的方法，程序中的每个线程都有自己的副本。
//! 线程不共享此数据，因此不需要同步访问。
//!
//! 线程本地键拥有它所包含的值，并在线程退出时销毁该值。它是使用 [`thread_local!`] 宏创建的，可以包含 `'static` 的任何值 (没有借用指针)。
//! 它提供了一个访问器函数 [`with`]，该访问器函数产生对指定闭包的值的共享引用。线程本地键只允许共享访问值，因为如果允许可变借用，就无法保证惟一性。
//! 大多数值都希望通过 [`Cell`] 或 [`RefCell`] 类型使用某种形式的 **内部可变性**。
//!
//! ## 命名线程
//!
//! 出于识别目的，线程可以有关联的名称。默认情况下，生成的线程是未命名的。要为线程指定名称，请使用 [`Builder`] 构建该线程，然后将所需的线程名称传递给 [`Builder::name`]。
//! 要从线程内检索线程名，请使用 [`Thread::name`]。
//! 有几个使用线程名称的例子:
//!
//! * 如果在命名线程中出现 panic，则线程名将显示在 panic 消息中。
//! * 线程名在适用的情况下提供给操作系统 (例如，在类 Unix 平台中为 `pthread_setname_np`)。
//!
//! ## 栈大小
//!
//! 默认栈大小取决于平台并且可能会发生变化。
//! 目前，在所有 Tier-1 平台上都是 2 MiB。
//!
//! 有两种方法可以手动指定衍生线程的栈大小：
//!
//! * 使用 [`Builder`] 构建线程，并将所需的栈大小传递给 [`Builder::stack_size`]。
//! * 将 `RUST_MIN_STACK` 环境变量设置为代表所需栈大小 (以字节为单位) 的整数。请注意，设置 [`Builder::stack_size`] 将覆盖此设置。请注意，程序启动后可能会忽略对 `RUST_MIN_STACK` 的更改。
//!
//! 注意，主线程的栈大小不是由 Rust 决定的。
//!
//! [channels]: crate::sync::mpsc
//! [`join`]: JoinHandle::join
//! [`Result`]: crate::result::Result
//! [`Ok`]: crate::result::Result::Ok
//! [`Err`]: crate::result::Result::Err
//! [`thread::current`]: current
//! [`thread::Result`]: Result
//! [`unpark`]: Thread::unpark
//! [`thread::park_timeout`]: park_timeout
//! [`Cell`]: crate::cell::Cell
//! [`RefCell`]: crate::cell::RefCell
//! [`with`]: LocalKey::with
//! [`thread_local!`]: crate::thread_local
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!

#![stable(feature = "rust1", since = "1.0.0")]
#![deny(unsafe_op_in_unsafe_fn)]
// 在 `test` 下，`__FastLocalKeyInner` 似乎没有使用。
#![cfg_attr(test, allow(dead_code))]

#[cfg(all(test, not(target_os = "emscripten")))]
mod tests;

use crate::any::Any;
use crate::cell::UnsafeCell;
use crate::ffi::{CStr, CString};
use crate::fmt;
use crate::io;
use crate::marker::PhantomData;
use crate::mem::{self, forget};
use crate::num::NonZeroU64;
use crate::num::NonZeroUsize;
use crate::panic;
use crate::panicking;
use crate::pin::Pin;
use crate::ptr::addr_of_mut;
use crate::str;
use crate::sync::Arc;
use crate::sys::thread as imp;
use crate::sys_common::thread;
use crate::sys_common::thread_info;
use crate::sys_common::thread_parking::Parker;
use crate::sys_common::{AsInner, IntoInner};
use crate::time::Duration;

#[stable(feature = "scoped_threads", since = "1.63.0")]
mod scoped;

#[stable(feature = "scoped_threads", since = "1.63.0")]
pub use scoped::{scope, Scope, ScopedJoinHandle};

////////////////////////////////////////////////////////////////////////////////
// 线程本地存储
////////////////////////////////////////////////////////////////////////////////

#[macro_use]
mod local;

cfg_if::cfg_if! {
    if #[cfg(test)] {
        // 避免在 crate 和 realstd 之间复制与线程本地相关联的全局状态。
        // Miri 依赖于此。
        pub use realstd::thread::{local_impl, AccessError, LocalKey};
    } else {
        #[stable(feature = "rust1", since = "1.0.0")]
        pub use self::local::{AccessError, LocalKey};

        // thread_local!{} 宏使用的实现细节。
        #[doc(hidden)]
        #[unstable(feature = "thread_local_internals", issue = "none")]
        pub mod local_impl {
            pub use crate::sys::common::thread_local::{thread_local_inner, Key};
        }
    }
}

////////////////////////////////////////////////////////////////////////////////
// Builder
////////////////////////////////////////////////////////////////////////////////

/// 线程工厂，可用于配置新线程的属性。
///
/// 可以在其上链接方法以对其进行配置。
///
/// 有两种配置可供选择：
///
/// - [`name`]: specifies an [associated name for the thread][naming-threads]
/// - [`stack_size`]: specifies the [desired stack size for the thread][stack-size]
///
/// [`spawn`] 方法将获取构建器的所有权，并使用给定的配置为线程句柄创建 [`io::Result`]。
///
/// [`thread::spawn`] free 函数使用带有默认配置的 `Builder`，并且 [`unwrap`] 是其返回值。
///
/// 当您想从启动线程失败中恢复时，您可能想使用 [`spawn`] 而不是 [`thread::spawn`]，实际上，free 函数会在 `Builder` 方法返回 [`io::Result`] 时 panic。
///
///
/// # Examples
///
/// ```
/// use std::thread;
///
/// let builder = thread::Builder::new();
///
/// let handler = builder.spawn(|| {
///     // 线程代码
/// }).unwrap();
///
/// handler.join().unwrap();
/// ```
///
/// [`stack_size`]: Builder::stack_size
/// [`name`]: Builder::name
/// [`spawn`]: Builder::spawn
/// [`thread::spawn`]: spawn
/// [`io::Result`]: crate::io::Result
/// [`unwrap`]: crate::result::Result::unwrap
/// [naming-threads]: ./index.html#naming-threads
/// [stack-size]: ./index.html#stack-size
///
///
///
///
#[must_use = "must eventually spawn the thread"]
#[stable(feature = "rust1", since = "1.0.0")]
#[derive(Debug)]
pub struct Builder {
    // 未来线程的名称，以在 panic 消息中进行标识
    name: Option<String>,
    // 衍生线程的栈大小 (以字节为单位)
    stack_size: Option<usize>,
}

impl Builder {
    /// 生成用于生成线程的基本配置，从中可以链接配置方法。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::thread;
    ///
    /// let builder = thread::Builder::new()
    ///                               .name("foo".into())
    ///                               .stack_size(32 * 1024);
    ///
    /// let handler = builder.spawn(|| {
    ///     // 线程代码
    /// }).unwrap();
    ///
    /// handler.join().unwrap();
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn new() -> Builder {
        Builder { name: None, stack_size: None }
    }

    /// 命名未来线程。当前，该名称仅用于 panic 消息中的标识。
    ///
    /// 该名称不能包含空字节 (`\0`)。
    ///
    /// 有关命名线程的更多信息，请参见 [模块级文档][naming-threads]。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::thread;
    ///
    /// let builder = thread::Builder::new()
    ///     .name("foo".into());
    ///
    /// let handler = builder.spawn(|| {
    ///     assert_eq!(thread::current().name(), Some("foo"))
    /// }).unwrap();
    ///
    /// handler.join().unwrap();
    /// ```
    ///
    /// [naming-threads]: ./index.html#naming-threads
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn name(mut self, name: String) -> Builder {
        self.name = Some(name);
        self
    }

    /// 设置新线程的栈大小 (以字节为单位)。
    ///
    /// 如果平台指定最小栈大小，则实际栈大小可能大于这个值。
    ///
    /// 有关线程的栈大小的更多信息，请参见 [模块级文档][stack-size]。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// use std::thread;
    ///
    /// let builder = thread::Builder::new().stack_size(32 * 1024);
    /// ```
    ///
    /// [stack-size]: ./index.html#stack-size
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn stack_size(mut self, size: usize) -> Builder {
        self.stack_size = Some(size);
        self
    }

    /// 通过获取 `Builder` 的所有权产生一个新线程，并向其 [`JoinHandle`] 返回一个 [`io::Result`]。
    ///
    /// 衍生的线程可能比调用者活得长 (除非调用者线程是主线程; 当主线程结束时，整个进程将终止)。
    /// 连接句柄可用于在新线程终止时阻塞，包括恢复其 panics。
    ///
    /// 有关更完整的文档，请参见 [`thread::spawn`][`spawn`]。
    ///
    /// # Errors
    ///
    /// 与 [`spawn`] 的 free 函数不同，此方法产生 [`io::Result`] 来捕获在操作系统级别创建线程的任何失败。
    ///
    /// [`io::Result`]: crate::io::Result
    ///
    /// # Panics
    ///
    /// 如果设置了线程名称并且它包含空字节，就会出现 panic。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::thread;
    ///
    /// let builder = thread::Builder::new();
    ///
    /// let handler = builder.spawn(|| {
    ///     // 线程代码
    /// }).unwrap();
    ///
    /// handler.join().unwrap();
    /// ```
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn spawn<F, T>(self, f: F) -> io::Result<JoinHandle<T>>
    where
        F: FnOnce() -> T,
        F: Send + 'static,
        T: Send + 'static,
    {
        unsafe { self.spawn_unchecked(f) }
    }

    /// 通过获取 `Builder` 的所有权来产生不受任何生命周期限制的新线程，并将 [`io::Result`] 返回其 [`JoinHandle`]。
    ///
    /// 衍生的线程可能比调用者活得长 (除非调用者线程是主线程; 当主线程结束时，整个进程将终止)。
    /// 连接句柄可用于在新线程终止时阻塞，包括恢复其 panics。
    ///
    /// 此方法与 [`thread::Builder::spawn`][`Builder::spawn`] 相同，不同之处在于宽松的生命周期界限使其不安全。
    /// 有关更完整的文档，请参见 [`thread::spawn`][`spawn`]。
    ///
    /// # Errors
    ///
    /// 与 [`spawn`] 的 free 函数不同，此方法产生 [`io::Result`] 来捕获在操作系统级别创建线程的任何失败。
    ///
    /// # Panics
    ///
    /// 如果设置了线程名称并且它包含空字节，就会出现 panic。
    ///
    /// # Safety
    ///
    /// 调用者必须确保新建线程的生命周期不会超过所提供线程闭包及其返回类型中的任何引用。
    /// 可以通过两种方式保证这一点：
    ///
    /// - 确保在丢弃任何引用数据之前已调用 [`join`][`JoinHandle::join`]
    /// - 仅使用具有 `'static` 生命周期界限的类型，即没有 `'static` 引用或仅具有 `'static` 引用的类型 ([`thread::Builder::spawn`][`Builder::spawn`] 和 [`thread::spawn`][`spawn`] 都静态地强制执行此属性)
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(thread_spawn_unchecked)]
    /// use std::thread;
    ///
    /// let builder = thread::Builder::new();
    ///
    /// let x = 1;
    /// let thread_x = &x;
    ///
    /// let handler = unsafe {
    ///     builder.spawn_unchecked(move || {
    ///         println!("x = {}", *thread_x);
    ///     }).unwrap()
    /// };
    ///
    /// // 调用者必须确保已调用 `join()`，否则，如果在执行线程闭包之前 `x` 被丢弃，则可以访问释放的内存！
    /////
    /////
    /// handler.join().unwrap();
    /// ```
    ///
    /// [`io::Result`]: crate::io::Result
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[unstable(feature = "thread_spawn_unchecked", issue = "55132")]
    pub unsafe fn spawn_unchecked<'a, F, T>(self, f: F) -> io::Result<JoinHandle<T>>
    where
        F: FnOnce() -> T,
        F: Send + 'a,
        T: Send + 'a,
    {
        Ok(JoinHandle(unsafe { self.spawn_unchecked_(f, None) }?))
    }

    unsafe fn spawn_unchecked_<'a, 'scope, F, T>(
        self,
        f: F,
        scope_data: Option<Arc<scoped::ScopeData>>,
    ) -> io::Result<JoinInner<'scope, T>>
    where
        F: FnOnce() -> T,
        F: Send + 'a,
        T: Send + 'a,
        'scope: 'a,
    {
        let Builder { name, stack_size } = self;

        let stack_size = stack_size.unwrap_or_else(thread::min_stack);

        let my_thread = Thread::new(name.map(|name| {
            CString::new(name).expect("thread name may not contain interior null bytes")
        }));
        let their_thread = my_thread.clone();

        let my_packet: Arc<Packet<'scope, T>> = Arc::new(Packet {
            scope: scope_data,
            result: UnsafeCell::new(None),
            _marker: PhantomData,
        });
        let their_packet = my_packet.clone();

        let output_capture = crate::io::set_output_capture(None);
        crate::io::set_output_capture(output_capture.clone());

        // 在 `MaybeUninit` 中通过 `f` 因为实际上那个闭包可能 *run 比 `F`* 的生命周期长。
        // 有关详细信息，请参见 <https://github.com/rust-lang/rust/issues/101983>。
        // 为了防止泄漏，我们使用丢弃其内容的包装器。
        #[repr(transparent)]
        struct MaybeDangling<T>(mem::MaybeUninit<T>);
        impl<T> MaybeDangling<T> {
            fn new(x: T) -> Self {
                MaybeDangling(mem::MaybeUninit::new(x))
            }
            fn into_inner(self) -> T {
                // SAFETY: 我们总是被初始化。
                let ret = unsafe { self.0.assume_init_read() };
                // 确保我们不丢弃。
                mem::forget(self);
                ret
            }
        }
        impl<T> Drop for MaybeDangling<T> {
            fn drop(&mut self) {
                // SAFETY: 我们总是被初始化。
                unsafe { self.0.assume_init_drop() };
            }
        }

        let f = MaybeDangling::new(f);
        let main = move || {
            if let Some(name) = their_thread.cname() {
                imp::Thread::set_name(name);
            }

            crate::io::set_output_capture(output_capture);

            // SAFETY: 我们构造了初始化的 `f`。
            let f = f.into_inner();
            // SAFETY: 传递的堆栈守卫是当前线程的守卫。
            // 这意味着当前线程的栈和新线程的栈已被正确设置并相互保护。
            //
            thread_info::set(unsafe { imp::guard::current() }, their_thread);
            let try_result = panic::catch_unwind(panic::AssertUnwindSafe(|| {
                crate::sys_common::backtrace::__rust_begin_short_backtrace(f)
            }));
            // SAFETY: `their_packet` 正好在其上方构建并由闭包 (它是 Arc<...>) 移动，并且 `my_packet` 将与该闭包存储在同一 `JoinInner` 中，这意味着该可变的是安全的 (不对其进行修改并影响一个远的值)。
            //
            //
            //
            unsafe { *their_packet.result.get() = Some(try_result) };
            // 这里 `their_packet` 得到那个丢弃，如果这是最后一个 `Arc` 数据包将调用 `decrement_num_running_threads` 并因此发出这个线程完成的信号。
            //
            //
            drop(their_packet);
            // 到这里，生命周期 `'a` 甚至 `'scope` 都可以结束了。
            // `main` 在返回之前会继续运行一段时间。
        };

        if let Some(scope_data) = &my_packet.scope {
            scope_data.increment_num_running_threads();
        }

        Ok(JoinInner {
            // SAFETY:
            //
            // `imp::Thread::new` 接受一个带有 `'static` 生命周期的闭包，因为它通过 FFI 传递或以其他方式与没有概念或方式执行生命周期的线程原语一起使用。
            //
            // 如本函数文档的 `Safety` 部分所述，此函数的调用者需要确保传入的生命周期对于线程的生命周期足够长。
            //
            //
            // 同样，`sys` 实现必须保证在线程终止后，对闭包的引用不存在，这由 `Thread::join` 返回表示。
            //
            //
            //
            //
            //
            native: unsafe {
                imp::Thread::new(
                    stack_size,
                    mem::transmute::<Box<dyn FnOnce() + 'a>, Box<dyn FnOnce() + 'static>>(
                        Box::new(main),
                    ),
                )?
            },
            thread: my_thread,
            packet: my_packet,
        })
    }
}

////////////////////////////////////////////////////////////////////////////////
// free 函数
////////////////////////////////////////////////////////////////////////////////

/// 产生一个新线程，并为其返回一个 [`JoinHandle`]。
///
/// 连接句柄提供了一个 [`join`] 方法，可以用来连接新生成的线程。如果生成的线程发生 panics，那么 [`join`] 将返回一个 [`Err`]，其中包含了提供给 [`panic!`] 的参数。
///
/// 如果连接句柄被丢弃了，则新生成的线程将被隐式地 *分离*。
/// 在这种情况下，新生成的线程可能不再被连接。
/// (程序有责任最终连接它创建的线程，或者将它们分离; 否则，将导致资源泄漏。)
///
/// 此调用将使用 [`Builder`] 的默认参数创建一个线程，如果要指定栈大小或线程名称，请使用此 API。
///
/// 正如您在 `spawn` 的签名中看到的那样，对于赋予 `spawn` 的闭包及其返回值都有两个约束，让我们对其进行解释：
///
/// - `'static` 约束意味着闭包及其返回值必须具有整个程序执行的生命周期。这是因为线程可以比它们被创建时的生命周期更长。
///
///   确实，如果线程以及它的返回值可以比它们的调用者活得更久，我们需要确保它们以后仍然有效，并且因为我们不能知道它什么时候返回，因此需要使它们直到程序结束时尽可能有效，因此是 `'static` 生命周期。
///
/// - [`Send`] 约束是因为闭包需要通过值从产生它的线程传递到新线程。它的返回值将需要从新线程传递到它被 `join` 的线程。
///   提醒一下，[`Send`] 标记 trait 表示从一个线程传递到另一个线程是安全的。[`Sync`] 表示将引用从一个线程传递到另一个线程是安全的。
///
/// # Panics
///
/// 如果操作系统无法创建线程，就会出现 panics。使用 [`Builder::spawn`] 从此类错误中恢复。
///
/// # Examples
///
/// 创建一个线程。
///
/// ```
/// use std::thread;
///
/// let handler = thread::spawn(|| {
///     // 线程代码
/// });
///
/// handler.join().unwrap();
/// ```
///
/// 如模块文档中所述，线程通常是使用 [`channels`] 进行通信的，通常情况下是这样的。
///
/// 此示例还展示了如何使用 `move`，以便将值的所有权授予线程。
///
/// ```
/// use std::thread;
/// use std::sync::mpsc::channel;
///
/// let (tx, rx) = channel();
///
/// let sender = thread::spawn(move || {
///     tx.send("Hello, thread".to_owned())
///         .expect("Unable to send on channel");
/// });
///
/// let receiver = thread::spawn(move || {
///     let value = rx.recv().expect("Unable to receive from channel");
///     println!("{value}");
/// });
///
/// sender.join().expect("The sender thread has panicked");
/// receiver.join().expect("The receiver thread has panicked");
/// ```
///
/// 一个线程也可以通过 [`JoinHandle`] 来返回一个值，您可以使用它进行异步计算 (不过 futures 可能更合适)。
///
/// ```
/// use std::thread;
///
/// let computation = thread::spawn(|| {
///     // 一些昂贵的计算。
///     42
/// });
///
/// let result = computation.join().unwrap();
/// println!("{result}");
/// ```
///
/// [`channels`]: crate::sync::mpsc
/// [`join`]: JoinHandle::join
/// [`Err`]: crate::result::Result::Err
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn spawn<F, T>(f: F) -> JoinHandle<T>
where
    F: FnOnce() -> T,
    F: Send + 'static,
    T: Send + 'static,
{
    Builder::new().spawn(f).expect("failed to spawn thread")
}

/// 获取调用它的线程的句柄。
///
/// # Examples
///
/// 使用 `thread::current()` 获取当前线程的句柄：
///
/// ```
/// use std::thread;
///
/// let handler = thread::Builder::new()
///     .name("named thread".into())
///     .spawn(|| {
///         let handle = thread::current();
///         assert_eq!(handle.name(), Some("named thread"));
///     })
///     .unwrap();
///
/// handler.join().unwrap();
/// ```
#[must_use]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn current() -> Thread {
    thread_info::current_thread().expect(
        "use of std::thread::current() is not possible \
         after the thread's local data has been destroyed",
    )
}

/// 协同地将时间片交给操作系统调度程序。
///
/// 这会调用底层操作系统调度程序的 yield 原语，表明调用线程愿意放弃其剩余的时间片，以便操作系统可以在 CPU 上调度其他线程。
///
/// 在循环中让步的一个缺点是，如果操作系统没有任何其他就绪线程在当前 CPU 上运行，该线程将有效地进行忙等待，这会浪费 CPU 时间和精力。
///
/// 因此，在等待感兴趣的事件时，程序员的首选应该是使用同步设备，例如 [`channel`]、[`Condvar`]、[`Mutex`] 或 [`join`]，因为这些原语是以阻塞方式实现，放弃 CPU 直到感兴趣的事件发生，避免重复让步。
///
///
/// 因此，`yield_now` 应该很少使用，主要是在需要重复轮询的情况下，因为没有其他合适的方法可以了解何时发生了感兴趣的事件。
///
/// # Examples
///
/// ```
/// use std::thread;
///
/// thread::yield_now();
/// ```
///
/// [`channel`]: crate::sync::mpsc
/// [`join`]: JoinHandle::join
/// [`Condvar`]: crate::sync::Condvar
/// [`Mutex`]: crate::sync::Mutex
///
///
///
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn yield_now() {
    imp::Thread::yield_now()
}

/// 确定当前线程是否由于 panic 而处于展开状态。
///
/// 此特性的一个常见用途是在编写不安全代码时毒害共享资源，方法是在调用 `drop` 时检查 `panic`。
///
/// 编写安全代码时通常不需要这样做，因为当线程在持有锁时 panic，[`Mutex`][Mutex] 已经中毒了。
///
/// 这也可以在多线程应用程序中使用，以便向其他线程发送消息，警告某个线程已发生 panic (例如，出于监视目的)。
///
///
/// # Examples
///
/// ```should_panic
/// use std::thread;
///
/// struct SomeStruct;
///
/// impl Drop for SomeStruct {
///     fn drop(&mut self) {
///         if thread::panicking() {
///             println!("dropped while unwinding");
///         } else {
///             println!("dropped while not unwinding");
///         }
///     }
/// }
///
/// {
///     print!("a: ");
///     let a = SomeStruct;
/// }
///
/// {
///     print!("b: ");
///     let b = SomeStruct;
///     panic!()
/// }
/// ```
///
/// [Mutex]: crate::sync::Mutex
///
///
///
#[inline]
#[must_use]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn panicking() -> bool {
    panicking::panicking()
}

/// 使用 [`sleep`]。
///
/// 使当前线程休眠至少指定的时间。
///
/// 由于调度细节或平台相关的功能，线程的睡眠时间可能比指定的持续时间更长。
/// 它永远不会少睡。
///
/// 该函数正在阻塞，因此不应在 `async` 函数中使用。
///
/// # 特定于平台的行为
///
/// 在 Unix 平台上，底层的系统调用可能会由于虚假唤醒或信号处理程序而中断。
/// 为了确保至少在指定的持续时间内发生睡眠，此函数可以多次调用该系统。
///
///
/// # Examples
///
/// ```no_run
/// use std::thread;
///
/// // 让我们睡 2 秒钟：
/// thread::sleep_ms(2000);
/// ```
///
#[stable(feature = "rust1", since = "1.0.0")]
#[deprecated(since = "1.6.0", note = "replaced by `std::thread::sleep`")]
pub fn sleep_ms(ms: u32) {
    sleep(Duration::from_millis(ms as u64))
}

/// 使当前线程休眠至少指定的时间。
///
/// 由于调度细节或平台相关的功能，线程的睡眠时间可能比指定的持续时间更长。它永远不会少睡。
///
/// 该函数正在阻塞，因此不应在 `async` 函数中使用。
///
/// # 特定于平台的行为
///
/// 在 Unix 平台上，底层的系统调用可能会由于虚假唤醒或信号处理程序而中断。
/// 为了确保至少在指定的持续时间内发生睡眠，此函数可以多次调用该系统。
/// 不支持纳秒级睡眠精度的平台会将 `dur` 舍入为最接近的睡眠时间粒度。
///
/// 目前，在 Unix 平台上指定零持续时间会立即返回，而不会调用底层 [`nanosleep`] syscall，而在 Windows 平台上，始终调用底层 [`Sleep`] syscall。
///
/// 如果要产生当前时间片，则可能需要使用 [`yield_now`]。
///
/// [`nanosleep`]: https://linux.die.net/man/2/nanosleep
/// [`Sleep`]: https://docs.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-sleep
///
/// # Examples
///
/// ```no_run
/// use std::{thread, time};
///
/// let ten_millis = time::Duration::from_millis(10);
/// let now = time::Instant::now();
///
/// thread::sleep(ten_millis);
///
/// assert!(now.elapsed() >= ten_millis);
/// ```
///
///
///
///
///
///
#[stable(feature = "thread_sleep", since = "1.4.0")]
pub fn sleep(dur: Duration) {
    imp::Thread::sleep(dur)
}

/// 用于确保 `park` 和 `park_timeout` 不 unwind，因为如果处理不当会导致未定义的行为 (有关上下文，请参见 #102398)。
///
struct PanicGuard;

impl Drop for PanicGuard {
    fn drop(&mut self) {
        rtabort!("an irrecoverable error occurred while synchronizing threads")
    }
}

/// 阻塞，除非或直到当前线程的 token 可用为止。
///
/// 对 `park` 的调用不能保证线程将永远保持驻留状态，因此调用者应为此做好准备。
/// 但是，保证这个函数不会 panic (如果执行遇到一些罕见的错误，它可能会中止进程)。
///
/// # park 和 unpark
///
/// 每个线程都通过 [`thread::park`][`park`] 函数和 [`thread::Thread::unpark`][`unpark`] 方法提供了一些基本的阻塞支持。
/// [`park`] 阻塞当前线程，然后可以通过在阻塞线程的句柄上调用 [`unpark`] 方法从另一个线程恢复当前线程。
///
/// 从概念上讲，每个 [`Thread`] 句柄都有一个关联的 token，该 token 最初不存在：
///
/// * [`thread::park`][`park`] 函数会阻塞当前线程，除非或直到 token 可用于其线程句柄为止，否则该原子将自动消耗 token。
/// 它也可能虚假地返回，而不消耗 token。
/// [`thread::park_timeout`] 执行相同的操作，但允许指定阻塞线程的最长时间。
///
/// * [`Thread`] 上的 [`unpark`] 方法原子地使 token (如果尚未提供) 可用。
/// 由于最初不存在 token，因此 [`unpark`] 后跟 [`park`] 将导致第二个调用立即返回。
///
/// 换句话说，每个 [`Thread`] 的行为都类似于自旋锁，可以使用 `park` 和 `unpark` 进行锁定和解锁。
///
/// 请注意，被取消阻止并不意味着与取消该线程的某个人进行任何同步，这也可能是虚假的。
/// 例如，将 [`park`] 和 [`unpark`] 都立即返回而无需执行任何操作将是有效但效率低下的实现。
///
/// 通常通过获取当前线程的句柄，将该句柄放置在共享数据结构体中，以便其他线程可以找到它，然后 `park` 在循环中来使用该 API。
///
/// 当满足某些所需条件时，另一个线程将在句柄上调用 [`unpark`]。
///
/// 这种设计的动机是双重的：
///
/// * 在构建新的同步原语时，它无需分配互斥锁和 condvar。线程已经提供了基本的 blocking/signaling。
///
/// * 它可以在许多平台上非常有效地实现。
///
/// # Examples
///
/// ```
/// use std::thread;
/// use std::sync::{Arc, atomic::{Ordering, AtomicBool}};
/// use std::time::Duration;
///
/// let flag = Arc::new(AtomicBool::new(false));
/// let flag2 = Arc::clone(&flag);
///
/// let parked_thread = thread::spawn(move || {
///     // 我们要等到标志被设置。
///     // 我们可以旋转，但是使用 park/unpark 效率更高。
///     while !flag2.load(Ordering::Acquire) {
///         println!("Parking thread");
///         thread::park();
///         // 我们可以伪装地到达这里，即在下面的 10ms 结束之前！
///         // 但这没问题，我们一直处于循环状态，直到仍然设置了标志。
///         println!("Thread unparked");
///     }
///     println!("Flag received");
/// });
///
/// // 花费一些时间来生成线程。
/// thread::sleep(Duration::from_millis(10));
///
/// // 设置标志，并让线程唤醒。
/// // 这里没有竞态条件，如果 `unpark` 首先出现，则 `park` 将立即返回。
/////
/// // 因此，没有死锁的风险。
/// flag.store(true, Ordering::Release);
/// println!("Unpark the thread");
/// parked_thread.thread().unpark();
///
/// parked_thread.join().unwrap();
/// ```
///
/// [`unpark`]: Thread::unpark
/// [`thread::park_timeout`]: park_timeout
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn park() {
    let guard = PanicGuard;
    // SAFETY: 在该线程所拥有的 parker 上调用 park_timeout。
    unsafe {
        current().inner.as_ref().parker().park();
    }
    // 没有发生 panic，不要触发。
    forget(guard);
}

/// 使用 [`park_timeout`]。
///
/// 除非直到当前线程的 token 可用或达到指定的持续时间 (否则可能会虚假唤醒)，否则将阻塞。
///
/// 该函数的语义与 [`park`] 等效，除了线程被阻塞的时间不超过 `dur`。
/// 由于抢占或平台差异等异常情况可能不会导致最长等待时间精确到 `ms` 长，因此不应将此方法用于精确计时。
///
///
/// 有关更多详细信息，请参见 [park 文档][`park`]。
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
#[deprecated(since = "1.6.0", note = "replaced by `std::thread::park_timeout`")]
pub fn park_timeout_ms(ms: u32) {
    park_timeout(Duration::from_millis(ms as u64))
}

/// 除非直到当前线程的 token 可用或达到指定的持续时间 (否则可能会虚假唤醒)，否则将阻塞。
///
/// 该函数的语义与 [`park`][park] 等效，除了线程被阻塞的时间不超过 `dur`。
/// 由于抢占或平台差异等异常情况可能不会导致最长等待时间精确到 `dur` 长，因此不应将此方法用于精确计时。
///
///
/// 有关更多详细信息，请参见 [park 文档][park]。
///
/// # 特定于平台的行为
///
/// 不支持纳秒级睡眠精度的平台会将 `dur` 舍入为最接近的睡眠时间粒度。
///
/// # Examples
///
/// 等待超时完全到期：
///
/// ```rust,no_run
/// use std::thread::park_timeout;
/// use std::time::{Instant, Duration};
///
/// let timeout = Duration::from_secs(2);
/// let beginning_park = Instant::now();
///
/// let mut timeout_remaining = timeout;
/// loop {
///     park_timeout(timeout_remaining);
///     let elapsed = beginning_park.elapsed();
///     if elapsed >= timeout {
///         break;
///     }
///     println!("restarting park_timeout after {elapsed:?}");
///     timeout_remaining = timeout - elapsed;
/// }
/// ```
///
///
///
///
#[stable(feature = "park_timeout", since = "1.4.0")]
pub fn park_timeout(dur: Duration) {
    let guard = PanicGuard;
    // SAFETY: 在该线程所拥有的 parker 上调用 park_timeout。
    unsafe {
        current().inner.as_ref().parker().park_timeout(dur);
    }
    // 没有发生 panic，不要触发。
    forget(guard);
}

////////////////////////////////////////////////////////////////////////////////
// ThreadId
////////////////////////////////////////////////////////////////////////////////

/// 正在运行的线程的唯一标识符。
///
/// `ThreadId` 是一个不透明的对象，它唯一的标识了在进程生命周期期中创建的每个线程。`ThreadId`s 保证不会被重用，即使线程终止时也是如此。
/// `ThreadId` 受 Rust 标准库的控制，`ThreadId` 和底层平台的线程标识符概念之间可能没有任何关系 -- 因此，这两个概念不能互换使用。
///
/// 可以从 [`Thread`] 上的 [`id`] 方法中检索 `ThreadId`。
///
/// # Examples
///
/// ```
/// use std::thread;
///
/// let other_thread = thread::spawn(|| {
///     thread::current().id()
/// });
///
/// let other_thread_id = other_thread.join().unwrap();
/// assert!(thread::current().id() != other_thread_id);
/// ```
///
/// [`id`]: Thread::id
///
///
///
#[stable(feature = "thread_id", since = "1.19.0")]
#[derive(Eq, PartialEq, Clone, Copy, Hash, Debug)]
pub struct ThreadId(NonZeroU64);

impl ThreadId {
    // 生成一个新的唯一线程 ID。
    fn new() -> ThreadId {
        #[cold]
        fn exhausted() -> ! {
            panic!("failed to generate unique thread ID: bitspace exhausted")
        }

        cfg_if::cfg_if! {
            if #[cfg(target_has_atomic = "64")] {
                use crate::sync::atomic::{AtomicU64, Ordering::Relaxed};

                static COUNTER: AtomicU64 = AtomicU64::new(0);

                let mut last = COUNTER.load(Relaxed);
                loop {
                    let Some(id) = last.checked_add(1) else {
                        exhausted();
                    };

                    match COUNTER.compare_exchange_weak(last, id, Relaxed, Relaxed) {
                        Ok(_) => return ThreadId(NonZeroU64::new(id).unwrap()),
                        Err(id) => last = id,
                    }
                }
            } else {
                use crate::sync::{Mutex, PoisonError};

                static COUNTER: Mutex<u64> = Mutex::new(0);

                let mut counter = COUNTER.lock().unwrap_or_else(PoisonError::into_inner);
                let Some(id) = counter.checked_add(1) else {
                    // 如果 panic 处理程序最终调用 `ThreadId::new()`，请避免获取可重入锁。
                    //
                    drop(counter);
                    exhausted();
                };

                *counter = id;
                drop(counter);
                ThreadId(NonZeroU64::new(id).unwrap())
            }
        }
    }

    /// 这将返回此 `ThreadId` 标识的线程的数字标识符。
    ///
    /// 如类型本身的文档中所述，它本质上是一个不透明的 ID，但可以保证每个线程都是唯一的。
    /// 返回的值是完全不透明的 - 仅相等测试是稳定的。
    /// 请注意，不能保证新线程将返回哪些值，并且在 Rust 版本之间可能会改变。
    ///
    ///
    ///
    #[must_use]
    #[unstable(feature = "thread_id_value", issue = "67939")]
    pub fn as_u64(&self) -> NonZeroU64 {
        self.0
    }
}

////////////////////////////////////////////////////////////////////////////////
// Thread
////////////////////////////////////////////////////////////////////////////////

/// `Thread` 句柄的内部表示
struct Inner {
    name: Option<CString>, // 保证为 UTF-8
    id: ThreadId,
    parker: Parker,
}

impl Inner {
    fn parker(self: Pin<&Self>) -> Pin<&Parker> {
        unsafe { Pin::map_unchecked(self, |inner| &inner.parker) }
    }
}

#[derive(Clone)]
#[stable(feature = "rust1", since = "1.0.0")]
/// 线程的句柄。
///
/// 线程通过 `Thread` 类型表示，您可以通过以下两种方式之一来获取：
///
/// * 通过生成一个新线程，例如使用 [`thread::spawn`][`spawn`] 函数，并在 [`JoinHandle`] 上调用 [`thread`][`JoinHandle::thread`]。
/// * 通过使用 [`thread::current`] 函数来请求当前线程。
///
/// [`thread::current`] 函数甚至可用于不是由该模块的 API 生成的线程。
///
/// 通常不需要自己创建 `Thread` 结构体，而应使用 `spawn` 之类的函数来创建新线程，有关更多详细信息，请参见 [`Builder`] 和 [`spawn`] 的文档。
///
///
/// [`thread::current`]: current
///
///
///
///
///
pub struct Thread {
    inner: Pin<Arc<Inner>>,
}

impl Thread {
    // 如果名称包含 nul，则仅在内部用于构造线程对象，而不会发生 panics。
    //
    pub(crate) fn new(name: Option<CString>) -> Thread {
        // 我们必须在这里使用 `unsafe` 来就地构造 `Parker`，这是 UNIX 实现所必需的。
        //
        //
        // SAFETY: 我们在创建后立即固定 Arc，因此它的地址永远不会改变。
        //
        let inner = unsafe {
            let mut arc = Arc::<Inner>::new_uninit();
            let ptr = Arc::get_mut_unchecked(&mut arc).as_mut_ptr();
            addr_of_mut!((*ptr).name).write(name);
            addr_of_mut!((*ptr).id).write(ThreadId::new());
            Parker::new_in_place(addr_of_mut!((*ptr).parker));
            Pin::new_unchecked(arc.assume_init())
        };

        Thread { inner }
    }

    /// 通过原子方式使句柄的 token 可用 (如果尚不可用)。
    ///
    /// 每个线程都通过 [`park`][park] 函数和 `unpark()` 方法提供了一些基本的阻塞支持。
    /// 这些可用作自旋锁的 CPU 效率更高的实现。
    ///
    /// 有关更多详细信息，请参见 [park 文档][park]。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::thread;
    /// use std::time::Duration;
    ///
    /// let parked_thread = thread::Builder::new()
    ///     .spawn(|| {
    ///         println!("Parking thread");
    ///         thread::park();
    ///         println!("Thread unparked");
    ///     })
    ///     .unwrap();
    ///
    /// // 花费一些时间来生成线程。
    /// thread::sleep(Duration::from_millis(10));
    ///
    /// println!("Unpark the thread");
    /// parked_thread.thread().unpark();
    ///
    /// parked_thread.join().unwrap();
    /// ```
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    #[inline]
    pub fn unpark(&self) {
        self.inner.as_ref().parker().unpark();
    }

    /// 获取线程的唯一标识符。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::thread;
    ///
    /// let other_thread = thread::spawn(|| {
    ///     thread::current().id()
    /// });
    ///
    /// let other_thread_id = other_thread.join().unwrap();
    /// assert!(thread::current().id() != other_thread_id);
    /// ```
    #[stable(feature = "thread_id", since = "1.19.0")]
    #[must_use]
    pub fn id(&self) -> ThreadId {
        self.inner.id
    }

    /// 获取线程的名称。
    ///
    /// 有关命名线程的更多信息，请参见 [模块级文档][naming-threads]。
    ///
    ///
    /// # Examples
    ///
    /// 默认情况下，线程未指定名称：
    ///
    /// ```
    /// use std::thread;
    ///
    /// let builder = thread::Builder::new();
    ///
    /// let handler = builder.spawn(|| {
    ///     assert!(thread::current().name().is_none());
    /// }).unwrap();
    ///
    /// handler.join().unwrap();
    /// ```
    ///
    /// 具有指定名称的线程：
    ///
    /// ```
    /// use std::thread;
    ///
    /// let builder = thread::Builder::new()
    ///     .name("foo".into());
    ///
    /// let handler = builder.spawn(|| {
    ///     assert_eq!(thread::current().name(), Some("foo"))
    /// }).unwrap();
    ///
    /// handler.join().unwrap();
    /// ```
    ///
    /// [naming-threads]: ./index.html#naming-threads
    #[stable(feature = "rust1", since = "1.0.0")]
    #[must_use]
    pub fn name(&self) -> Option<&str> {
        self.cname().map(|s| unsafe { str::from_utf8_unchecked(s.to_bytes()) })
    }

    fn cname(&self) -> Option<&CStr> {
        self.inner.name.as_deref()
    }
}

#[stable(feature = "rust1", since = "1.0.0")]
impl fmt::Debug for Thread {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Thread")
            .field("id", &self.id())
            .field("name", &self.name())
            .finish_non_exhaustive()
    }
}

////////////////////////////////////////////////////////////////////////////////
// JoinHandle
////////////////////////////////////////////////////////////////////////////////

/// 线程专用的 [`Result`] 的类型。
///
/// 指示线程退出的方式。
///
/// `Result::Err` 变体中包含的值是线程 panic 时使用的值；
/// 也就是说，调用了 `panic!` 宏的参数。
/// 与正常错误不同，此值不实现 [`Error`](crate::error::Error) trait。
///
/// 因此，处理线程 panic 的明智方法是：
///
/// 1. 用 [`std::panic::resume_unwind`] 传播 panic
/// 2.
/// 或者，如果线程是用来隔离系统级故障的子系统边界，则匹配 `Err` 变体，并以适当的方式处理 panic
///
///
/// 一个线程在没有 panic 的情况下完成被认为是成功退出。
///
/// # Examples
///
/// 匹配已连接线程的结果：
///
/// ```no_run
/// use std::{fs, thread, panic};
///
/// fn copy_in_thread() -> thread::Result<()> {
///     thread::spawn(|| {
///         fs::copy("foo.txt", "bar.txt").unwrap();
///     }).join()
/// }
///
/// fn main() {
///     match copy_in_thread() {
///         Ok(_) => println!("copy succeeded"),
///         Err(e) => panic::resume_unwind(e),
///     }
/// }
/// ```
///
/// [`Result`]: crate::result::Result
/// [`std::panic::resume_unwind`]: crate::panic::resume_unwind
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub type Result<T> = crate::result::Result<T, Box<dyn Any + Send + 'static>>;

// 该数据包用于在程序的新建线程和对象部分之间传递返回值。
// 它是通过 `Arc` 共享的，这里不需要互斥锁，因为同步发生在 `join()` 上 (调用者在线程退出之前，永远不会读取这个数据包)。
//
//
// 数据包的 Arc 存储到 `JoinInner` 中，而 `JoinInner` 又放置在 `JoinHandle` 中。
//
//
struct Packet<'scope, T> {
    scope: Option<Arc<scoped::ScopeData>>,
    result: UnsafeCell<Option<Result<T>>>,
    _marker: PhantomData<Option<&'scope scoped::ScopeData>>,
}

// 由于使用了 `UnsafeCell`，我们需要手动实现 Sync。
// `T` 类型应该一直是 Send (否则无法创建线程) 并且 Packet 是 Sync，因为所有对 `UnsafeCell` 的访问都是同步的 (通过 `join()` 边界)，并且 `ScopeData` 是 Sync。
//
//
unsafe impl<'scope, T: Sync> Sync for Packet<'scope, T> {}

impl<'scope, T> Drop for Packet<'scope, T> {
    fn drop(&mut self) {
        // 如果此数据包是针对在作用域中运行的线程，该线程发生了 panic，并且没有人使用 panic 的有效载荷，我们确保作用域函数也发生 panic。
        //
        //
        let unhandled_panic = matches!(self.result.get_mut(), Some(Err(_)));
        // 在不导致展开的情况下丢弃结果。
        // 这仅与未加入 () 的线程有关，因为 join() 将采用 `result` 并将其设置为 None，这样这里就没有任何东西可以丢弃了。
        //
        // 如果出现这种情况，我们应该处理它，因为我们在线程的最外层 `catch_unwind` 之外。
        // 在那种情况下，我们只是中止，因为我们无能为力。
        // (即使我们试图以某种方式处理它，我们也需要处理我们从中得到的 panic 有效，载荷，在丢弃时也会 panic 的情况，依此类推。
        // 请参见问题 #86027。)
        //
        //
        //
        if let Err(_) = panic::catch_unwind(panic::AssertUnwindSafe(|| {
            *self.result.get_mut() = None;
        })) {
            rtabort!("thread result panicked on drop");
        }
        // 簿记，以便作用域知道何时完成。
        if let Some(scope) = &self.scope {
            // 现在将不再有用户代码在此线程上运行可以使用 'scope，将线程标记为 'finished'。
            // 重要的是我们只在 `result` 被丢弃之后才这样做，因为丢弃它可能仍然使用从 'scope 借来的东西
            //
            //
            scope.decrement_num_running_threads(unhandled_panic);
        }
    }
}

/// JoinHandle 的内部表示
struct JoinInner<'scope, T> {
    native: imp::Thread,
    thread: Thread,
    packet: Arc<Packet<'scope, T>>,
}

impl<'scope, T> JoinInner<'scope, T> {
    fn join(mut self) -> Result<T> {
        self.native.join();
        Arc::get_mut(&mut self.packet).unwrap().result.get_mut().take().unwrap()
    }
}

/// 拥有加入线程的权限 (在线程终止时阻止)。
///
/// 当 `JoinHandle` 被丢弃时，它会*分离*关联的线程，这意味着不再有线程的任何句柄，也无法在其上使用 `join`。
///
///
/// 由于平台的限制，无法使用 [`Clone`] 此句柄：加入线程的能力是唯一拥有的权限。
///
/// 该 `struct` 由 [`thread::spawn`] 函数和 [`thread::Builder::spawn`] 方法创建。
///
/// # Examples
///
/// 从 [`thread::spawn`] 创建：
///
/// ```
/// use std::thread;
///
/// let join_handle: thread::JoinHandle<_> = thread::spawn(|| {
///     // 这里一些工作
/// });
/// ```
///
/// 从 [`thread::Builder::spawn`] 创建：
///
/// ```
/// use std::thread;
///
/// let builder = thread::Builder::new();
///
/// let join_handle: thread::JoinHandle<_> = builder.spawn(|| {
///     // 这里一些工作
/// }).unwrap();
/// ```
///
/// 一个线程被分离并且比产生它的线程生命周期更长：
///
/// ```no_run
/// use std::thread;
/// use std::time::Duration;
///
/// let original_thread = thread::spawn(|| {
///     let _detached_thread = thread::spawn(|| {
///         // 在这里我们睡觉以确保第一个线程在此之前返回。
///         thread::sleep(Duration::from_millis(10));
///         // 即使 JoinHandle 被丢弃，也将调用它。
///         println!("♫ Still alive ♫");
///     });
/// });
///
/// original_thread.join().expect("The thread being joined has panicked");
/// println!("Original thread is joined.");
///
/// // 我们确保在主线程返回之前，新线程有时间运行。
/////
///
/// thread::sleep(Duration::from_millis(1000));
/// ```
///
/// [`thread::Builder::spawn`]: Builder::spawn
/// [`thread::spawn`]: spawn
///
///
///
#[stable(feature = "rust1", since = "1.0.0")]
pub struct JoinHandle<T>(JoinInner<'static, T>);

#[stable(feature = "joinhandle_impl_send_sync", since = "1.29.0")]
unsafe impl<T> Send for JoinHandle<T> {}
#[stable(feature = "joinhandle_impl_send_sync", since = "1.29.0")]
unsafe impl<T> Sync for JoinHandle<T> {}

impl<T> JoinHandle<T> {
    /// 提取底层线程的句柄。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::thread;
    ///
    /// let builder = thread::Builder::new();
    ///
    /// let join_handle: thread::JoinHandle<_> = builder.spawn(|| {
    ///     // 这里一些工作
    /// }).unwrap();
    ///
    /// let thread = join_handle.thread();
    /// println!("thread id: {:?}", thread.id());
    /// ```
    #[stable(feature = "rust1", since = "1.0.0")]
    #[must_use]
    pub fn thread(&self) -> &Thread {
        &self.0.thread
    }

    /// 等待关联的线程完成。
    ///
    /// 如果关联的线程已经完成，这个函数将立即返回。
    ///
    /// 就 [原子内存排序][atomic memory orderings] 而言，关联线程的完成与此函数返回同步。
    /// 换句话说，该线程 [之前发生过](https://doc.rust-lang.org/nomicon/atomics.html#data-accesses) 执行的所有操作都是在 `join` 返回之后发生的所有操作。
    ///
    ///
    /// 如果关联的线程 panics，则返回 [`Err`]，并返回给 [`panic!`] 的参数。
    ///
    /// [`Err`]: crate::result::Result::Err
    /// [atomic memory orderings]: crate::sync::atomic
    ///
    /// # Panics
    ///
    /// 如果某个线程尝试加入自身，则该函数在某些平台上可能为 panic，否则可能会在加入线程时产生死锁。
    ///
    /// # Examples
    ///
    /// ```
    /// use std::thread;
    ///
    /// let builder = thread::Builder::new();
    ///
    /// let join_handle: thread::JoinHandle<_> = builder.spawn(|| {
    ///     // 这里一些工作
    /// }).unwrap();
    /// join_handle.join().expect("Couldn't join on the associated thread");
    /// ```
    ///
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn join(self) -> Result<T> {
        self.0.join()
    }

    /// 检查关联线程是否已完成其 main 函数的运行。
    ///
    /// `is_finished` 支持实现非阻塞连接操作，通过检查 `is_finished`，如果返回 `true` 则调用 `join`。
    /// 该函数不会阻止。
    /// 要在等待线程完成时阻塞，请使用 [`join`][Self::join]。
    ///
    /// 这可能在线程的 main 函数返回之后，但在线程本身停止运行之前短暂返回 `true`。
    /// 但是，一旦返回 `true`，可以预期 [`join`][Self::join] 会快速返回，而不会被阻塞很长时间。
    ///
    ///
    #[stable(feature = "thread_is_running", since = "1.61.0")]
    pub fn is_finished(&self) -> bool {
        Arc::strong_count(&self.0.packet) == 1
    }
}

impl<T> AsInner<imp::Thread> for JoinHandle<T> {
    fn as_inner(&self) -> &imp::Thread {
        &self.0.native
    }
}

impl<T> IntoInner<imp::Thread> for JoinHandle<T> {
    fn into_inner(self) -> imp::Thread {
        self.0.native
    }
}

#[stable(feature = "std_debug", since = "1.16.0")]
impl<T> fmt::Debug for JoinHandle<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("JoinHandle").finish_non_exhaustive()
    }
}

fn _assert_sync_and_send() {
    fn _assert_both<T: Send + Sync>() {}
    _assert_both::<JoinHandle<()>>();
    _assert_both::<Thread>();
}

/// 返回程序应该使用的默认并行量的估计值。
///
/// 并行性是一种资源。给定的机器提供一定的并行能力，即它可以同时执行的计算数量的界限。这个数字通常与计算机拥有的 CPU 数量相对应，但在不同情况下可能会有所不同。
///
/// 虚拟机或容器编排器等主机环境可能希望限制其中的程序可用的并行量。
/// 这样做通常是为了限制 (非故意地) 资源密集型程序对同一台机器上运行的其他程序的潜在影响。
///
/// # Limitations
///
/// 此 API 的目的是提供一种简单且可移植的方式来查询程序应使用的默认并行量。
/// 除其他事项外，它不公开有关 NUMA 区域的信息，不考虑 (协同) 处理器功能或当前系统负载的差异，并且不会为了更准确地查询可用并行度的数量而修改程序的整体状态。
///
///
/// 在固定稳态和突发限制都可用的情况下，稳态容量将用于确保更可预测的延迟。
///
/// 资源限制可以在程序运行时更改，因此该值不会被缓存，而是在每次调用此函数时重新计算。不应从热代码中调用它。
///
/// 这个函数返回的值应该被认为是任何给定时间可用的实际并行量的简化近似值。
/// 要更详细或更准确地了解程序可用的并行量，您可能还希望使用特定于平台的 API。
/// 以下平台限制目前适用于 `available_parallelism`：
///
/// 在 Windows 上：
/// - 它可能会低估具有超过 64 个逻辑 CPU 的系统上可用的并行量。
/// 但是，程序通常需要特定的支持才能利用超过 64 个逻辑 CPU，而在没有这种支持的情况下，此函数返回的数字准确地反映了程序默认可以使用的逻辑 CPU 的数量。
/// - 它可能会过度计算系统上可用的并行量，这些并行量受到进程范围的相似性屏蔽或作业对象限制的限制。
///
/// 在 Linux 上：
/// - 当受进程范围的关联掩码或 cgroup 配额限制并且无法查询 `sched_getaffinity()` 或 cgroup fs (例如由于沙盒) 时，它可能会高估可用的并行量。
/// - 如果当前线程的关联掩码没有反映进程的 cpuset，例如由于固定线程，它可能会低估并行的数量。
/// - 如果进程在 cgroup v1 cpu 控制器中，则可能需要扫描挂载点以找到对应的 cgroup v1 控制器，这在具有大量挂载点的系统上可能需要一些时间。
///   (这不适用于 cgroup v2 或不在 cgroup 中的进程。)
///
/// 在所有目标上：
/// - 当在具有 CPU 使用限制的 VM 中运行时 (例如过载的主机)，它可能会过度计算可用的并行量。
///
/// # Errors
///
/// 在以下情况下，此函数将返回错误，但不限于此：
///
/// - 如果目标平台的并行量未知。
/// - 如果程序没有查询可用的并行量的权限。
///
/// # Examples
///
/// ```
/// # #![allow(dead_code)]
/// use std::{io, thread};
///
/// fn main() -> io::Result<()> {
///     let count = thread::available_parallelism()?.get();
///     assert!(count >= 1_usize);
///     Ok(())
/// }
/// ```
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
#[doc(alias = "available_concurrency")] // 我们为这个 API 提供了不稳定的前一个名称的别名。
#[doc(alias = "hardware_concurrency")] // C++ `std::thread::hardware_concurrency` 的别名。
#[doc(alias = "num_cpus")] // 提供类似功能的流行生态系统 crate 的别名。
#[stable(feature = "available_parallelism", since = "1.59.0")]
pub fn available_parallelism() -> io::Result<NonZeroUsize> {
    imp::available_parallelism()
}