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
122
123
124
125
126
127

#![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 表示通过使用 [`async`] 获得的异步计算。
///
/// future 是一个可能尚未完成计算的值。
/// 这种异步值使得，线程在等待值变为可用时，可以继续执行有用的工作。
///
///
/// # `poll` 方法
///
/// future 的核心方法 `poll` 试图将 future 解析为最终值。
/// 如果值未准备好，则此方法不会阻塞。
/// 取而代之的是，如果有可能通过再次轮询来取得进一步的进展，则计划将当前任务唤醒。
/// 传递给 `poll` 方法的 `context` 可以提供 [`Waker`]，它是唤醒当前任务的句柄。
///
/// 当使用 future 时，通常不会直接调用 `poll`，而是 `.await` 该值。
///
/// [`async`]: ../../std/keyword.async.html
/// [`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",
    note = "{Self} must be a future or must implement `IntoFuture` to be awaited"
)]
pub trait Future {
    /// 完成时产生的值类型。
    #[stable(feature = "futures_api", since = "1.36.0")]
    #[rustc_diagnostic_item = "FutureOutput"]
    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: 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> {
        <P::Target as Future>::poll(self.as_deref_mut(), cx)
    }
}