//! 线程本地存储

#![unstable(feature = "thread_local_internals", issue = "none")]

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

#[cfg(test)]
mod dynamic_tests;

use crate::cell::{Cell, RefCell};
use crate::error::Error;
use crate::fmt;

/// 拥有其内容的线程本地存储密钥。
///
/// 该密钥使用可用于目标平台的最快速度的实现。它用 [`thread_local!`] 宏实例化，主要方法是 [`with`] 方法。
///
/// [`with`] 方法对包含的值产生一个引用，该值不能比当前线程长寿或转义给定的封闭包。
///
/// [`thread_local!`]: crate::thread_local
///
/// # 初始化与销毁
///
/// 初始化是在线程中对 [`with`] 的第一次调用中动态执行的，并且当线程退出时，实现 [`Drop`] 的值将被销毁。一些注意事项适用，下面将进行说明。
///
/// LocalKey 的初始化不能递归地依赖于它自己，以这种方式使用 `LocalKey` 会使初始化在第一次调用 `with` 时无限递归。
///
/// # Examples
///
/// ```
/// use std::cell::RefCell;
/// use std::thread;
///
/// thread_local!(static FOO: RefCell<u32> = RefCell::new(1));
///
/// FOO.with(|f| {
///     assert_eq!(*f.borrow(), 1);
///     *f.borrow_mut() = 2;
/// });
///
/// // 每个线程以 1 的初始值开始
/// let t = thread::spawn(move|| {
///     FOO.with(|f| {
///         assert_eq!(*f.borrow(), 1);
///         *f.borrow_mut() = 3;
///     });
/// });
///
/// // 等待线程完成并在 panic 上退出
/// t.join().unwrap();
///
/// // 尽管有子线程，我们仍保留原始值 2
/// FOO.with(|f| {
///     assert_eq!(*f.borrow(), 2);
/// });
/// ```
///
/// # 特定于平台的行为
///
/// 请注意，我们尽了 "最大努力" 来确保运行线程本地存储中存储的类型的析构函数，但并非所有平台都能保证运行线程本地存储中所有类型的析构函数。
///
/// 例如，有许多已知的警告未运行析构函数：
///
/// 1. 在 Unix 系统上，当使用基于 pthread 的 TLS 时，主线程退出时，不会为主线程上的 TLS 值运行析构函数。
/// 请注意，应用程序也将在主线程退出后立即退出。
/// 2. 在所有平台上，TLS 都有可能在销毁期间重新初始化其他 TLS 插槽。
/// 某些平台通过防止重新初始化已销毁的任何插槽来确保不会无限发生这种情况，但并非所有平台都具有此保护措施。
/// 那些不受约束的平台通常具有综合限制，在此之后，将不再运行析构函数。
/// 3. 当进程在 Windows 系统上退出时，TLS 析构函数可能只在导致进程退出的线程上运行。这是因为其他线程可能会被强制终止。
///
/// ## 线程本地析构函数中的同步
///
/// 在 Windows 上，线程本地析构函数中的同步操作 (例如 [`JoinHandle::join`]) 容易出现死锁，因此应该避免。
/// 这是因为 [loader lock] 在运行析构函数时，仍被持有。每当线程启动、退出、加载或卸载 DLL 时，都会获取锁。
/// 所以，只要线程本地析构函数正在运行，这些事件就会被阻止。
///
/// [loader lock]: https://docs.microsoft.com/en-us/windows/win32/dlls/dynamic-link-library-best-practices
/// [`JoinHandle::join`]: crate::thread::JoinHandle::join
/// [`with`]: LocalKey::with
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
///
#[cfg_attr(not(test), rustc_diagnostic_item = "LocalKey")]
#[stable(feature = "rust1", since = "1.0.0")]
pub struct LocalKey<T: 'static> {
    // 这种外部 `LocalKey<T>` 类型将存储在静态变量中，但是内部的实际数据有时会用 #[thread_local] 标记。
    // 引用 #[thread_local] 静态变量对真实的静态变量是无效的，因此我们通过在函数间接层 (此重击) 中公开一个访问器来解决此问题。
    //
    // 请注意，该重击本身是不安全的，因为返回的数据所在的插槽 `'static` 的生命周期实际上是无效的。
    // 此处的生命周期实际上比当前正在运行的线程短一些！
    //
    // 尽管这是一个间接的额外层，但是从理论上讲，LLVM 应该可以对其进行虚拟化，因为 `inner` 的值永远不会更改，并且常量在 crate 内应为只读。
    //
    // 仅当在 crates 上导出 TLS 静态信息时，这才主要遇到问题。
    //
    //
    //
    //
    //
    inner: unsafe fn(Option<&mut Option<T>>) -> Option<&'static T>,
}

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

/// 声明一个新的 [`std::thread::LocalKey`] 类型的线程本地存储密钥。
///
/// # Syntax
///
/// 宏可以包装任意数量的静态声明，并使它们成为局部线程。
/// 允许每个静态的公开和属性。Example:
///
/// ```
/// use std::cell::RefCell;
/// thread_local! {
///     pub static FOO: RefCell<u32> = RefCell::new(1);
///
///     static BAR: RefCell<f32> = RefCell::new(1.0);
/// }
///
/// FOO.with(|foo| assert_eq!(*foo.borrow(), 1));
/// BAR.with(|bar| assert_eq!(*bar.borrow(), 1.0));
/// ```
///
/// 此宏支持特殊的 `const {}` 语法，当初始化表达式可以被评估为常量时可以使用该语法。
/// 这可以启用可以避免延迟初始化的更高效的线程本地实现。
/// 对于不是 [need to be dropped][crate::mem::needs_drop] 的类型，这可以实现更高效的实现，无需跟踪任何其他状态。
///
///
/// ```
/// use std::cell::Cell;
/// thread_local! {
///     pub static FOO: Cell<u32> = const { Cell::new(1) };
/// }
///
/// FOO.with(|foo| assert_eq!(foo.get(), 1));
/// ```
///
/// 有关更多信息，请参见 [`LocalKey` 文档][`std::thread::LocalKey`]。
///
/// [`std::thread::LocalKey`]: crate::thread::LocalKey
///
///
///
///
#[macro_export]
#[stable(feature = "rust1", since = "1.0.0")]
#[cfg_attr(not(test), rustc_diagnostic_item = "thread_local_macro")]
#[allow_internal_unstable(thread_local_internals)]
macro_rules! thread_local {
    // 空 (递归的基本情况)
    () => {};

    ($(#[$attr:meta])* $vis:vis static $name:ident: $t:ty = const { $init:expr }; $($rest:tt)*) => (
        $crate::thread::local_impl::thread_local_inner!($(#[$attr])* $vis $name, $t, const $init);
        $crate::thread_local!($($rest)*);
    );

    ($(#[$attr:meta])* $vis:vis static $name:ident: $t:ty = const { $init:expr }) => (
        $crate::thread::local_impl::thread_local_inner!($(#[$attr])* $vis $name, $t, const $init);
    );

    // 处理多个声明
    ($(#[$attr:meta])* $vis:vis static $name:ident: $t:ty = $init:expr; $($rest:tt)*) => (
        $crate::thread::local_impl::thread_local_inner!($(#[$attr])* $vis $name, $t, $init);
        $crate::thread_local!($($rest)*);
    );

    // 处理一个声明
    ($(#[$attr:meta])* $vis:vis static $name:ident: $t:ty = $init:expr) => (
        $crate::thread::local_impl::thread_local_inner!($(#[$attr])* $vis $name, $t, $init);
    );
}

/// [`LocalKey::try_with`](struct.LocalKey.html#method.try_with) 返回的错误。
#[stable(feature = "thread_local_try_with", since = "1.26.0")]
#[non_exhaustive]
#[derive(Clone, Copy, Eq, PartialEq)]
pub struct AccessError;

#[stable(feature = "thread_local_try_with", since = "1.26.0")]
impl fmt::Debug for AccessError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("AccessError").finish()
    }
}

#[stable(feature = "thread_local_try_with", since = "1.26.0")]
impl fmt::Display for AccessError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt("already destroyed", f)
    }
}

#[stable(feature = "thread_local_try_with", since = "1.26.0")]
impl Error for AccessError {}

impl<T: 'static> LocalKey<T> {
    #[doc(hidden)]
    #[unstable(
        feature = "thread_local_internals",
        reason = "recently added to create a key",
        issue = "none"
    )]
    #[rustc_const_unstable(feature = "thread_local_internals", issue = "none")]
    pub const unsafe fn new(
        inner: unsafe fn(Option<&mut Option<T>>) -> Option<&'static T>,
    ) -> LocalKey<T> {
        LocalKey { inner }
    }

    /// 获取对此 TLS 密钥中的值的引用。
    ///
    /// 如果此线程尚未引用此键，则将延迟地初始化该值。
    ///
    /// # Panics
    ///
    /// 如果该键当前正在运行其析构函数，则此函数将为 `panic!()`; 如果先前已为此线程运行了析构函数，则它可能 panic。
    ///
    ///
    ///
    #[stable(feature = "rust1", since = "1.0.0")]
    pub fn with<F, R>(&'static self, f: F) -> R
    where
        F: FnOnce(&T) -> R,
    {
        self.try_with(f).expect(
            "cannot access a Thread Local Storage value \
             during or after destruction",
        )
    }

    /// 获取对此 TLS 密钥中的值的引用。
    ///
    /// 如果此线程尚未引用此键，则将延迟地初始化该值。
    /// 如果密钥已被销毁 (如果在析构函数中调用它可能会发生这种情况)，此函数将返回 [`AccessError`]。
    ///
    ///
    /// # Panics
    ///
    /// 如果未初始化密钥并且密钥的初始化 panics，则此函数仍将 `panic!()`。
    ///
    #[stable(feature = "thread_local_try_with", since = "1.26.0")]
    #[inline]
    pub fn try_with<F, R>(&'static self, f: F) -> Result<R, AccessError>
    where
        F: FnOnce(&T) -> R,
    {
        unsafe {
            let thread_local = (self.inner)(None).ok_or(AccessError)?;
            Ok(f(thread_local))
        }
    }

    /// 获取对此 TLS 密钥中的值的引用，如果尚未在此线程上初始化，则使用 `init` 对其进行初始化。
    ///
    /// 如果 `init` 用于初始化线程局部变量，则 `None` 作为第一个参数传递给 `f`。
    /// 如果它已经被初始化，`Some(init)` 被传递给 `f`。
    ///
    /// # Panics
    ///
    /// 如果键当前正在运行其析构函数，则此函数将 panic，如果析构函数先前已为此线程运行，则它**可能**panic。
    ///
    ///
    ///
    ///
    fn initialize_with<F, R>(&'static self, init: T, f: F) -> R
    where
        F: FnOnce(Option<T>, &T) -> R,
    {
        unsafe {
            let mut init = Some(init);
            let reference = (self.inner)(Some(&mut init)).expect(
                "cannot access a Thread Local Storage value \
                 during or after destruction",
            );
            f(init, reference)
        }
    }
}

impl<T: 'static> LocalKey<Cell<T>> {
    /// 设置或初始化包含的值。
    ///
    /// 与其他方法不同，这将*不会*运行本地线程的惰性初始化。
    /// 相反，如果它还没有初始化，它将直接用给定的值初始化。
    ///
    /// # Panics
    ///
    /// 如果密钥当前正在运行其析构函数，则发生 panic，如果析构函数先前已为此线程运行，则它**可能**panic。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(local_key_cell_methods)]
    /// use std::cell::Cell;
    ///
    /// thread_local! {
    ///     static X: Cell<i32> = panic!("!");
    /// }
    ///
    /// // 在这里调用 X.get() 会导致 panic。
    ///
    /// X.set(123); // 但是 X.set() 很好，因为它跳过了上面的初始化。
    ///
    /// assert_eq!(X.get(), 123);
    /// ```
    ///
    #[unstable(feature = "local_key_cell_methods", issue = "92122")]
    pub fn set(&'static self, value: T) {
        self.initialize_with(Cell::new(value), |value, cell| {
            if let Some(value) = value {
                // cell 已经初始化，所以没有使用 `value` 来初始化它。
                // 所以我们用新的值覆盖当前值。
                //
                cell.set(value.into_inner());
            }
        });
    }

    /// 返回所包含值的副本。
    ///
    /// 如果此线程尚未引用此键，则将延迟地初始化该值。
    ///
    /// # Panics
    ///
    /// 如果密钥当前正在运行其析构函数，则发生 panic，如果析构函数先前已为此线程运行，则它**可能**panic。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(local_key_cell_methods)]
    /// use std::cell::Cell;
    ///
    /// thread_local! {
    ///     static X: Cell<i32> = Cell::new(1);
    /// }
    ///
    /// assert_eq!(X.get(), 1);
    /// ```
    ///
    #[unstable(feature = "local_key_cell_methods", issue = "92122")]
    pub fn get(&'static self) -> T
    where
        T: Copy,
    {
        self.with(|cell| cell.get())
    }

    /// 获取包含的值，在其位置保留 `Default::default()`。
    ///
    /// 如果此线程尚未引用此键，则将延迟地初始化该值。
    ///
    /// # Panics
    ///
    /// 如果密钥当前正在运行其析构函数，则发生 panic，如果析构函数先前已为此线程运行，则它**可能**panic。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(local_key_cell_methods)]
    /// use std::cell::Cell;
    ///
    /// thread_local! {
    ///     static X: Cell<Option<i32>> = Cell::new(Some(1));
    /// }
    ///
    /// assert_eq!(X.take(), Some(1));
    /// assert_eq!(X.take(), None);
    /// ```
    ///
    #[unstable(feature = "local_key_cell_methods", issue = "92122")]
    pub fn take(&'static self) -> T
    where
        T: Default,
    {
        self.with(|cell| cell.take())
    }

    /// 替换包含的值，返回旧值。
    ///
    /// 如果此线程尚未引用此键，则将延迟地初始化该值。
    ///
    /// # Panics
    ///
    /// 如果密钥当前正在运行其析构函数，则发生 panic，如果析构函数先前已为此线程运行，则它**可能**panic。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(local_key_cell_methods)]
    /// use std::cell::Cell;
    ///
    /// thread_local! {
    ///     static X: Cell<i32> = Cell::new(1);
    /// }
    ///
    /// assert_eq!(X.replace(2), 1);
    /// assert_eq!(X.replace(3), 2);
    /// ```
    ///
    #[unstable(feature = "local_key_cell_methods", issue = "92122")]
    pub fn replace(&'static self, value: T) -> T {
        self.with(|cell| cell.replace(value))
    }
}

impl<T: 'static> LocalKey<RefCell<T>> {
    /// 获取对所包含值的引用。
    ///
    /// 如果此线程尚未引用此键，则将延迟地初始化该值。
    ///
    /// # Panics
    ///
    /// 如果当前价值是可变借来的，就会出现 panic。
    ///
    /// 如果密钥当前正在运行其析构函数，则发生 panic，如果析构函数先前已为此线程运行，则它**可能**panic。
    ///
    ///
    /// # Example
    ///
    /// ```
    /// #![feature(local_key_cell_methods)]
    /// use std::cell::RefCell;
    ///
    /// thread_local! {
    ///     static X: RefCell<Vec<i32>> = RefCell::new(Vec::new());
    /// }
    ///
    /// X.with_borrow(|v| assert!(v.is_empty()));
    /// ```
    ///
    #[unstable(feature = "local_key_cell_methods", issue = "92122")]
    pub fn with_borrow<F, R>(&'static self, f: F) -> R
    where
        F: FnOnce(&T) -> R,
    {
        self.with(|cell| f(&cell.borrow()))
    }

    /// 获取对所包含值的可变引用。
    ///
    /// 如果此线程尚未引用此键，则将延迟地初始化该值。
    ///
    /// # Panics
    ///
    /// 如果当前的值是借来的，就会出现 panic。
    ///
    /// 如果密钥当前正在运行其析构函数，则发生 panic，如果析构函数先前已为此线程运行，则它**可能**panic。
    ///
    ///
    /// # Example
    ///
    /// ```
    /// #![feature(local_key_cell_methods)]
    /// use std::cell::RefCell;
    ///
    /// thread_local! {
    ///     static X: RefCell<Vec<i32>> = RefCell::new(Vec::new());
    /// }
    ///
    /// X.with_borrow_mut(|v| v.push(1));
    ///
    /// X.with_borrow(|v| assert_eq!(*v, vec![1]));
    /// ```
    ///
    #[unstable(feature = "local_key_cell_methods", issue = "92122")]
    pub fn with_borrow_mut<F, R>(&'static self, f: F) -> R
    where
        F: FnOnce(&mut T) -> R,
    {
        self.with(|cell| f(&mut cell.borrow_mut()))
    }

    /// 设置或初始化包含的值。
    ///
    /// 与其他方法不同，这将*不会*运行本地线程的惰性初始化。
    /// 相反，如果它还没有初始化，它将直接用给定的值初始化。
    ///
    /// # Panics
    ///
    /// 如果当前的值是借来的，就会出现 panic。
    ///
    /// 如果密钥当前正在运行其析构函数，则发生 panic，如果析构函数先前已为此线程运行，则它**可能**panic。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(local_key_cell_methods)]
    /// use std::cell::RefCell;
    ///
    /// thread_local! {
    ///     static X: RefCell<Vec<i32>> = panic!("!");
    /// }
    ///
    /// // 在这里调用 X.with() 会导致 panic。
    ///
    /// X.set(vec![1, 2, 3]); // 但是 X.set() 很好，因为它跳过了上面的初始化。
    ///
    /// X.with_borrow(|v| assert_eq!(*v, vec![1, 2, 3]));
    /// ```
    ///
    #[unstable(feature = "local_key_cell_methods", issue = "92122")]
    pub fn set(&'static self, value: T) {
        self.initialize_with(RefCell::new(value), |value, cell| {
            if let Some(value) = value {
                // cell 已经初始化，所以没有使用 `value` 来初始化它。
                // 所以我们用新的值覆盖当前值。
                //
                *cell.borrow_mut() = value.into_inner();
            }
        });
    }

    /// 获取包含的值，在其位置保留 `Default::default()`。
    ///
    /// 如果此线程尚未引用此键，则将延迟地初始化该值。
    ///
    /// # Panics
    ///
    /// 如果当前的值是借来的，就会出现 panic。
    ///
    /// 如果密钥当前正在运行其析构函数，则发生 panic，如果析构函数先前已为此线程运行，则它**可能**panic。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(local_key_cell_methods)]
    /// use std::cell::RefCell;
    ///
    /// thread_local! {
    ///     static X: RefCell<Vec<i32>> = RefCell::new(Vec::new());
    /// }
    ///
    /// X.with_borrow_mut(|v| v.push(1));
    ///
    /// let a = X.take();
    ///
    /// assert_eq!(a, vec![1]);
    ///
    /// X.with_borrow(|v| assert!(v.is_empty()));
    /// ```
    ///
    #[unstable(feature = "local_key_cell_methods", issue = "92122")]
    pub fn take(&'static self) -> T
    where
        T: Default,
    {
        self.with(|cell| cell.take())
    }

    /// 替换包含的值，返回旧值。
    ///
    /// # Panics
    ///
    /// 如果当前的值是借来的，就会出现 panic。
    ///
    /// 如果密钥当前正在运行其析构函数，则发生 panic，如果析构函数先前已为此线程运行，则它**可能**panic。
    ///
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(local_key_cell_methods)]
    /// use std::cell::RefCell;
    ///
    /// thread_local! {
    ///     static X: RefCell<Vec<i32>> = RefCell::new(Vec::new());
    /// }
    ///
    /// let prev = X.replace(vec![1, 2, 3]);
    /// assert!(prev.is_empty());
    ///
    /// X.with_borrow(|v| assert_eq!(*v, vec![1, 2, 3]));
    /// ```
    #[unstable(feature = "local_key_cell_methods", issue = "92122")]
    pub fn replace(&'static self, value: T) -> T {
        self.with(|cell| cell.replace(value))
    }
}