Rust async/await 状态机展开原理:从 .rs 源码到 Future 状态机的底层旅程

一、深度引言与场景痛点
你写过这样的代码吗?
async fn fetch_and_process() -> Result<Data, Error> {
let data = fetch_from_api().await?;
let processed = process(data).await;
Ok(processed)
}
代码很清爽。await 像一个暂停键,挂起当前任务,让出控制权,然后继续执行。一切看起来都很自然、很直观。
但当你有一天想要自定义一个异步逻辑——比如实现一个支持取消的超时请求、或者想在异步闭包中捕获可变引用——编译器就会扔出一堆你看不太懂的错误信息。
error:
asynctrait methods can't be used in a stable releaseerror: future cannot be shared between threads safely
这些错误的背后,是一个你从未见过的东西:状态机。
Rust 的 async/await 不是关键字魔术,不是宏展开的黑魔法,而是编译器严格遵循语言规范、按部就班完成的语法到语义的精确翻译。每一个 .await 都是一个状态节点,每一次 poll 都是一次状态转移。
如果你能理解这套翻译机制,你就掌握了 Rust 异步编程的真正底层逻辑。而不是只会 copy-paste .await,然后祈祷它不会 panic。
这篇文章,我们从一个简单的 async fn 出发,逐步剥开编译器对它的层层变换。你会看到 .rs 文件是怎么变成一个个状态机结构的。你会理解 Future trait 的 poll 方法为什么需要返回 Poll 而不是简单的 Option。你会搞清楚为什么 Future 需要 Pin 保护。你还会看到一个生产级别的异步代码应该怎么写。
废话不多说,直接上干货。
二、底层机制与原理深度剖析
2.1 async fn 的第一次变形:从函数到结构体
让我们从一个最简单的 async fn 开始:
// 源码中的写法 —— 很简洁,很友好
async fn add_one(x: i32) -> i32 {
x + 1
}
编译器看到这个 async fn 的时候,脑子里在想什么?它在想:"这个函数会挂起,挂起就需要保存现场。那我把这个函数的所有局部变量,全部打包成一个结构体。"
编译器展开后的代码大致如下:
// 编译器生成的伪代码 —— 实际上还有更多细节
struct AddOneFuture {
x: i32, // 函数参数变成结构体字段
// 状态变量、临时变量都会被捕获
}
impl Future for AddOneFuture {
type Output = i32;
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
// 计算 x + 1 并返回
Poll::Ready(self.x + 1)
}
}
注意几个关键点:
第一,原来的函数参数变成了结构体的字段。因为挂起时需要保持参数的值。
第二,Future::poll 接收的是 Pin<&mut Self> 而不是 &mut Self。这是 Rust 异步系统的核心约束之一,我们后面会详细解释。
第三,poll 返回 Poll<Self::Output>。这是一个枚举,有两个变体:Ready(T) 表示计算完成,Pending 表示还没算完。
2.2 带 await 的状态机
更有趣的情况是包含 .await 的代码:
// 源码
async fn greet(name: String) -> String {
let greeting = say_hello(name).await; // 第一个 await 点
format!("Hello, {}!", greeting).await // 第二个 await 点
}
编译器会把这段代码变成一个包含多个状态的状态机:
stateDiagram-v2
[*] --> State0: 初始态,捕获 name 参数
State0 --> State1: say_hello 完成,绑定 greeting
State1 --> State2: 字符串拼接完成
State2 --> [*]: 返回最终结果
State0 : 状态0\n等待 say_hello
State1 : 状态1\n等待 format 完成
State2 : 状态2\n准备就绪
编译器的展开逻辑是这样的:
// 编译器展开后的伪代码(简化版)
enum GreetFuture {
// 每个 .await 对应一个状态变体
State0 { name: String }, // 等待 say_hello 返回
State1 { greeting: String }, // 等待 format 返回
Done { result: String }, // 计算完成
}
impl Future for GreetFuture {
type Output = String;
fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
match self.as_mut().get_mut() {
GreetFuture::State0 { name } => {
// 取出 say_hello 的 future,poll 它
let mut future = say_hello(name.clone());
match Pin::new(&mut future).poll(cx) {
Poll::Ready(greeting) => {
// 进入下一个状态
*self.as_mut().get_mut() = GreetFuture::State1 { greeting };
// 重新 poll 进入下一个分支
return Pin::new_mut(self).poll(cx);
}
Poll::Pending => return Poll::Pending,
}
}
GreetFuture::State1 { greeting } => {
let final_string = format!("Hello, {}!", greeting);
*self.as_mut().get_mut() = GreetFuture::Done { result: final_string };
return Poll::Ready(self.as_mut().get_mut().result.clone());
}
GreetFuture::Done { .. } => {
panic!("poll after Ready is a violation of the Future contract");
}
}
}
}
这段代码虽然长,但逻辑非常朴素:每个 .await 就是一个状态转移点。编译器负责把所有的局部变量打包成状态机结构,然后生成一个巨大的 match 表达式。
2.3 Future trait 与 poll 机制
我们来看 Future trait 的定义:
trait Future {
type Output;
// poll 是异步运行的核心引擎
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>;
}
Poll 枚举的定义:
enum Poll<T> {
Ready(T), // 异步计算已经完成,返回结果
Pending, // 异步计算还在进行中,稍后再试
}
这里有一个非常关键的设计决策:poll 为什么接受 Pin<&mut Self>?
答案是:有些 future 内部持有指向自身数据的指针。如果 future 在内存中被移动了,这些指针就会失效,导致 undefined behavior。Pin 保证了 future 在 poll 期间不会被移动。
举个例子:
use std::pin::Pin;
use std::future::Future;
use std::task::{Context, Poll};
// 一个自引用的 future(极端但真实存在的场景)
struct SelfReferentialFuture {
data: String,
// 如果 future 被移动,data_ptr 会指向错误的位置
// 这就是为什么需要 Pin
}
impl Future for SelfReferentialFuture {
type Output = ();
fn poll(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Self::Output> {
// self 被 Pin 保护,不能移动
println!("Polled");
Poll::Ready(())
}
}
2.4 async 闭包与 async-trait
async 闭包和普通闭包有一个根本区别:普通闭包返回的具体类型是匿名的、不可名的。你没法在函数签名里写出 async { ... } 的类型。
// 这行代码编译不过去
fn take_future() -> ??? {
async { 42 } // 类型是匿名的,无法命名
}
解决方案有两种:
方案一:使用 Box::pin 转化为 trait object
use std::future::Future;
async fn create_boxed_future() -> Box<dyn Future<Output = i32>> {
Box::pin(async { 42 })
// Box::pin 把匿名 future 变成 Pin<Box<dyn Future>>
// 通过 heap 分配 + trait object 来隐藏具体类型
}
方案二:使用 async-trait 宏
这个宏解决的是另一个经典问题:在 trait 中定义 async fn。
use async_trait::async_trait;
#[async_trait]
trait Fetcher {
async fn fetch(&self, url: &str) -> Result<String, Error>;
}
// 宏展开后大致等价于:
trait Fetcher {
fn fetch<'a>(&'a self, url: &'a str)
-> Pin<Box<dyn Future<Output = Result<String, Error>> + Send + 'a>>;
}
async-trait 宏的展开方式是:把 async fn 变成一个返回 Pin<Box<dyn Future>> 的普通函数。这样 trait 方法就可以被正常使用了。
代价呢?每一次调用都会产生一次 heap 分配。性能有损失,但这是为了 trait 兼容性付出的合理代价。
三、生产级代码实现与最佳实践
3.1 带超时的异步请求
use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};
use std::time::Duration;
use tokio::time::{timeout, sleep};
/// 为任意 Future 添加超时包装器
struct TimeoutFuture<F> {
inner: F,
timeout_remaining: Duration,
}
impl<F: Future> Future for TimeoutFuture<F> {
type Output = Result<F::Output, &'static str>;
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
// 获取内部 future 的可变引用,同时保持 Pin
let this = self.get_mut();
let inner_future = unsafe { Pin::new_unchecked(&mut this.inner) };
match inner_future.poll(cx) {
Poll::Ready(output) => {
// 正常完成,包装结果
Poll::Ready(Ok(output))
}
Poll::Pending => {
// 还没完成,但超时检测需要另行安排
// 在生产环境中,这里通常会注册一个定时器 waker
// 下面只是一个简化示意
Poll::Pending
}
}
}
}
/// 使用 tokio 的 timeout 工具函数(推荐做法)
async fn fetch_with_timeout(url: &str) -> Result<String, Box<dyn std::error::Error>> {
// timeout 的返回值是 Result<T, Elapsed>
// 这是最清晰、最不易出错的超时模式
match timeout(Duration::from_secs(5), req(url)).await {
Ok(Ok(body)) => Ok(body),
Ok(Err(e)) => Err(Box::new(e)),
Err(_) => Err("请求超时,5 秒内未完成".into()),
}
}
async fn req(_url: &str) -> Result<String, std::io::Error> {
sleep(Duration::from_millis(100)).await;
Ok("response body".to_string())
}
超时包装的核心思想:将超时逻辑内嵌到状态机中。timeout 函数本身也是一个 future,它内部维护了一个定时器 waker。当定时器触发时,它会主动唤醒主 future,然后返回 Elapsed 错误。
3.2 取消安全性(Cancellation Safety)
取消安全性是异步编程中最容易被忽略、也最危险的陷阱之一。
什么是取消安全性?简单说:一个异步操作被取消后,如果它能保证不留下任何副作用或中间状态,那么它就是取消安全的。
来看一个反例:
use tokio::io::AsyncWriteExt;
// 不安全的写法 —— 被取消会导致数据丢失
async fn write_two_chunks(
writer: &mut tokio::fs::File,
chunk1: &[u8],
chunk2: &[u8],
) -> std::io::Result<()> {
// 如果第一次写入成功,但在第二次写入前被取消
// chunk1 已经写入了磁盘,但 chunk2 没有
// 调用者不知道写到了哪里,陷入不一致状态
writer.write_all(chunk1).await?;
writer.write_all(chunk2).await?;
Ok(())
}
正确的做法是使用 tokio::io::write_all 这样的组合子,或者手动检查取消点:
// 安全的写法 —— 每一步都是原子的
async fn write_two_chunks_safe(
writer: &mut tokio::fs::File,
chunk1: &[u8],
chunk2: &[u8],
) -> std::io::Result<()> {
// 确保每次写入都是完整的、可回退的
writer.write_all(chunk1).await?;
writer.flush().await?; // 强制落盘
writer.write_all(chunk2).await?;
writer.flush().await?; // 再次落盘
Ok(())
}
原则就是:在 .await 之间保持操作的原子性。 如果两次 .await 之间可能发生取消,那么要么把整个逻辑包装成一个原子操作,要么在取消后有能力回滚。
3.3 错误处理与组合
use tokio::task::JoinHandle;
use tokio::sync::mpsc;
/// 并发拉取多个数据源,全部成功才返回
async fn fetch_all_concurrent(
urls: Vec<String>,
) -> Result<Vec<String>, Vec<(&str, std::io::Error)>> {
let mut handles: Vec<JoinHandle<Result<String, std::io::Error>>> = Vec::new();
// 为每个 URL 创建并发任务
for url in &urls {
let handle = tokio::spawn(fetch_single(url.clone()));
handles.push(handle);
}
let mut results = Vec::new();
let mut errors = Vec::new();
// 收集结果 —— 逐个 poll 每个 join handle
for (i, handle) in handles.into_iter().enumerate() {
match handle.await {
Ok(Ok(body)) => results.push(body),
Ok(Err(e)) => errors.push((urls[i].as_str(), e)),
Err(join_error) => {
// task panic 了,这是最糟糕的情况
errors.push((urls[i].as_str(), std::io::Error::new(
std::io::ErrorKind::Other,
format!("task panicked: {join_error}"),
)));
}
}
}
// 全部成功返回 Ok,否则返回所有错误
if errors.is_empty() {
Ok(results)
} else {
Err(errors)
}
}
async fn fetch_single(_url: String) -> Result<String, std::io::Error> {
tokio::time::sleep(tokio::time::Duration::from_millis(50)).await;
Ok("data".to_string())
}
这段代码展示了几个关键点:
tokio::spawn把异步任务放到运行时上执行JoinHandle本身也是一个 Future,可以.await等待结果- 错误收集采用 "all-or-nothing" 模式,全部成功或返回所有错误
Err变体中包含了每个失败任务对应的 URL,方便定位问题
四、边界分析与架构权衡
4.1 状态机展开的代价
编译器对 async fn 的展开不是没有代价的:
编译时间:每个
.await都会增加状态机的复杂度。一个包含 10 个.await的函数,其展开后的枚举可能有超过 10 个状态变体。编译器的 monomorphization 和 MIR 优化都要处理更大的中间表示。二进制体积:状态机结构体通常比原始代码更大。因为需要保存所有跨 await 点的局部变量。
展开深度:嵌套的 async 函数会叠加状态机。
async fn A { async fn B {} }中的 B 的状态机会被嵌入 A 的状态机中。如果嵌套过深,可能导致编译性能下降。
建议:保持异步函数简短,单一职责。把复杂逻辑拆成多个小的 async 函数,而不是一个大的 async 函数包打天下。
4.2 Pin 的性能开销
Pin 是一个零大小类型(ZST)。它本身不占用任何运行时空间,也没有虚表开销。但是:
Pin::new和Pin::new_unchecked是零成本抽象UnsafeCell在编译器优化良好的情况下几乎不产生额外指令- 在某些极端场景下(大量 Pin/Unpin 操作),编译器可能无法彻底消除安全检查
建议:不要过度使用 unsafe { Pin::new_unchecked }。只有在确实需要绕过 Pin 保护时才用,并且确保你有充分的理由。
4.3 async-trait 与性能
async-trait 宏的 heap 分配开销:
| 方案 | 分配 | 多态方式 | 运行时开销 |
|---|---|---|---|
| 泛型实现 | 无 | 单态化 | 几乎为零 |
| async-trait 宏 | 每次调用 | 动态分发 | 堆分配 + vtable |
| 返回 Pin<Box> | 每次调用 | 动态分发 | 同上 |
建议:
- 在库代码中,优先使用泛型而不是 trait object
- 需要 trait 对象多态时,考虑
async_trait的性能预算 - 在性能敏感路径上(如高频调用的 handler),避免使用
async_trait
4.4 状态机 vs 协程
Rust 的 async 状态机和 Kotlin/Go 的协程有本质区别:
- Rust:每个 async 函数在编译期展开为确定类型的状态机。类型系统全程参与,零运行时协程栈管理开销。
- Kotlin/Go:协程栈在运行时动态分配和管理。更灵活,但有运行时开销。
Rust 的方式更硬核,但也更可控。你清楚每一字节内存的用途,清楚每一次状态转移的细节。这种确定性是 Rust 异步系统的核心优势。
五、总结
我们从一段简单的 async fn 出发,走过了编译器的展开过程。看到了 .await 如何变成状态机中的节点。理解了 Future::poll 为什么需要 Pin。探讨了 async-trait 的宏展开机制和生产级异步代码的最佳实践。
核心要点回顾:
async fn被编译器翻译成包含所有局部变量的结构体,实现Futuretrait- 每个
.await对应一个状态节点,poll方法中的match实现状态转移 Pin<&mut Self>保证 self-referential 结构的内存安全- 取消安全性要求在每个
.await点考虑操作是否可回滚 async-trait通过 heap 分配换取 trait 兼容性,有性能代价但通常可接受
Rust 的异步系统看起来复杂,但底层逻辑非常纯粹。它不依赖任何神秘的运行时,不引入黑盒的协程调度器。它所做的,只是把异步代码精确地翻译成编译器能够理解、优化和推理的状态机。
当你下一次看到 await 的时候,不妨想一想:此刻,状态机正在经历一次状态转移。而这一切,发生在零成本抽象的承诺之下。
如果你能在这种视角下写代码,你就不仅仅是在用 Rust 的异步语法。你是在和 Rust 的运行时对话。
180



被折叠的 条评论
为什么被折叠?



