Trait core::async_iter::AsyncIterator

source · 
pub trait AsyncIterator {
    type Item;

    // Required method
    fn poll_next(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>
    ) -> Poll<Option<Self::Item>>;

    // Provided method
    fn size_hint(&self) -> (usize, Option<usize>) { ... }
}
🔬This is a nightly-only experimental API. (async_iterator #79024)
Expand description

用于处理异步迭代器的 trait。

这是主要的异步迭代器 trait。 更多关于异步迭代器的概念，请参见 模块级文档。 特别是，您可能想知道如何 实现 AsyncIterator。

Required Associated Types§

source

type Item

🔬This is a nightly-only experimental API. (async_iterator #79024)

异步迭代器产生的项的类型。

Required Methods§

source

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Option<Self::Item>>

🔬This is a nightly-only experimental API. (async_iterator #79024)

尝试提取此异步迭代器的下一个值，如果该值尚不可用，则注册当前任务以进行唤醒，如果异步迭代器耗尽，则返回 None。

返回值

有几个可能的返回值，每个表示不同的异步迭代器状态:

  • Poll::Pending 表示这个异步迭代器的下一个值还没有准备好。实现将确保在准备好下一个值时将通知当前任务。

  • Poll::Ready(Some(val)) 表示异步迭代器已成功生成值 val，并且可能会在后续 poll_next 调用中生成更多值。

  • Poll::Ready(None) 表示异步迭代器已终止，不应再次调用 poll_next。

Panics

一旦异步迭代器完成 (从 poll_next 返回 Ready(None))，再次调用它的 poll_next 方法可能会出现 panic、永久阻塞或导致其他类型的问题; AsyncIterator trait 对调用的效果没有要求。

然而，由于 poll_next 方法没有标记为 unsafe，所以 Rust 的通常规则适用：无论异步迭代器的状态如何，调用都不能导致未定义的行为 (内存损坏、错误使用 unsafe 函数等)。

Provided Methods§

source

fn size_hint(&self) -> (usize, Option<usize>)

🔬This is a nightly-only experimental API. (async_iterator #79024)

返回异步迭代器剩余长度的界限。

具体来说，size_hint() 返回一个元组，其中第一个元素是下界，第二个元素是上界。

返回的元组的后半部分是 Option<usize>。 这里的 None 表示没有已知的上限，或者该上限大于 usize。

实现说明

异步迭代器实现产生声明的元素数量并不是强制性的。 有缺陷的异步迭代器产生的结果可能小于元素的下限或大于元素的上限。

size_hint() 主要用于优化，例如为异步迭代器的元素保留空间，但不能信任它，例如在不安全的代码中省略边界检查。

size_hint() 的不正确实现不应导致违反内存安全性。

也就是说，该实现应提供正确的估计，因为否则将违反 trait 的协议。

默认实现返回 (0, None)，这对于任何异步迭代器都是正确的。

Implementors§