//! 定义 [`Exclusive`]。

use core::fmt;
use core::future::Future;
use core::pin::Pin;
use core::task::{Context, Poll};

/// `Exclusive` 仅提供非法访问，也称为对底层值的独占访问。它不提供对底层值的不公开或共享访问。
///
/// 虽然这看起来不是很有用，但它允许 `Exclusive` 无条件地实现 [`Sync`]。
/// 事实上，`Sync` 的安全要求规定，`Exclusive` 要成为 `Sync`，跨线程共享必须是健全的，即 `&Exclusive` 跨线程边界必须是健全的。
/// 根据设计，`&Exclusive` 没有任何 API，使其无用，因此无害，因此内存安全。
///
/// [`Future`] s 之类的某些结构只能用于独占访问，并且通常是 `Send` 而不是 `Sync`，因此 `Exclusive` 可以用作 rust 编译器的提示，即在实践中某些东西是 `Sync`。
///
///
/// ## Examples
/// 使用非 `Sync` future 防止包装结构体为 `Sync`
///
/// ```compile_fail
/// use core::cell::Cell;
///
/// async fn other() {}
/// fn assert_sync<T: Sync>(t: T) {}
/// struct State<F> {
///     future: F
/// }
///
/// assert_sync(State {
///     future: async {
///         let cell = Cell::new(1);
///         let cell_ref = &cell;
///         other().await;
///         let value = cell_ref.get();
///     }
/// });
/// ```
///
/// `Exclusive` 确保结构体是 `Sync` 而不会剥夺 future 的功能。
///
/// ```
/// #![feature(exclusive_wrapper)]
/// use core::cell::Cell;
/// use core::sync::Exclusive;
///
/// async fn other() {}
/// fn assert_sync<T: Sync>(t: T) {}
/// struct State<F> {
///     future: Exclusive<F>
/// }
///
/// assert_sync(State {
///     future: Exclusive::new(async {
///         let cell = Cell::new(1);
///         let cell_ref = &cell;
///         other().await;
///         let value = cell_ref.get();
///     })
/// });
/// ```
///
/// ## 与互斥锁平行
/// 在某种意义上，`Exclusive` 可以被认为是互斥锁的编译时版本，因为借用检查器保证只有一个 `&mut` 可以存在任何值。
/// 这与 `&` 和 `&mut` 引用一起可以被认为是读写锁的编译时版本的事实是并行的。
///
///
///
///
///
///
///
#[unstable(feature = "exclusive_wrapper", issue = "98407")]
#[doc(alias = "SyncWrapper")]
#[doc(alias = "SyncCell")]
#[doc(alias = "Unique")]
// `Exclusive` 不能有 `PartialOrd`、`Clone` 等。
// impls 因为他们会使用 `&` 访问内部值，违反了 `Sync` impl 的安全要求。
//
#[derive(Default)]
#[repr(transparent)]
pub struct Exclusive<T: ?Sized> {
    inner: T,
}

// 有关理由，请参见 `Exclusive` 的文档。
#[unstable(feature = "exclusive_wrapper", issue = "98407")]
unsafe impl<T: ?Sized> Sync for Exclusive<T> {}

#[unstable(feature = "exclusive_wrapper", issue = "98407")]
impl<T: ?Sized> fmt::Debug for Exclusive<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
        f.debug_struct("Exclusive").finish_non_exhaustive()
    }
}

impl<T: Sized> Exclusive<T> {
    /// 在 `Exclusive` 中包装一个值
    #[unstable(feature = "exclusive_wrapper", issue = "98407")]
    #[must_use]
    #[inline]
    pub const fn new(t: T) -> Self {
        Self { inner: t }
    }

    /// 展开 `Exclusive` 中包含的值
    #[unstable(feature = "exclusive_wrapper", issue = "98407")]
    #[must_use]
    #[inline]
    pub const fn into_inner(self) -> T {
        self.inner
    }
}

impl<T: ?Sized> Exclusive<T> {
    /// 获得对，底层，值的独占访问权。
    #[unstable(feature = "exclusive_wrapper", issue = "98407")]
    #[must_use]
    #[inline]
    pub const fn get_mut(&mut self) -> &mut T {
        &mut self.inner
    }

    /// 获得对，底层，值的固定独占访问权。
    ///
    /// `Exclusive` 被认为在结构上固定了，底层，值，这意味着未固定的 `Exclusive` 可以产生对，底层，值的未固定访问，但固定的 `Exclusive` 仅产生对，底层，值的固定访问。
    ///
    ///
    ///
    #[unstable(feature = "exclusive_wrapper", issue = "98407")]
    #[must_use]
    #[inline]
    pub const fn get_pin_mut(self: Pin<&mut Self>) -> Pin<&mut T> {
        // SAFETY: `Exclusive` 只有在自身被 unpinned 时才能产生 `&mut T` `Pin::map_unchecked_mut` 不是 const，所以我们手动进行这个转换
        //
        unsafe { Pin::new_unchecked(&mut self.get_unchecked_mut().inner) }
    }

    /// 从可变引用到 `T` 构建可变引用到 `Exclusive<T>`。
    /// 这允许您跳过使用 [`Exclusive::new`] 构建 `Exclusive`。
    ///
    #[unstable(feature = "exclusive_wrapper", issue = "98407")]
    #[must_use]
    #[inline]
    pub const fn from_mut(r: &'_ mut T) -> &'_ mut Exclusive<T> {
        // SAFETY: repr ≥ C，因此 refs 具有相同的布局; 和 `Exclusive` 属性与 `&mut` 无关
        unsafe { &mut *(r as *mut T as *mut Exclusive<T>) }
    }

    /// 从固定可变引用到 `T` 构建固定可变引用到 `Exclusive<T>`。
    /// 这允许您跳过使用 [`Exclusive::new`] 构建 `Exclusive`。
    ///
    #[unstable(feature = "exclusive_wrapper", issue = "98407")]
    #[must_use]
    #[inline]
    pub const fn from_pin_mut(r: Pin<&'_ mut T>) -> Pin<&'_ mut Exclusive<T>> {
        // SAFETY: `Exclusive` 只有在自身被 unpinned 时才能产生 `&mut T` `Pin::map_unchecked_mut` 不是 const，所以我们手动进行这个转换
        //
        unsafe { Pin::new_unchecked(Self::from_mut(r.get_unchecked_mut())) }
    }
}

#[unstable(feature = "exclusive_wrapper", issue = "98407")]
impl<T> From<T> for Exclusive<T> {
    #[inline]
    fn from(t: T) -> Self {
        Self::new(t)
    }
}

#[unstable(feature = "exclusive_wrapper", issue = "98407")]
impl<T: Future + ?Sized> Future for Exclusive<T> {
    type Output = T::Output;
    #[inline]
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        self.get_pin_mut().poll(cx)
    }
}