#![stable(feature = "futures_api", since = "1.36.0")]

use crate::fmt;
use crate::marker::{PhantomData, Unpin};

/// `RawWaker` 允许任务执行器的实现者创建 [`Waker`]，该 [`Waker`] 提供自定义的唤醒行为。
///
/// [vtable]: https://en.wikipedia.org/wiki/Virtual_method_table
///
/// 它由一个数据指针和一个自定义 `RawWaker` 行为的 [虚函数指针表 (vtable)][vtable] 组成。
///
///
#[derive(PartialEq, Debug)]
#[stable(feature = "futures_api", since = "1.36.0")]
pub struct RawWaker {
    /// 数据指针，可用于根据执行程序的要求存储任意数据。
    /// 这可能是例如
    /// 指向与任务关联的 `Arc` 的类型擦除的指针。
    /// 该字段的值作为第一个参数传递给 vtable 一部分的所有函数。
    ///
    data: *const (),
    /// 虚拟函数指针表，可自定义此唤醒程序的行为。
    vtable: &'static RawWakerVTable,
}

impl RawWaker {
    /// 根据提供的 `data` 指针和 `vtable` 创建新的 `RawWaker`。
    ///
    /// `data` 指针可用于存储执行程序所需的任意数据。这可能是例如
    /// 指向与任务关联的 `Arc` 的类型擦除的指针。
    /// 该指针的值将作为第一个参数传递给 `vtable` 一部分的所有函数。
    ///
    /// `vtable` 自定义从 `RawWaker` 创建的 `Waker` 的行为。
    /// 对于 `Waker` 上的每个操作，将调用基础 `RawWaker` 的 `vtable` 中的关联函数。
    ///
    ///
    ///
    #[inline]
    #[rustc_promotable]
    #[stable(feature = "futures_api", since = "1.36.0")]
    #[rustc_const_stable(feature = "futures_api", since = "1.36.0")]
    pub const fn new(data: *const (), vtable: &'static RawWakerVTable) -> RawWaker {
        RawWaker { data, vtable }
    }
}

/// 虚拟函数指针表 (vtable)，用于指定 [`RawWaker`] 的行为。
///
/// 传递给 vtable 内所有函数的指针是来自封闭的 [`RawWaker`] 对象的 `data` 指针。
///
/// 仅应在 [`RawWaker`] 实现内部从正确构造的 [`RawWaker`] 对象的 `data` 指针上调用此结构体内部的函数。
/// 使用任何其他 `data` 指针调用所包含的函数之一将导致未定义的行为。
///
///
///
///
#[stable(feature = "futures_api", since = "1.36.0")]
#[derive(PartialEq, Copy, Clone, Debug)]
pub struct RawWakerVTable {
    /// 克隆 [`RawWaker`] 时，例如克隆存储 [`RawWaker`] 的 [`Waker`] 时，将调用此函数。
    ///
    /// 此函数的实现必须保留 [`RawWaker`] 的此附加实例和关联任务所需的所有资源。
    /// 在生成的 [`RawWaker`] 上调用 `wake` 应该会唤醒原 [`RawWaker`] 会唤醒的相同任务。
    ///
    ///
    ///
    clone: unsafe fn(*const ()) -> RawWaker,

    /// 在 [`Waker`] 上调用 `wake` 时将调用此函数。
    /// 它必须唤醒与此 [`RawWaker`] 相关的任务。
    ///
    /// 此函数的实现必须确保释放与该 [`RawWaker`] 实例和关联任务相关联的所有资源。
    ///
    ///
    wake: unsafe fn(*const ()),

    /// 在 [`Waker`] 上调用 `wake_by_ref` 时将调用此函数。
    /// 它必须唤醒与此 [`RawWaker`] 相关的任务。
    ///
    /// 该函数与 `wake` 相似，但一定不能使用提供的数据指针。
    ///
    wake_by_ref: unsafe fn(*const ()),

    /// 丢弃 [`RawWaker`] 时将调用此函数。
    ///
    /// 此函数的实现必须确保释放与该 [`RawWaker`] 实例和关联任务相关联的所有资源。
    ///
    ///
    drop: unsafe fn(*const ()),
}

impl RawWakerVTable {
    /// 从提供的 `clone`，`wake`，`wake_by_ref` 和 `drop` 函数创建新的 `RawWakerVTable`。
    ///
    /// # `clone`
    ///
    /// 克隆 [`RawWaker`] 时，例如克隆存储 [`RawWaker`] 的 [`Waker`] 时，将调用此函数。
    ///
    /// 此函数的实现必须保留 [`RawWaker`] 的此附加实例和关联任务所需的所有资源。
    /// 在生成的 [`RawWaker`] 上调用 `wake` 应该会唤醒原 [`RawWaker`] 会唤醒的相同任务。
    ///
    /// # `wake`
    ///
    /// 在 [`Waker`] 上调用 `wake` 时将调用此函数。
    /// 它必须唤醒与此 [`RawWaker`] 相关的任务。
    ///
    /// 此函数的实现必须确保释放与该 [`RawWaker`] 实例和关联任务相关联的所有资源。
    ///
    ///
    /// # `wake_by_ref`
    ///
    /// 在 [`Waker`] 上调用 `wake_by_ref` 时将调用此函数。
    /// 它必须唤醒与此 [`RawWaker`] 相关的任务。
    ///
    /// 该函数与 `wake` 相似，但一定不能使用提供的数据指针。
    ///
    /// # `drop`
    ///
    /// 丢弃 [`RawWaker`] 时将调用此函数。
    ///
    /// 此函数的实现必须确保释放与该 [`RawWaker`] 实例和关联任务相关联的所有资源。
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[rustc_promotable]
    #[stable(feature = "futures_api", since = "1.36.0")]
    #[rustc_const_stable(feature = "futures_api", since = "1.36.0")]
    #[rustc_allow_const_fn_unstable(const_fn_fn_ptr_basics)]
    pub const fn new(
        clone: unsafe fn(*const ()) -> RawWaker,
        wake: unsafe fn(*const ()),
        wake_by_ref: unsafe fn(*const ()),
        drop: unsafe fn(*const ()),
    ) -> Self {
        Self { clone, wake, wake_by_ref, drop }
    }
}

/// 异步任务的 `Context`。
///
/// 当前，`Context` 仅用于提供对可用于唤醒当前任务的 `&Waker` 的访问。
///
#[stable(feature = "futures_api", since = "1.36.0")]
pub struct Context<'a> {
    waker: &'a Waker,
    // 通过强制生命周期不变 (参数位置生命周期是协变量，而返回位置生命周期是协变量) 来确保 future 能够抵抗方差变化。
    //
    //
    //
    _marker: PhantomData<fn(&'a ()) -> &'a ()>,
}

impl<'a> Context<'a> {
    /// 从 `&Waker` 创建一个新的 `Context`。
    #[stable(feature = "futures_api", since = "1.36.0")]
    #[inline]
    pub fn from_waker(waker: &'a Waker) -> Self {
        Context { waker, _marker: PhantomData }
    }

    /// 返回当前任务的 `Waker` 引号。
    #[stable(feature = "futures_api", since = "1.36.0")]
    #[inline]
    pub fn waker(&self) -> &'a Waker {
        &self.waker
    }
}

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

/// `Waker` 是通过通知执行者准备运行来唤醒任务的句柄。
///
/// 该句柄封装了 [`RawWaker`] 实例，该实例定义了特定于执行者的唤醒行为。
///
///
/// 实现 [`Clone`]，[`Send`] 和 [`Sync`]。
///
#[repr(transparent)]
#[stable(feature = "futures_api", since = "1.36.0")]
pub struct Waker {
    waker: RawWaker,
}

#[stable(feature = "futures_api", since = "1.36.0")]
impl Unpin for Waker {}
#[stable(feature = "futures_api", since = "1.36.0")]
unsafe impl Send for Waker {}
#[stable(feature = "futures_api", since = "1.36.0")]
unsafe impl Sync for Waker {}

impl Waker {
    /// 唤醒与此 `Waker` 相关的任务。
    #[inline]
    #[stable(feature = "futures_api", since = "1.36.0")]
    pub fn wake(self) {
        // 实际的唤醒调用通过虚拟函数调用委托给执行程序定义的实现。
        //
        let wake = self.waker.vtable.wake;
        let data = self.waker.data;

        // 不要调用 `drop` - `wake` 将消耗唤醒器。
        crate::mem::forget(self);

        // SAFETY: 这是安全的，因为 `Waker::from_raw` 是初始化 `wake` 和 `data` 的唯一方法，要求用户确认 `RawWaker` 的契约已得到遵守。
        //
        //
        unsafe { (wake)(data) };
    }

    /// 唤醒与此 `Waker` 相关的任务，而不消耗 `Waker`。
    ///
    /// 这与 `wake` 相似，但是在拥有 `Waker` 的情况下效率可能稍低。
    /// 此方法应该比调用 `waker.clone().wake()` 更可取。
    ///
    #[inline]
    #[stable(feature = "futures_api", since = "1.36.0")]
    pub fn wake_by_ref(&self) {
        // 实际的唤醒调用通过虚拟函数调用委托给执行程序定义的实现。
        //

        // SAFETY: 见 `wake`
        unsafe { (self.waker.vtable.wake_by_ref)(self.waker.data) }
    }

    /// 如果此 `Waker` 和另一个 `Waker` 唤醒了同一任务，则返回 `true`。
    ///
    /// 该函数在尽力而为的基础上起作用，即使 `Waker`s 唤醒相同的任务，也可能返回 false。
    /// 但是，如果此函数返回 `true`，则可以确保 Waker 唤醒相同的任务。
    ///
    /// 该函数主要用于优化目的。
    ///
    #[inline]
    #[stable(feature = "futures_api", since = "1.36.0")]
    pub fn will_wake(&self, other: &Waker) -> bool {
        self.waker == other.waker
    }

    /// 从 [`RawWaker`] 创建一个新的 `Waker`。
    ///
    /// 如果未遵守 [RawWaker`] 和 [`RawWakerVTable`] 文档中定义的契约，则返回的 `Waker` 的行为是不确定的。
    ///
    /// 因此，此方法是不安全的。
    #[inline]
    #[stable(feature = "futures_api", since = "1.36.0")]
    pub unsafe fn from_raw(waker: RawWaker) -> Waker {
        Waker { waker }
    }
}

#[stable(feature = "futures_api", since = "1.36.0")]
impl Clone for Waker {
    #[inline]
    fn clone(&self) -> Self {
        Waker {
            // SAFETY: 这是安全的，因为 `Waker::from_raw` 是初始化 `clone` 和 `data` 的唯一方法，要求用户确认 [`RawWaker`] 的契约已得到遵守。
            //
            //
            waker: unsafe { (self.waker.vtable.clone)(self.waker.data) },
        }
    }
}

#[stable(feature = "futures_api", since = "1.36.0")]
impl Drop for Waker {
    #[inline]
    fn drop(&mut self) {
        // SAFETY: 这是安全的，因为 `Waker::from_raw` 是初始化 `drop` 和 `data` 的唯一方法，要求用户确认 `RawWaker` 的契约已得到遵守。
        //
        //
        unsafe { (self.waker.vtable.drop)(self.waker.data) }
    }
}

#[stable(feature = "futures_api", since = "1.36.0")]
impl fmt::Debug for Waker {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let vtable_ptr = self.waker.vtable as *const RawWakerVTable;
        f.debug_struct("Waker")
            .field("data", &self.waker.data)
            .field("vtable", &vtable_ptr)
            .finish()
    }
}