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)
}
}