1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

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

use crate::marker::Unpin;
use crate::ops;
use crate::pin::Pin;
use crate::task::{Context, Poll};

/// future 表示异步计算。
///
/// future 是一个可能尚未完成计算的值。
/// 这种异步值使得，线程在等待值变为可用时，可以继续执行有用的工作。
///
///
/// # `poll` 方法
///
/// future 的核心方法 `poll` 试图将 future 解析为最终值。
/// 如果值未准备好，则此方法不会阻塞。
/// 取而代之的是，如果有可能通过再次轮询来取得进一步的进展，则计划将当前任务唤醒。
/// 传递给 `poll` 方法的 `context` 可以提供 [`Waker`]，它是唤醒当前任务的句柄。
///
/// 当使用 future 时，通常不会直接调用 `poll`，而是 `.await` 该值。
///
/// [`Waker`]: crate::task::Waker
///
///
///
#[doc(notable_trait)]
#[must_use = "futures do nothing unless you `.await` or poll them"]
#[stable(feature = "futures_api", since = "1.36.0")]
#[lang = "future_trait"]
#[rustc_on_unimplemented(label = "`{Self}` is not a future", message = "`{Self}` is not a future")]
pub trait Future {
    /// 完成时产生的值类型。
    #[stable(feature = "futures_api", since = "1.36.0")]
    type Output;

    /// 尝试将 future 解析为最终值，如果该值尚不可用，请注册当前任务以进行唤醒。
    ///
    /// # 返回值
    ///
    /// 该函数返回:
    ///
    /// - [`Poll::Pending`] 如果 future 还没有准备好
    /// - [`Poll::Ready(val)`] 如果成功完成，则返回 future 的结果 `val`。
    ///
    /// future 完成后，客户端不应再次对其进行 `poll`。
    ///
    /// 当 future 尚未准备好时，`poll` 返回 `Poll::Pending` 并存储从当前 [`Context`] 复制的 [`Waker`] 的副本。
    /// future 可以取得进展后，将唤醒该 [`Waker`]。
    /// 例如，等待套接字可读的 future 将在 [`Waker`] 上调用 `.clone()` 并将其存储。
    /// 当信号到达其他地方指示套接字可读时，将调用 [`Waker::wake`]，并且唤醒套接字 future 的任务。
    /// 一旦任务被唤醒，它应该尝试再次 `poll` future，这可能会或可能不会产生最终值。
    ///
    /// 请注意，在多次调用 `poll` 时，应仅计划将 [`Context`] 中传递给最新调用的 [`Waker`] 接收唤醒。
    ///
    /// # 运行时特征
    ///
    /// 单独的 Futures 是惰性的; 必须对它们进行主动轮询以取得进展，这意味着每次唤醒当前任务时，它都应主动重新轮询以等待仍对其感兴趣的 futures。
    ///
    /// `poll` 函数不会在紧密循环中重复调用 - 而是仅在 future 指示已准备好进行调用时 (通过调用 `wake()`) 才应调用它。
    /// 如果您熟悉 Unix 上的 `poll(2)` 或 `select(2)` 系统调用，则值得注意的是 futures 通常不会遭受与 "所有唤醒都必须轮询所有事件" 相同的问题; 他们更像 `epoll(4)`。
    ///
    /// `poll` 的实现应努力迅速返回，并且不应阻塞。快速返回可防止不必要地阻塞线程或事件循环。
    /// 如果提前得知对 `poll` 的调用可能要花一点时间，则应将工作卸载到线程池 (或类似的线程) 中，以确保 `poll` 可以快速返回。
    ///
    /// # Panics
    ///
    /// future 完成后 (从 `poll` 返回 `Ready`)，再次调用其 `poll` 方法可能会导致 panic 永久阻塞或引起其他类型的问题。`Future` trait 对这种调用的效果没有任何要求。
    /// 但是，由于 `poll` 方法未标记为 `unsafe`，因此适用 Rust 的通常规则: 调用绝不能引起未定义的行为 (内存损坏，`unsafe` 函数的错误使用等)，而与 future 的状态无关。
    ///
    ///
    /// [`Poll::Ready(val)`]: Poll::Ready
    /// [`Waker`]: crate::task::Waker
    /// [`Waker::wake`]: crate::task::Waker::wake
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[lang = "poll"]
    #[stable(feature = "futures_api", since = "1.36.0")]
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>;
}

#[stable(feature = "futures_api", since = "1.36.0")]
impl<F: ?Sized + Future + Unpin> Future for &mut F {
    type Output = F::Output;

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        F::poll(Pin::new(&mut **self), cx)
    }
}

#[stable(feature = "futures_api", since = "1.36.0")]
impl<P> Future for Pin<P>
where
    P: Unpin + ops::DerefMut<Target: Future>,
{
    type Output = <<P as ops::Deref>::Target as Future>::Output;

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        Pin::get_mut(self).as_mut().poll(cx)
    }
}