Poll 枚举
核心概念
Poll<T> 是 Future::poll 方法的返回值类型,定义在 std::task 模块中。它只有两个变体:Poll::Ready(T) 表示异步操作已完成,结果值为 T;Poll::Pending 表示异步操作尚未完成,需要稍后再次轮询。Poll 的设计非常简洁,是 Rust 异步模型"拉取"(pull-based)机制的核心——运行时反复 poll 一个 Future,直到它返回 Ready。这和回调模型(push-based)不同,拉取模型让编译器可以将 Future 编译为高效的状态机。
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 的方法
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 实现中的使用
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 宏
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 的交互
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 实现一个异步重试逻辑:
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后按约定不应再 pollmap方法可以转换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,但理解它对掌握异步原理很关键。