Context 与 Waker ​

核心概念 ​

Context 和 Waker 是 Rust 异步运行时与 Future 之间的通信桥梁,定义在 std::task 模块中。Context 是 Future::poll 方法的第二个参数,目前它的主要作用就是携带一个 Waker。Waker 是一个唤醒器——当 Future 返回 Poll::Pending 时,它需要在未来某个时刻调用 Waker 来通知运行时"我准备好了,请再次 poll 我"。没有 Waker,运行时不知道什么时候该重新轮询一个 Future,Future 就会永远沉睡。Waker 实现了 Clone 和 Send,可以被传递到其他线程或存储在回调中。

rust
use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll, Waker};

// Context 的定义(简化版):
// pub struct Context<'a> {
//     waker: &'a Waker,
// }
//
// impl<'a> Context<'a> {
//     pub fn waker(&self) -> &'a Waker { ... }
// }

// Waker 的关键方法:
// impl Waker {
//     pub fn wake(self) { ... }        // 唤醒,消耗 self
//     pub fn wake_by_ref(&self) { ... } // 唤醒,不消耗 self
//     pub fn will_wake(&self, other: &Waker) -> bool { ... }
// }

// 简单示例:一个需要 Waker 的 Future
struct WakerDemo {
    done: bool,
}

impl Future for WakerDemo {
    type Output = &'static str;

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<&'static str> {
        if self.done {
            Poll::Ready("完成")
        } else {
            self.done = true;
            // 通过 Context 获取 Waker,通知运行时再次 poll
            cx.waker().wake_by_ref();
            Poll::Pending
        }
    }
}

#[tokio::main]
async fn main() {
    let result = WakerDemo { done: false }.await;
    println!("{}", result);
}

Waker 的工作原理 ​

rust
use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};
use std::sync::{Arc, Mutex};
use std::thread;
use std::time::Duration;

// Waker 的核心职责:
// 1. Future 返回 Pending 时,保存 Waker
// 2. 当某个事件发生(IO就绪、定时器到期等),调用 Waker
// 3. 运行时收到唤醒通知后,重新 poll 对应的 Future

// 模拟一个等待外部事件的 Future
struct ExternalEvent {
    // 共享状态:存放结果和 Waker
    shared: Arc<Mutex<SharedState>>,
}

struct SharedState {
    completed: bool,
    result: Option<String>,
    waker: Option<std::task::Waker>,  // 保存 Waker
}

impl ExternalEvent {
    fn new(delay_ms: u64) -> Self {
        let shared = Arc::new(Mutex::new(SharedState {
            completed: false,
            result: None,
            waker: None,
        }));

        // 启动一个线程模拟外部事件
        let shared_clone = Arc::clone(&shared);
        thread::spawn(move || {
            // 模拟等待外部事件
            thread::sleep(Duration::from_millis(delay_ms));

            let mut state = shared_clone.lock().unwrap();
            state.completed = true;
            state.result = Some(format!("事件在{}ms后发生", delay_ms));

            // 关键:调用 Waker 唤醒 Future
            if let Some(waker) = state.waker.take() {
                waker.wake();  // 通知运行时重新 poll
            }
        });

        ExternalEvent { shared }
    }
}

impl Future for ExternalEvent {
    type Output = String;

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<String> {
        let mut state = self.shared.lock().unwrap();

        if state.completed {
            // 事件已发生,返回结果
            Poll::Ready(state.result.take().unwrap())
        } else {
            // 事件未发生,保存 Waker 以便稍后唤醒
            state.waker = Some(cx.waker().clone());
            Poll::Pending
        }
    }
}

#[tokio::main]
async fn main() {
    println!("等待外部事件...");
    let result = ExternalEvent::new(200).await;
    println!("收到: {}", result);

    // 并发等待多个事件
    let (r1, r2, r3) = tokio::join!(
        ExternalEvent::new(100),
        ExternalEvent::new(200),
        ExternalEvent::new(150),
    );
    println!("事件1: {}", r1);
    println!("事件2: {}", r2);
    println!("事件3: {}", r3);
}

wake 和 wake_by_ref 的区别 ​

rust
use std::task::Waker;

// wake(self):消耗 Waker,调用后不能再使用
// wake_by_ref(&self):借用 Waker,调用后仍可使用

// 选择指南:
// - 如果调用后不再需要 Waker → 用 wake()(可能更高效)
// - 如果调用后还需要保留 Waker → 用 wake_by_ref()

use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};

struct RepeatPoll {
    count: u32,
    max: u32,
}

impl Future for RepeatPoll {
    type Output = u32;

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<u32> {
        self.count += 1;

        if self.count >= self.max {
            // 最后一次,不再需要 Waker
            Poll::Ready(self.count)
        } else {
            // 还需要被 poll,使用 wake_by_ref 保留 Waker
            // 这样下次 poll 时 Waker 仍然有效
            cx.waker().wake_by_ref();
            Poll::Pending
        }
    }
}

#[tokio::main]
async fn main() {
    let result = RepeatPoll { count: 0, max: 5 }.await;
    println!("经过 {} 次 poll", result);
}
方法签名消耗 Waker适用场景
wake()fn wake(self)是最后一次唤醒,不再需要 Waker
wake_by_ref()fn wake_by_ref(&self)否可能需要多次唤醒
will_wake()fn will_wake(&self, other: &Waker) -> bool否检查两个 Waker 是否唤醒同一个任务

Waker 的存储与传递 ​

rust
use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll, Waker};
use std::sync::{Arc, Mutex};
use std::thread;
use std::time::Duration;

// 实际的异步原语需要存储 Waker
// 当事件发生时,通过存储的 Waker 唤醒对应的 Future

struct AsyncTimer {
    state: Arc<Mutex<TimerState>>,
}

struct TimerState {
    expired: bool,
    waker: Option<Waker>,
}

impl AsyncTimer {
    fn new(duration: Duration) -> Self {
        let state = Arc::new(Mutex::new(TimerState {
            expired: false,
            waker: None,
        }));

        let state_clone = Arc::clone(&state);
        thread::spawn(move || {
            thread::sleep(duration);

            let mut s = state_clone.lock().unwrap();
            s.expired = true;

            // 唤醒等待中的 Future
            if let Some(waker) = s.waker.take() {
                println!("  定时器到期,唤醒 Future");
                waker.wake();
            }
        });

        AsyncTimer { state }
    }
}

impl Future for AsyncTimer {
    type Output = ();

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
        let mut state = self.state.lock().unwrap();

        if state.expired {
            Poll::Ready(())
        } else {
            // 检查是否需要更新 Waker
            // 如果任务被移动到不同的执行器线程,Waker 可能变了
            let new_waker = cx.waker();
            match &state.waker {
                Some(existing) if existing.will_wake(new_waker) => {
                    // Waker 没变,不需要更新
                }
                _ => {
                    // 更新 Waker
                    state.waker = Some(new_waker.clone());
                }
            }
            Poll::Pending
        }
    }
}

#[tokio::main]
async fn main() {
    println!("开始计时...");
    let start = std::time::Instant::now();

    AsyncTimer::new(Duration::from_millis(300)).await;
    println!("300ms 定时器完成: {:?}", start.elapsed());

    // 并发多个定时器
    let start = std::time::Instant::now();
    tokio::join!(
        AsyncTimer::new(Duration::from_millis(100)),
        AsyncTimer::new(Duration::from_millis(200)),
        AsyncTimer::new(Duration::from_millis(300)),
    );
    println!("并发定时器完成: {:?}", start.elapsed());  // ~300ms
}

Context 的扩展 ​

rust
use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};

// Context 目前主要就是封装 Waker
// 未来可能会扩展更多功能(如 LocalWaker 等)

// 从 Context 获取 Waker 的方式
struct ShowContext;

impl Future for ShowContext {
    type Output = ();

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
        // 获取 Waker 的引用
        let waker_ref = cx.waker();
        println!("获取了 Waker 引用");

        // 克隆 Waker(用于存储或传递到其他线程)
        let _waker_clone = waker_ref.clone();
        println!("克隆了 Waker");

        // Waker 实现了 Send + Sync,可以跨线程
        // let _: Box<dyn Send> = Box::new(waker_ref.clone());

        Poll::Ready(())
    }
}

#[tokio::main]
async fn main() {
    ShowContext.await;
}

基本示例 ​

用 Context 和 Waker 实现一个异步通知机制:

rust
use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll, Waker};
use std::sync::{Arc, Mutex};
use std::thread;
use std::time::Duration;

// 异步通知:一个线程设置值,另一个线程异步等待
struct AsyncNotify<T> {
    inner: Arc<Mutex<NotifyInner<T>>>,
}

struct NotifyInner<T> {
    value: Option<T>,
    waker: Option<Waker>,
}

// 发送端
struct NotifySender<T> {
    inner: Arc<Mutex<NotifyInner<T>>>,
}

impl<T> AsyncNotify<T> {
    fn new() -> (NotifySender<T>, AsyncNotify<T>) {
        let inner = Arc::new(Mutex::new(NotifyInner {
            value: None,
            waker: None,
        }));

        let sender = NotifySender {
            inner: Arc::clone(&inner),
        };
        let receiver = AsyncNotify { inner };

        (sender, receiver)
    }
}

impl<T: Send> NotifySender<T> {
    fn notify(self, value: T) {
        let mut inner = self.inner.lock().unwrap();
        inner.value = Some(value);

        // 唤醒等待的 Future
        if let Some(waker) = inner.waker.take() {
            waker.wake();
        }
    }
}

impl<T> Future for AsyncNotify<T> {
    type Output = T;

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<T> {
        let mut inner = self.inner.lock().unwrap();

        if let Some(value) = inner.value.take() {
            Poll::Ready(value)
        } else {
            // 保存 Waker,等待通知
            inner.waker = Some(cx.waker().clone());
            Poll::Pending
        }
    }
}

#[tokio::main]
async fn main() {
    // 基本用法
    println!("=== 基本通知 ===");
    let (sender, receiver) = AsyncNotify::<String>::new();

    // 在另一个线程中发送通知
    thread::spawn(move || {
        thread::sleep(Duration::from_millis(200));
        println!("  发送通知");
        sender.notify("Hello from another thread!".to_string());
    });

    println!("等待通知...");
    let msg = receiver.await;
    println!("收到: {}\n", msg);

    // 多个通知并发等待
    println!("=== 并发通知 ===");
    let mut receivers = Vec::new();

    for i in 0..3 {
        let (sender, receiver) = AsyncNotify::<String>::new();
        receivers.push(receiver);

        let delay = 100 * (i as u64 + 1);
        thread::spawn(move || {
            thread::sleep(Duration::from_millis(delay));
            sender.notify(format!("通知{} (延迟{}ms)", i, delay));
        });
    }

    // 用 join_all 并发等待所有通知
    let results = futures::future::join_all(receivers).await;
    for result in &results {
        println!("  {}", result);
    }

    // 数值计算通知
    println!("\n=== 计算通知 ===");
    let (sender, receiver) = AsyncNotify::<f64>::new();

    thread::spawn(move || {
        // 在后台线程做 CPU 密集型计算
        let result: f64 = (1..=1000000)
            .map(|i| 1.0 / (i as f64 * i as f64))
            .sum();
        sender.notify(result);
    });

    let pi_squared_over_6 = receiver.await;
    println!("  计算结果: {:.10}", pi_squared_over_6);
    println!("  π²/6 ≈ {:.10}", std::f64::consts::PI.powi(2) / 6.0);
}

常见问题 ​

问题一:如果忘记调用 Waker 会怎样?

Future 会永远处于 Pending 状态,不会再被 poll,任务就"卡住"了。这不会导致编译错误或 panic,而是一种逻辑错误(类似死锁),很难调试。

问题二:Waker 可以被多次调用吗?

可以。多次调用 wake 是安全的,运行时会处理重复唤醒。但不必要的唤醒会导致 Future 被多余地 poll,浪费 CPU。

问题三:Waker 是怎么创建的?

Waker 由异步运行时(如 tokio)在 poll Future 时创建并通过 Context 传递给 Future。开发者不需要手动创建 Waker,只需要从 Context 中获取并在需要时调用。

问题四:为什么需要检查 will_wake?

任务可能在不同的执行器线程上被 poll,每次 poll 传入的 Waker 可能不同。如果存储了旧的 Waker,新的 poll 可能带来了新的 Waker。will_wake 检查两个 Waker 是否指向同一个任务,避免不必要的 clone。

适用场景 ​

  • 自定义异步原语:定时器、通知、事件等
  • 跨线程唤醒:后台线程完成工作后唤醒异步任务
  • IO 事件集成:将操作系统的 IO 事件连接到 Future
  • 运行时开发:实现自定义的异步运行时

注意事项 ​

  • 返回 Pending 前必须确保 Waker 会被调用
  • Waker 实现了 Clone + Send + Sync,可以跨线程
  • wake() 消耗 Waker,wake_by_ref() 借用 Waker
  • 每次 poll 可能传入不同的 Waker,需要更新存储的 Waker
  • 多次 wake 是安全的,但会导致多余的 poll
  • Context 目前主要就是封装 Waker

总结 ​

Context 是 Future::poll 的参数,携带一个 Waker。Waker 是异步运行时与 Future 之间的唤醒机制:Future 返回 Pending 时保存 Waker,当外部事件发生(IO 就绪、定时器到期等)时调用 Waker 通知运行时重新 poll。wake() 消耗 Waker,wake_by_ref() 借用 Waker。Waker 实现了 Clone + Send + Sync,可以被传递到其他线程。忘记调用 Waker 会导致 Future 永远沉睡。每次 poll 可能传入不同的 Waker,需要用 will_wake() 检查是否需要更新。开发者通常通过 async/await 使用异步功能,不直接接触 Waker,但在实现自定义异步原语时必须正确处理 Waker。