Poll 枚举 ​

核心概念 ​

Poll<T> 是 Future::poll 方法的返回值类型,定义在 std::task 模块中。它只有两个变体:Poll::Ready(T) 表示异步操作已完成,结果值为 T;Poll::Pending 表示异步操作尚未完成,需要稍后再次轮询。Poll 的设计非常简洁,是 Rust 异步模型"拉取"(pull-based)机制的核心——运行时反复 poll 一个 Future,直到它返回 Ready。这和回调模型(push-based)不同,拉取模型让编译器可以将 Future 编译为高效的状态机。

rust
use std::task::Poll;

fn main() {
    // Poll 枚举的定义:
    // pub enum Poll<T> {
    //     Ready(T),   // 操作完成,携带结果值
    //     Pending,    // 操作未完成,稍后再 poll
    // }

    // 创建 Poll 值
    let done: Poll<i32> = Poll::Ready(42);
    let not_done: Poll<i32> = Poll::Pending;

    // 检查状态
    println!("done.is_ready(): {}", done.is_ready());     // true
    println!("done.is_pending(): {}", done.is_pending()); // false
    println!("not_done.is_ready(): {}", not_done.is_ready());     // false
    println!("not_done.is_pending(): {}", not_done.is_pending()); // true

    // 模式匹配
    match done {
        Poll::Ready(val) => println!("完成: {}", val),
        Poll::Pending => println!("未完成"),
    }
}

Poll 的方法 ​

rust
use std::task::Poll;

fn main() {
    // map:转换 Ready 中的值
    let poll: Poll<i32> = Poll::Ready(10);
    let mapped: Poll<String> = poll.map(|v| format!("值={}", v));
    println!("map: {:?}", mapped);  // Ready("值=10")

    let pending: Poll<i32> = Poll::Pending;
    let mapped: Poll<String> = pending.map(|v| format!("值={}", v));
    println!("map Pending: {:?}", mapped);  // Pending(map 不影响 Pending)

    // is_ready / is_pending
    let ready = Poll::Ready("完成");
    let pending: Poll<&str> = Poll::Pending;
    println!("ready.is_ready(): {}", ready.is_ready());
    println!("pending.is_pending(): {}", pending.is_pending());

    // Poll<Result<T, E>> 的特殊方法
    let ok_poll: Poll<Result<i32, String>> = Poll::Ready(Ok(42));
    let err_poll: Poll<Result<i32, String>> = Poll::Ready(Err("错误".to_string()));
    let pending_poll: Poll<Result<i32, String>> = Poll::Pending;

    // map_ok:只转换 Ready(Ok(T)) 中的值
    println!("map_ok: {:?}", ok_poll.map_ok(|v| v * 2));    // Ready(Ok(84))
    println!("map_ok err: {:?}", err_poll.map_ok(|v| v * 2)); // Ready(Err("错误"))

    // map_err:只转换 Ready(Err(E)) 中的错误
    println!("map_err: {:?}", err_poll.map_err(|e| format!("包装: {}", e)));
}

Poll 在 Future 实现中的使用 ​

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

// 一个在第 N 次 poll 后才完成的 Future
struct PollCounter {
    target: u32,    // 需要 poll 多少次才完成
    current: u32,   // 已经被 poll 了多少次
}

impl PollCounter {
    fn new(target: u32) -> Self {
        PollCounter { target, current: 0 }
    }
}

impl Future for PollCounter {
    type Output = u32;

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<u32> {
        self.current += 1;
        println!("  第 {} 次 poll (目标: {})", self.current, self.target);

        if self.current >= self.target {
            // 达到目标次数,返回 Ready
            Poll::Ready(self.current)
        } else {
            // 还没到,通知运行时稍后再 poll
            cx.waker().wake_by_ref();
            Poll::Pending
        }
    }
}

// 状态机 Future:模拟多步操作
enum MultiStepState {
    Step1,
    Step2(String),
    Step3(String, i32),
    Done,
}

struct MultiStepFuture {
    state: MultiStepState,
}

impl MultiStepFuture {
    fn new() -> Self {
        MultiStepFuture { state: MultiStepState::Step1 }
    }
}

impl Future for MultiStepFuture {
    type Output = String;

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<String> {
        match &self.state {
            MultiStepState::Step1 => {
                println!("  步骤1: 初始化");
                self.state = MultiStepState::Step2("数据".to_string());
                cx.waker().wake_by_ref();
                Poll::Pending
            }
            MultiStepState::Step2(data) => {
                println!("  步骤2: 处理 '{}'", data);
                let data = data.clone();
                self.state = MultiStepState::Step3(data, 42);
                cx.waker().wake_by_ref();
                Poll::Pending
            }
            MultiStepState::Step3(data, number) => {
                println!("  步骤3: 完成");
                let result = format!("{}={}", data, number);
                self.state = MultiStepState::Done;
                Poll::Ready(result)
            }
            MultiStepState::Done => {
                panic!("已完成的 Future 不应该再被 poll");
            }
        }
    }
}

#[tokio::main]
async fn main() {
    println!("=== PollCounter ===");
    let result = PollCounter::new(3).await;
    println!("经过 {} 次 poll 完成\n", result);

    println!("=== MultiStepFuture ===");
    let result = MultiStepFuture::new().await;
    println!("结果: {}", result);
}

Poll 与 Ready 宏 ​

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

// ready! 宏简化了 poll 中的模式匹配
// 标准库中没有 ready! 宏,但 futures crate 和很多运行时提供了
// 从 Rust 1.64 开始,可以用 std::task::ready!

struct CombinedFuture {
    inner: Pin<Box<dyn Future<Output = i32>>>,
    multiplier: i32,
}

impl Future for CombinedFuture {
    type Output = i32;

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<i32> {
        // 手动写法:
        // match self.inner.as_mut().poll(cx) {
        //     Poll::Ready(val) => Poll::Ready(val * self.multiplier),
        //     Poll::Pending => Poll::Pending,
        // }

        // 用 ready! 宏简化(Rust 1.64+):
        let val = std::task::ready!(self.inner.as_mut().poll(cx));
        Poll::Ready(val * self.multiplier)

        // ready! 宏展开后等价于:
        // 如果是 Pending,立即 return Poll::Pending
        // 如果是 Ready(val),解包出 val 继续执行
    }
}

#[tokio::main]
async fn main() {
    let future = CombinedFuture {
        inner: Box::pin(async { 21 }),
        multiplier: 2,
    };
    let result = future.await;
    println!("结果: {}", result);  // 42
}

Poll 与 Option、Result 的交互 ​

rust
use std::task::Poll;

fn main() {
    // Poll<Option<T>>:常见于 Stream trait
    let poll_some: Poll<Option<i32>> = Poll::Ready(Some(42));
    let poll_none: Poll<Option<i32>> = Poll::Ready(None);
    let poll_pending: Poll<Option<i32>> = Poll::Pending;

    println!("{:?}", poll_some);     // Ready(Some(42))
    println!("{:?}", poll_none);     // Ready(None)
    println!("{:?}", poll_pending);  // Pending

    // 在 Stream 中的含义:
    // Ready(Some(item)) → 有一个新元素
    // Ready(None)       → 流结束
    // Pending           → 暂时没有元素

    // Poll<Result<T, E>>:常见于 IO 操作
    let poll_ok: Poll<Result<String, std::io::Error>> =
        Poll::Ready(Ok("数据".to_string()));
    let poll_err: Poll<Result<String, std::io::Error>> =
        Poll::Ready(Err(std::io::Error::new(
            std::io::ErrorKind::NotFound, "未找到"
        )));

    // 在异步 IO 中的含义:
    // Ready(Ok(data))  → IO 完成,得到数据
    // Ready(Err(e))    → IO 完成,发生错误
    // Pending          → IO 尚未完成

    match poll_ok {
        Poll::Ready(Ok(data)) => println!("数据: {}", data),
        Poll::Ready(Err(e)) => println!("错误: {}", e),
        Poll::Pending => println!("等待中"),
    }
}

基本示例 ​

用 Poll 实现一个异步重试逻辑:

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

// 带重试的 Future:如果内部操作失败就重试
struct RetryFuture<F, Fut>
where
    F: Fn() -> Fut,
    Fut: Future<Output = Result<String, String>>,
{
    factory: F,                       // 创建新 Future 的工厂函数
    current: Option<Pin<Box<Fut>>>,   // 当前正在执行的 Future
    max_retries: u32,
    attempts: u32,
}

impl<F, Fut> RetryFuture<F, Fut>
where
    F: Fn() -> Fut,
    Fut: Future<Output = Result<String, String>>,
{
    fn new(factory: F, max_retries: u32) -> Self {
        RetryFuture {
            factory,
            current: None,
            max_retries,
            attempts: 0,
        }
    }
}

impl<F, Fut> Future for RetryFuture<F, Fut>
where
    F: Fn() -> Fut + Unpin,
    Fut: Future<Output = Result<String, String>>,
{
    type Output = Result<String, String>;

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        loop {
            // 如果没有正在执行的 Future,创建一个
            if self.current.is_none() {
                self.attempts += 1;
                println!("  第 {} 次尝试", self.attempts);
                let fut = (self.factory)();
                self.current = Some(Box::pin(fut));
            }

            // poll 当前的 Future
            let result = self.current.as_mut().unwrap().as_mut().poll(cx);

            match result {
                Poll::Ready(Ok(val)) => {
                    // 成功
                    return Poll::Ready(Ok(val));
                }
                Poll::Ready(Err(e)) => {
                    // 失败,检查是否还能重试
                    if self.attempts >= self.max_retries {
                        return Poll::Ready(Err(format!(
                            "{}次重试后失败: {}", self.attempts, e
                        )));
                    }
                    // 重置 current,下次 poll 会创建新的
                    self.current = None;
                    cx.waker().wake_by_ref();
                    return Poll::Pending;
                }
                Poll::Pending => {
                    return Poll::Pending;
                }
            }
        }
    }
}

// 模拟一个有时会失败的操作
use std::sync::atomic::{AtomicU32, Ordering};
static CALL_COUNT: AtomicU32 = AtomicU32::new(0);

async fn flaky_operation() -> Result<String, String> {
    let count = CALL_COUNT.fetch_add(1, Ordering::SeqCst);
    if count < 2 {
        Err(format!("第{}次调用失败", count + 1))
    } else {
        Ok("操作成功!".to_string())
    }
}

#[tokio::main]
async fn main() {
    println!("=== 重试逻辑 ===");
    CALL_COUNT.store(0, Ordering::SeqCst);

    let result = RetryFuture::new(flaky_operation, 5).await;
    println!("最终结果: {:?}\n", result);

    // 测试超过重试次数
    println!("=== 超过重试次数 ===");
    CALL_COUNT.store(0, Ordering::SeqCst);

    let always_fail = || async {
        Err::<String, String>("始终失败".to_string())
    };

    let result = RetryFuture::new(always_fail, 3).await;
    println!("最终结果: {:?}\n", result);

    // Poll 状态转换图示
    println!("=== Poll 状态转换 ===");
    println!("  创建 Future → poll()");
    println!("  poll() → Pending  (未完成,稍后再 poll)");
    println!("  poll() → Ready(T) (完成,返回结果)");
    println!("  Ready 后不应再 poll");
}

常见问题 ​

问题一:返回 Pending 后一定会被再次 poll 吗?

只有在 Waker 被调用后运行时才会再次 poll 这个 Future。如果返回 Pending 但没有安排 Waker 被调用,Future 就会永远沉睡。这就是为什么返回 Pending 前必须确保 Waker 会在某个时刻被触发。

问题二:Ready 之后还会被 poll 吗?

按照约定,Future 返回 Ready 后不应该再被 poll。但这不是强制的——标准库的 FusedFuture trait 可以标记一个 Future 在完成后再次 poll 时总是返回 Pending。

问题三:Poll 和 Option 有什么区别?

Option<T> 表示值的存在与否。Poll<T> 表示异步操作的完成状态。语义不同:None 表示"没有值",Pending 表示"还没完成,稍后再问"。

问题四:ready! 宏有什么用?

ready! 简化了在 poll 实现中对内部 Future 的 poll 处理。let val = ready!(inner.poll(cx)) 如果内部返回 Pending,自动 return Poll::Pending;如果返回 Ready(val),解包出 val 继续执行。

适用场景 ​

  • 自定义 Future 实现:手动实现 Future::poll 的返回值
  • 异步状态机:通过 Poll 控制状态转换
  • Stream 实现:Poll<Option<T>> 表示流的下一个元素
  • 底层异步 IO:Poll<Result<T, E>> 表示 IO 操作状态

注意事项 ​

  • Poll::Ready(T) 表示完成,Poll::Pending 表示未完成
  • 返回 Pending 前必须确保 Waker 会被调用
  • Ready 后按约定不应再 poll
  • map 方法可以转换 Ready 中的值,Pending 不受影响
  • ready! 宏(Rust 1.64+)简化 poll 中的嵌套处理
  • 不要在 poll 中做阻塞操作

总结 ​

Poll<T> 是 Future::poll 的返回类型,有两个变体:Ready(T) 表示异步操作完成并携带结果值,Pending 表示操作尚未完成。运行时通过反复调用 poll 来驱动 Future 直到返回 Ready。返回 Pending 前必须确保 Waker 会在未来某个时刻被调用,否则 Future 会永远沉睡。Poll 提供了 map、is_ready、is_pending 等方法。ready! 宏可以简化在 poll 实现中处理内部 Future 的模式匹配。在 Stream 中使用 Poll<Option<T>>,在异步 IO 中使用 Poll<Result<T, E>>。开发者通常通过 async/await 使用 Future,不直接接触 Poll,但理解它对掌握异步原理很关键。