//! 惰性值和静态数据的一次性初始化。

#[cfg(test)]
mod tests;

use crate::{
    cell::{Cell, UnsafeCell},
    fmt,
    marker::PhantomData,
    mem::MaybeUninit,
    ops::{Deref, Drop},
    panic::{RefUnwindSafe, UnwindSafe},
    pin::Pin,
    sync::Once,
};

#[doc(inline)]
#[unstable(feature = "once_cell", issue = "74465")]
pub use core::lazy::*;

/// 只能写入一次的同步原语。
///
/// 此类型是线程安全的 `OnceCell`。
///
/// # Examples
///
/// ```
/// #![feature(once_cell)]
///
/// use std::lazy::SyncOnceCell;
///
/// static CELL: SyncOnceCell<String> = SyncOnceCell::new();
/// assert!(CELL.get().is_none());
///
/// std::thread::spawn(|| {
///     let value: &String = CELL.get_or_init(|| {
///         "Hello, World!".to_string()
///     });
///     assert_eq!(value, "Hello, World!");
/// }).join().unwrap();
///
/// let value: Option<&String> = CELL.get();
/// assert!(value.is_some());
/// assert_eq!(value.unwrap().as_str(), "Hello, World!");
/// ```
#[unstable(feature = "once_cell", issue = "74465")]
pub struct SyncOnceCell<T> {
    once: Once,
    // `state_and_queue` 跟踪该值是否已初始化。
    value: UnsafeCell<MaybeUninit<T>>,
    /// `PhantomData` 以确保 dropck 理解我们在 Drop impl 中丢弃了 T。
    ///
    /// ```compile_fail,E0597
    /// #![feature(once_cell)]
    ///
    /// use std::lazy::SyncOnceCell;
    ///
    /// struct A<'a>(&'a str);
    ///
    /// impl<'a> Drop for A<'a> {
    ///     fn drop(&mut self) {}
    /// }
    ///
    /// let cell = SyncOnceCell::new();
    /// {
    ///     let s = String::new();
    ///     let _ = cell.set(A(&s));
    /// }
    /// ```
    _marker: PhantomData<T>,
}

// 为什么我们需要 `T: Send`?
// 线程 A 创建一个 `SyncOnceCell` 并将其与作用域内的线程 B 共享，该线程 B 填充了 cell，然后被 A 销毁。
// 也就是说，析构函数观察发送的值。
//
//
#[unstable(feature = "once_cell", issue = "74465")]
unsafe impl<T: Sync + Send> Sync for SyncOnceCell<T> {}
#[unstable(feature = "once_cell", issue = "74465")]
unsafe impl<T: Send> Send for SyncOnceCell<T> {}

#[unstable(feature = "once_cell", issue = "74465")]
impl<T: RefUnwindSafe + UnwindSafe> RefUnwindSafe for SyncOnceCell<T> {}
#[unstable(feature = "once_cell", issue = "74465")]
impl<T: UnwindSafe> UnwindSafe for SyncOnceCell<T> {}

#[unstable(feature = "once_cell", issue = "74465")]
impl<T> Default for SyncOnceCell<T> {
    fn default() -> SyncOnceCell<T> {
        SyncOnceCell::new()
    }
}

#[unstable(feature = "once_cell", issue = "74465")]
impl<T: fmt::Debug> fmt::Debug for SyncOnceCell<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self.get() {
            Some(v) => f.debug_tuple("Once").field(v).finish(),
            None => f.write_str("Once(Uninit)"),
        }
    }
}

#[unstable(feature = "once_cell", issue = "74465")]
impl<T: Clone> Clone for SyncOnceCell<T> {
    fn clone(&self) -> SyncOnceCell<T> {
        let cell = Self::new();
        if let Some(value) = self.get() {
            match cell.set(value.clone()) {
                Ok(()) => (),
                Err(_) => unreachable!(),
            }
        }
        cell
    }
}

#[unstable(feature = "once_cell", issue = "74465")]
impl<T> From<T> for SyncOnceCell<T> {
    fn from(value: T) -> Self {
        let cell = Self::new();
        match cell.set(value) {
            Ok(()) => cell,
            Err(_) => unreachable!(),
        }
    }
}

#[unstable(feature = "once_cell", issue = "74465")]
impl<T: PartialEq> PartialEq for SyncOnceCell<T> {
    fn eq(&self, other: &SyncOnceCell<T>) -> bool {
        self.get() == other.get()
    }
}

#[unstable(feature = "once_cell", issue = "74465")]
impl<T: Eq> Eq for SyncOnceCell<T> {}

impl<T> SyncOnceCell<T> {
    /// 创建一个新的空 cell。
    #[unstable(feature = "once_cell", issue = "74465")]
    pub const fn new() -> SyncOnceCell<T> {
        SyncOnceCell {
            once: Once::new(),
            value: UnsafeCell::new(MaybeUninit::uninit()),
            _marker: PhantomData,
        }
    }

    /// 获取对基础值的引用。
    ///
    /// 如果 cell 为空或正在初始化，则返回 `None`。
    /// 此方法永远不会阻塞。
    #[unstable(feature = "once_cell", issue = "74465")]
    pub fn get(&self) -> Option<&T> {
        if self.is_initialized() {
            // 安全 b/c 已检查 is_initialized
            Some(unsafe { self.get_unchecked() })
        } else {
            None
        }
    }

    /// 获取基础值的可变引用。
    ///
    /// 如果 cell 为空，则返回 `None`。此方法永远不会阻塞。
    #[unstable(feature = "once_cell", issue = "74465")]
    pub fn get_mut(&mut self) -> Option<&mut T> {
        if self.is_initialized() {
            // 安全 b/c 已检查 is_initialized，我们拥有唯一的访问权
            Some(unsafe { self.get_unchecked_mut() })
        } else {
            None
        }
    }

    /// 将此 cell 的内容设置为 `value`。
    ///
    /// 如果另一个线程当前正在尝试初始化该单元，则可能会阻塞。
    /// 尽管 set 不一定返回，但保证该 cell 包含一个值。
    ///
    /// 如果此调用设置了 cell 的值，则返回 `Ok(())`。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(once_cell)]
    ///
    /// use std::lazy::SyncOnceCell;
    ///
    /// static CELL: SyncOnceCell<i32> = SyncOnceCell::new();
    ///
    /// fn main() {
    ///     assert!(CELL.get().is_none());
    ///
    ///     std::thread::spawn(|| {
    ///         assert_eq!(CELL.set(92), Ok(()));
    ///     }).join().unwrap();
    ///
    ///     assert_eq!(CELL.set(62), Err(62));
    ///     assert_eq!(CELL.get(), Some(&92));
    /// }
    /// ```
    #[unstable(feature = "once_cell", issue = "74465")]
    pub fn set(&self, value: T) -> Result<(), T> {
        let mut value = Some(value);
        self.get_or_init(|| value.take().unwrap());
        match value {
            None => Ok(()),
            Some(value) => Err(value),
        }
    }

    /// 获取 cell 的内容，如果 cell 为空，则使用 `f` 对其进行初始化。
    ///
    /// 许多线程可以使用不同的初始化函数并发调用 `get_or_init`，但是可以保证仅执行一个函数。
    ///
    ///
    /// # Panics
    ///
    /// 如果 `f` panics，则 panic 会传播给调用者，并且单元仍保持未初始化状态。
    ///
    /// 重新从 `f` 初始化 cell 是错误的。确切的结果是不确定的。
    /// 当前的实现死锁，但是可以在 future 中将其更改为 panic。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(once_cell)]
    ///
    /// use std::lazy::SyncOnceCell;
    ///
    /// let cell = SyncOnceCell::new();
    /// let value = cell.get_or_init(|| 92);
    /// assert_eq!(value, &92);
    /// let value = cell.get_or_init(|| unreachable!());
    /// assert_eq!(value, &92);
    /// ```
    ///
    ///
    ///
    ///
    #[unstable(feature = "once_cell", issue = "74465")]
    pub fn get_or_init<F>(&self, f: F) -> &T
    where
        F: FnOnce() -> T,
    {
        match self.get_or_try_init(|| Ok::<T, !>(f())) {
            Ok(val) => val,
        }
    }

    /// 获取 cell 的内容，如果 cell 为空，则使用 `f` 对其进行初始化。
    /// 如果单元为空并且 `f` 失败，则返回错误。
    ///
    /// # Panics
    ///
    /// 如果 `f` panics，则 panic 会传播给调用者，并且单元仍保持未初始化状态。
    ///
    ///
    /// 重新从 `f` 初始化 cell 是错误的。
    /// 确切的结果是不确定的。
    /// 当前的实现死锁，但是可以在 future 中将其更改为 panic。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(once_cell)]
    ///
    /// use std::lazy::SyncOnceCell;
    ///
    /// let cell = SyncOnceCell::new();
    /// assert_eq!(cell.get_or_try_init(|| Err(())), Err(()));
    /// assert!(cell.get().is_none());
    /// let value = cell.get_or_try_init(|| -> Result<i32, ()> {
    ///     Ok(92)
    /// });
    /// assert_eq!(value, Ok(&92));
    /// assert_eq!(cell.get(), Some(&92))
    /// ```
    ///
    #[unstable(feature = "once_cell", issue = "74465")]
    pub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E>
    where
        F: FnOnce() -> Result<T, E>,
    {
        // 快速路径检查
        // NOTE: 为了正确同步 `SyncLazy::force`，我们需要使用此方法对状态执行获取。
        // 当前，这是通过调用 `self.get()` (依次调用 `self.is_initialized()`) 来完成的，而 `self.is_initialized()` 依次执行获取。
        //
        //
        if let Some(value) = self.get() {
            return Ok(value);
        }
        self.initialize(f)?;

        debug_assert!(self.is_initialized());

        // SAFETY: 内部值已初始化
        Ok(unsafe { self.get_unchecked() })
    }

    /// 仅限内部的 API，用于获取 cell 的内容，如果 cell 为空，则使用 `f` 和 `g` 分两步对其进行初始化。
    ///
    /// `f` 调用构造该值，然后将其移到 cell 中并作为 (pinned) 的变量引用给 `g` 以完成初始化。
    ///
    /// 这使 `g` 在将值移到 cell 中的最终位置之后但在将其视为初始化之前，可以检查该值。
    ///
    ///
    /// # Panics
    ///
    /// 如果为 `f` 或 `g` panics，则 panic 会传播到调用方，并且单元仍保持未初始化状态。
    ///
    /// 在当前实现中，如果 `g` panics，则不会丢弃 `f` 中的值。
    /// 如果此类型曾用于此类型，则可能应该修复此问题。
    ///
    /// 重新从 `f` 初始化 cell 是错误的。确切的结果是不确定的。
    /// 当前的实现死锁，但是可以在 future 中将其更改为 panic。
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    pub(crate) fn get_or_init_pin<F, G>(self: Pin<&Self>, f: F, g: G) -> Pin<&T>
    where
        F: FnOnce() -> T,
        G: FnOnce(Pin<&mut T>),
    {
        if let Some(value) = self.get_ref().get() {
            // SAFETY: 内部值已被初始化，将不再移动。
            //
            return unsafe { Pin::new_unchecked(value) };
        }

        let slot = &self.value;

        // 忽略其他线程的中毒如果另一个线程 panics，那么我们将能够运行我们的闭包
        //
        self.once.call_once_force(|_| {
            let value = f();
            // SAFETY: 我们使用一次 (self.once) 来保证对 UnsafeCell (slot) 的唯一访问。
            //
            let value: &mut T = unsafe { (&mut *slot.get()).write(value) };
            // SAFETY: 该值已被写入 self.value 的最终位置。
            // 我们不再移动它，我们在这里用 Pin<&mut T> 将其 promise 移动。
            //
            g(unsafe { Pin::new_unchecked(value) });
        });

        // SAFETY: 内部值已初始化，将不再移动。
        //
        unsafe { Pin::new_unchecked(self.get_ref().get_unchecked()) }
    }

    /// 消耗 `SyncOnceCell`，返回包装的值。
    /// 如果 cell 为空，则返回 `None`。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(once_cell)]
    ///
    /// use std::lazy::SyncOnceCell;
    ///
    /// let cell: SyncOnceCell<String> = SyncOnceCell::new();
    /// assert_eq!(cell.into_inner(), None);
    ///
    /// let cell = SyncOnceCell::new();
    /// cell.set("hello".to_string()).unwrap();
    /// assert_eq!(cell.into_inner(), Some("hello".to_string()));
    /// ```
    #[unstable(feature = "once_cell", issue = "74465")]
    pub fn into_inner(mut self) -> Option<T> {
        self.take()
    }

    /// 从 `SyncOnceCell` 中取出值，将其移回未初始化状态。
    ///
    /// 无效，如果尚未初始化 `SyncOnceCell`，则返回 `None`。
    ///
    /// 通过要求可变引用来保证安全。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(once_cell)]
    ///
    /// use std::lazy::SyncOnceCell;
    ///
    /// let mut cell: SyncOnceCell<String> = SyncOnceCell::new();
    /// assert_eq!(cell.take(), None);
    ///
    /// let mut cell = SyncOnceCell::new();
    /// cell.set("hello".to_string()).unwrap();
    /// assert_eq!(cell.take(), Some("hello".to_string()));
    /// assert_eq!(cell.get(), None);
    /// ```
    #[unstable(feature = "once_cell", issue = "74465")]
    pub fn take(&mut self) -> Option<T> {
        if self.is_initialized() {
            self.once = Once::new();
            // SAFETY: `self.value` 已初始化，并包含有效的 `T`。
            // `self.once` 复位后，`is_initialized()` 将再次为假，这将阻止该值被读取两次。
            //
            unsafe { Some((&mut *self.value.get()).assume_init_read()) }
        } else {
            None
        }
    }

    #[inline]
    fn is_initialized(&self) -> bool {
        self.once.is_completed()
    }

    #[cold]
    fn initialize<F, E>(&self, f: F) -> Result<(), E>
    where
        F: FnOnce() -> Result<T, E>,
    {
        let mut res: Result<(), E> = Ok(());
        let slot = &self.value;

        // 忽略其他线程的中毒如果另一个线程 panics，那么我们将能够运行我们的闭包
        //
        self.once.call_once_force(|p| {
            match f() {
                Ok(value) => {
                    unsafe { (&mut *slot.get()).write(value) };
                }
                Err(e) => {
                    res = Err(e);

                    // 由于无法初始化值，因此将基础 `Once` 视为中毒。
                    // Calls
                    p.poison();
                }
            }
        });
        res
    }

    /// # Safety
    ///
    /// 该值必须初始化
    unsafe fn get_unchecked(&self) -> &T {
        debug_assert!(self.is_initialized());
        (&*self.value.get()).assume_init_ref()
    }

    /// # Safety
    ///
    /// 该值必须初始化
    unsafe fn get_unchecked_mut(&mut self) -> &mut T {
        debug_assert!(self.is_initialized());
        (&mut *self.value.get()).assume_init_mut()
    }
}

unsafe impl<#[may_dangle] T> Drop for SyncOnceCell<T> {
    fn drop(&mut self) {
        if self.is_initialized() {
            // SAFETY: cell 已初始化并已丢弃，因此无法再次访问。
            // 除了 drop 它之外，我们也不会触及 `T`，它可以验证我们对 #[may_dangle] 的用法。
            //
            unsafe { (&mut *self.value.get()).assume_init_drop() };
        }
    }
}

/// 在首次访问时初始化的值。
///
/// 此类型是线程安全的 `Lazy`，可以在静态中使用。
///
/// # Examples
///
/// ```
/// #![feature(once_cell)]
///
/// use std::collections::HashMap;
///
/// use std::lazy::SyncLazy;
///
/// static HASHMAP: SyncLazy<HashMap<i32, String>> = SyncLazy::new(|| {
///     println!("initializing");
///     let mut m = HashMap::new();
///     m.insert(13, "Spica".to_string());
///     m.insert(74, "Hoyten".to_string());
///     m
/// });
///
/// fn main() {
///     println!("ready");
///     std::thread::spawn(|| {
///         println!("{:?}", HASHMAP.get(&13));
///     }).join().unwrap();
///     println!("{:?}", HASHMAP.get(&74));
///
///     // Prints:
///     //   准备初始化
/////
///     //   Some("Spica")
///     //   Some("Hoyten")
/// }
/// ```
#[unstable(feature = "once_cell", issue = "74465")]
pub struct SyncLazy<T, F = fn() -> T> {
    cell: SyncOnceCell<T>,
    init: Cell<Option<F>>,
}

#[unstable(feature = "once_cell", issue = "74465")]
impl<T: fmt::Debug, F> fmt::Debug for SyncLazy<T, F> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Lazy").field("cell", &self.cell).finish_non_exhaustive()
    }
}

// 我们从不从 `&SyncLazy<T, F>` 创建 `&F`，所以最好不要为 `F` 暗示 `Sync`，我们确实在 `force` 中创建了 `&mut Option<F>`，但这已正确同步，因此它只发生一次，因此也没有助长这一暗示。
//
//
//
//
#[unstable(feature = "once_cell", issue = "74465")]
unsafe impl<T, F: Send> Sync for SyncLazy<T, F> where SyncOnceCell<T>: Sync {}
// 自动派生的 `Send` impl 是可以的。

#[unstable(feature = "once_cell", issue = "74465")]
impl<T, F: UnwindSafe> RefUnwindSafe for SyncLazy<T, F> where SyncOnceCell<T>: RefUnwindSafe {}
#[unstable(feature = "once_cell", issue = "74465")]
impl<T, F: UnwindSafe> UnwindSafe for SyncLazy<T, F> where SyncOnceCell<T>: UnwindSafe {}

impl<T, F> SyncLazy<T, F> {
    /// 使用给定的初始化函数创建一个新的惰性值。
    ///
    #[unstable(feature = "once_cell", issue = "74465")]
    pub const fn new(f: F) -> SyncLazy<T, F> {
        SyncLazy { cell: SyncOnceCell::new(), init: Cell::new(Some(f)) }
    }
}

impl<T, F: FnOnce() -> T> SyncLazy<T, F> {
    /// 强制评估此惰性值，并返回引数以得出结果。
    /// 这等效于 `Deref` impl，但是是显式的。
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(once_cell)]
    ///
    /// use std::lazy::SyncLazy;
    ///
    /// let lazy = SyncLazy::new(|| 92);
    ///
    /// assert_eq!(SyncLazy::force(&lazy), &92);
    /// assert_eq!(&*lazy, &92);
    /// ```
    ///
    #[unstable(feature = "once_cell", issue = "74465")]
    pub fn force(this: &SyncLazy<T, F>) -> &T {
        this.cell.get_or_init(|| match this.init.take() {
            Some(f) => f(),
            None => panic!("Lazy instance has previously been poisoned"),
        })
    }
}

#[unstable(feature = "once_cell", issue = "74465")]
impl<T, F: FnOnce() -> T> Deref for SyncLazy<T, F> {
    type Target = T;
    fn deref(&self) -> &T {
        SyncLazy::force(self)
    }
}

#[unstable(feature = "once_cell", issue = "74465")]
impl<T: Default> Default for SyncLazy<T> {
    /// 使用 `Default` 作为初始化函数创建一个新的惰性值。
    fn default() -> SyncLazy<T> {
        SyncLazy::new(T::default)
    }
}