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>) { ... }
}
async_iterator
#79024)Expand description
用于处理异步迭代器的 trait。
这是主要的异步迭代器 trait。
更多关于异步迭代器的概念,请参见 模块级文档。
特别是,您可能想知道如何 实现 AsyncIterator
。
Required Associated Types§
Required Methods§
sourcefn poll_next(
self: Pin<&mut Self>,
cx: &mut Context<'_>
) -> Poll<Option<Self::Item>>
fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Option<Self::Item>>
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§
sourcefn size_hint(&self) -> (usize, Option<usize>)
fn size_hint(&self) -> (usize, Option<usize>)
async_iterator
#79024)返回异步迭代器剩余长度的界限。
具体来说,size_hint()
返回一个元组,其中第一个元素是下界,第二个元素是上界。
返回的元组的后半部分是 Option<usize>
。
这里的 None
表示没有已知的上限,或者该上限大于 usize
。
实现说明
异步迭代器实现产生声明的元素数量并不是强制性的。 有缺陷的异步迭代器产生的结果可能小于元素的下限或大于元素的上限。
size_hint()
主要用于优化,例如为异步迭代器的元素保留空间,但不能信任它,例如在不安全的代码中省略边界检查。
size_hint()
的不正确实现不应导致违反内存安全性。
也就是说,该实现应提供正确的估计,因为否则将违反 trait 的协议。
默认实现返回 (0, None)
,这对于任何异步迭代器都是正确的。