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 128 129 130 131 132 133 134 135 136 137 138 139 140
use crate::future::Future;
/// 转换为 `Future`。
///
/// 通过为类型实现 `IntoFuture`,您可以定义如何将其转换为 future。
///
/// # `.await` 脱糖
///
/// 在轮询 future 完成之前,`.await` 关键字首先脱糖到 `IntoFuture::into_future` 的调用中。
/// `IntoFuture` 适用于所有 `T: Future`,这意味着 `into_future` 方法将适用于所有 futures。
///
/// ```no_run
/// use std::future::IntoFuture;
///
/// # async fn foo() {
/// let v = async { "meow" };
/// let mut fut = v.into_future();
/// assert_eq!("meow", fut.await);
/// # }
/// ```
///
/// # 异步构建器
///
/// 当手动实现 futures 时,通常会在为一个类型实现 `Future` 或 `IntoFuture` 之间做出选择。
/// 在大多数情况下,实现 `Future` 是一个不错的选择。
/// 但是在实现 "async builder" 类型时实现 `IntoFuture` 是最有用的,它允许在被 `.await` 编辑之前多次修改它们的值。
///
/// ```rust
/// use std::future::{ready, Ready, IntoFuture};
///
/// /// 最终将两个数字相乘
/// pub struct Multiply {
/// num: u16,
/// factor: u16,
/// }
///
/// impl Multiply {
/// /// 创建一个新的 `Multiply` 实例。
/// pub fn new(num: u16, factor: u16) -> Self {
/// Self { num, factor }
/// }
///
/// /// 设置要乘以因子的数字。
/// pub fn number(mut self, num: u16) -> Self {
/// self.num = num;
/// self
/// }
///
/// /// 设置要与数字相乘的因子。
/// pub fn factor(mut self, factor: u16) -> Self {
/// self.factor = factor;
/// self
/// }
/// }
///
/// impl IntoFuture for Multiply {
/// type Output = u16;
/// type IntoFuture = Ready<Self::Output>;
///
/// fn into_future(self) -> Self::IntoFuture {
/// ready(self.num * self.factor)
/// }
/// }
///
/// // NOTE: Rust 还没有 `async fn main` 函数,该功能目前仅存在于生态系统中。
/////
/// async fn run() {
/// let num = Multiply::new(0, 0) // 将构建器初始化为数字: 0,因子: 0
/// .number(2) // 将数字更改为 2
/// .factor(2) // 将因子更改为 2
/// .await; // 转换为 future 和 .await
///
/// assert_eq!(num, 4);
/// }
/// ```
///
/// # trait bounds 中的用法
///
/// 在 trait 中使用 `IntoFuture` bounds 允许函数在 `Future` 和 `IntoFuture` 上都是泛型。
/// 这对函数的用户来说很方便,所以当他们使用它时,他们不必对 `IntoFuture::into_future` 进行额外的调用来获取 `Future` 的实例:
///
///
/// ```rust
/// use std::future::IntoFuture;
///
/// /// 将 future 的输出转换为字符串。
/// async fn fut_to_string<Fut>(fut: Fut) -> String
/// where
/// Fut: IntoFuture,
/// Fut::Output: std::fmt::Debug,
/// {
/// format!("{:?}", fut.await)
/// }
/// ```
///
///
///
///
///
///
#[stable(feature = "into_future", since = "1.64.0")]
#[rustc_diagnostic_item = "IntoFuture"]
pub trait IntoFuture {
/// future 完成时将产生的输出。
#[stable(feature = "into_future", since = "1.64.0")]
type Output;
/// 我们要把它变成哪种 future?
#[stable(feature = "into_future", since = "1.64.0")]
type IntoFuture: Future<Output = Self::Output>;
/// 根据一个值创建一个 future。
///
/// # Examples
///
/// 基本用法:
///
/// ```no_run
/// use std::future::IntoFuture;
///
/// # async fn foo() {
/// let v = async { "meow" };
/// let mut fut = v.into_future();
/// assert_eq!("meow", fut.await);
/// # }
/// ```
#[stable(feature = "into_future", since = "1.64.0")]
#[lang = "into_future"]
fn into_future(self) -> Self::IntoFuture;
}
#[stable(feature = "into_future", since = "1.64.0")]
impl<F: Future> IntoFuture for F {
type Output = F::Output;
type IntoFuture = F;
fn into_future(self) -> Self::IntoFuture {
self
}
}