用 Rust 从零实现一个 Future 执行器:Waker 到底是干什么的
用 tokio 写了大半年
.await,但被问到"Future 是谁在跑"的时候,很多人答不上来。
答案有点反直觉:Future 自己不会跑。 它只是一台没插电的机器,poll 一下它就往前走一步,然后告诉你"我还没好"或者"我好了"。真正反复去 poll 它的,是执行器(Executor)。
而执行器和 Future 之间怎么通信——"什么时候该再来 poll 我一次"——靠的是 Waker。
这篇用标准库从零写一个执行器,三样东西:Future、Pin、Waker。
第一件事:Future 的接口
pub trait Future {
type Output;
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>;
}
pub enum Poll<T> {
Ready(T),
Pending,
}展开看就三个问题:
Poll表示两种状态:好了,或者还没好Context里装着Waker,是 Future 通知执行器的方式Pin<&mut Self>是为了解决自引用问题
先看最简单的部分——手写一个 Future。
手写一个 Ready Future
use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};
struct Ready<T>(Option<T>);
impl<T> Future for Ready<T> {
type Output = T;
fn poll(mut self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<T> {
Poll::Ready(self.0.take().expect("polled after completion"))
}
}这个 Future 第一次 poll 立刻返回 Ready。它不需要 Waker,因为它从不 Pending。
fn ready<T>(value: T) -> Ready<T> {
Ready(Some(value))
}手写一个真正会 Pending 的 Future
再看一个真正需要 Waker 的例子——一个定时器(伪实现,用它来观察 Pending):
struct YieldNow {
yielded: bool,
}
impl Future for YieldNow {
type Output = ();
fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
if self.yielded {
Poll::Ready(())
} else {
self.yielded = true;
// 关键:告诉执行器"现在轮到我,但我还没好,请稍后再来"
cx.waker().wake_by_ref();
Poll::Pending
}
}
}wake_by_ref() 是这里的核心。它调用的就是 Waker:
pub struct Waker { /* ... */ }
impl Waker {
pub fn wake(self) { /* 消费自己 */ }
pub fn wake_by_ref(&self) { /* 借用版本 */ }
}Waker 的语义只有一条:调用 wake(),就是通知执行器"可以再 poll 一次这个 Future 了"。 它不做别的。
这个约定把"什么时候该重试"的责任交给了 Future 自己:
- IO Future:注册好 epoll 监听,当 fd 可读时由 reactor 调
wake() - 定时器 Future:把
wake()塞进定时器队列,到期时调用 YieldNow:立刻调用,表示"让出去一轮"
Waker 不是回调,是一次"续约邀请"。执行器不会主动轮询 Future,除非 Waker 响了。
第二件事:为什么需要 Pin
先看一段会编译失败的代码:
// 这是自引用结构,编译不过
struct SelfRef {
data: String,
ptr: *const String, // 指向自己的 data
}
impl SelfRef {
fn new(data: String) -> Self {
let mut s = SelfRef { data, ptr: std::ptr::null() };
s.ptr = &s.data;
s
}
}这个结构的问题在于:一旦 s 被移动,ptr 就指向了旧地址——悬垂指针。
而 async 生成的 Future 天然是这种结构。看这段:
async fn example() {
let s = String::from("hello");
let borrow = &s; // 借用局部变量
do_something(borrow).await; // 挂起点
println!("{}", borrow);
}await 点之间,s 和 borrow 都要存活在 Future 的状态机里,borrow 指向 s。这个 Future 一旦被移动,borrow 就失效了。
Pin 就是来解决这件事的:它是一个"我保证不再移动你"的包装。
impl<T> Pin<&mut T> {
/// 只有 T: Unpin 才能安全拿到 &mut T
pub fn get_mut(self) -> &mut T where T: Unpin { /* ... */ }
/// 不安全:承诺不会再移动
pub unsafe fn get_unchecked_mut(self) -> &mut T { /* ... */ }
}这也解释了为什么 Pin 的 API 里到处都是 where T: Unpin:Unpin 是"可以安全移动"的标记 trait。 绝大多数类型都自动实现 Unpin(因为它们是可安全移动的),只有自引用的状态机不是。
回到前面 YieldNow 的代码:
impl Future for YieldNow {
fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
if self.yielded { ... }
}
}self.yielded = true 能直接写,是因为 YieldNow 是 Unpin 的(它是个普通结构体),所以 Pin<&mut Self> 可以 DerefMut 到 &mut Self。
第三件事:写执行器
现在把执行器拼起来。最简单的一个循环版本:
use std::future::Future;
use std::pin::Pin;
use std::sync::{Arc, Mutex};
use std::task::{Context, Poll, Wake, Waker};
struct ThreadWaker {
thread: std::thread::Thread,
}
impl Wake for ThreadWaker {
fn wake(self: Arc<Self>) {
self.thread.unpark();
}
}Wake trait 是 Waker 的构造来源。标准库提供了这个 trait,实现它就能得到合法的 Waker。
pub fn block_on<F: Future>(fut: F) -> F::Output {
let mut fut = Box::pin(fut); // 固定在堆上,保证不移动
let thread = std::thread::current();
let waker = Waker::from(Arc::new(ThreadWaker { thread }));
let mut cx = Context::from_waker(&waker);
loop {
match fut.as_mut().poll(&mut cx) {
Poll::Ready(out) => return out,
Poll::Pending => {
// 挂起当前线程,等 Waker 唤醒
std::thread::park();
}
}
}
}就这么点代码,但已经把异步执行器的本质讲完了:
Box::pin把 Future 固定住,因为后面可能反复 poll 它,不能移动- 构造 Waker,把"唤醒"动作绑定到
unpark - 循环 poll:
Ready就返回,Pending就park挂起,等 Waker 来叫
block_on就是"一个线程 + 一个 Future + 一个循环"。所有执行器都是这个骨架的扩展。
用一个真实例子验证:
fn main() {
let out = block_on(async {
let a = ready(1).await;
let b = ready(2).await;
a + b
});
println!("{out}"); // 3
}因为 Ready 从不 Pending,这个循环跑两轮就结束了。
扩展到多任务:任务队列
前面的 block_on 只能跑一个 Future。要跑多个,需要一个任务队列,Waker 负责把任务重新推回队列。
type Task = Pin<Box<dyn Future<Output = ()> + Send>>;
struct Executor {
queue: Mutex<std::collections::VecDeque<Arc<Task>>>,
// 用来唤醒 executor 主循环
signal: std::thread::Thread,
}对应的 Waker:
struct TaskWaker {
queue: Arc<Mutex<std::collections::VecDeque<Arc<Task>>>>,
signal: std::thread::Thread,
}
impl Wake for TaskWaker {
fn wake(self: Arc<Self>) {
// 唤醒就是"把自己重新放回队列"
self.signal.unpark();
}
}这就是 Reactor 和执行器的接口:IO 完成时,reactor 调用 Waker,Waker 把任务推回队列,执行器下一轮再 poll 它。
真实运行时的完整流程:
1. executor 从队列取出任务,调用 poll
2. poll 返回 Pending,同时 future 已经把 waker 注册到了 reactor
3. executor 去处理其他任务(或 park)
4. reactor 检测到 IO 就绪,调用 waker.wake()
5. waker 把任务重新入队,回到步骤 1tokio 的复杂度主要在 2 和 4 的实现上:怎么注册到 epoll、怎么管理计时器、怎么用多个线程跑、work-stealing 调度……但骨架就是上面这五步。
三个容易踩的坑
1. poll 完再 poll 会 panic。 前面 Ready 的实现里有:
Poll::Ready(self.0.take().expect("polled after completion"))Future 的契约是:一旦返回 Ready,就绝不能再被 poll。 违反是逻辑错误,所以直接 expect 报错比"悄悄返回旧值"更好。
2. Waker 必须保证被调用。 如果 Future 返回 Pending 但没保存 Waker,执行器会永远 park,整个程序卡死。这是新手写 Future 最常见的 bug。
3. park 有丢失唤醒问题。 如果 Waker 在 poll 和 park 之间被调用,unpark 的许可会被记住(标准库保证了这一点),下一次 park 立刻返回——所以标准库的 park 是安全的。但自己实现的条件变量就没这个保证,必须和状态一起检查。
结论
异步执行器拆开就三块拼图:
Future::poll是工作单元;Waker是"准备好了叫我"的通知;Pin是保证自引用状态机不被移动的护栏。执行器是一个 poll 循环 + 一个任务队列。
把 block_on 写一遍,再看 tokio::spawn,你会发现它神秘感全没了——它只是在后面加上了 epoll、时间轮、多线程调度器和 work-stealing。下一轮我们就去把这套 reactor 补上。