Trait std::stream::Stream [−][src]
#[must_use = "streams do nothing unless polled"]
pub trait Stream {
type Item;
fn poll_next(
self: Pin<&mut Self>,
cx: &mut Context<'_>
) -> Poll<Option<Self::Item>>;
fn size_hint(&self) -> (usize, Option<usize>) { ... }
}Expand description
用于处理异步迭代器的接口。
这是主流 trait。
有关一般的流概念的更多信息，请参见 module-level documentation。
特别是，您可能想知道如何 implement Stream。
Associated Types
Required methods
尝试拉出该流的下一个值，如果该值尚不可用，则注册当前任务以进行唤醒，如果流已用尽，则返回 None。
返回值
有几个可能的返回值，每个返回值指示不同的流状态:
-
Poll::Pending表示该流的下一个值尚未准备好。实现将确保在准备好下一个值时将通知当前任务。 -
Poll::Ready(Some(val))表示流已成功产生值val，并可能在随后的poll_next调用中产生进一步的值。 -
Poll::Ready(None)表示流已终止，并且不应再次调用poll_next。
Panics
流完成后 (从 poll_next 返回 Ready(None))，再次调用其 poll_next 方法可能会 panic，永远阻塞或引起其他类型的问题。Stream trait 对这种调用的效果没有任何要求。
但是，由于 poll_next 方法未标记为 unsafe，因此适用 Rust 的通常规则: 调用决不能引起未定义的行为 (内存损坏，对 unsafe 函数的错误使用等)，而与流的状态无关。
Provided methods
返回流剩余长度上的边界。
具体来说，size_hint() 返回一个元组，其中第一个元素是下界，第二个元素是上界。
返回的元组的后半部分是 Option<usize>。
这里的 None 表示没有已知的上限，或者该上限大于 usize。
实现说明
流实现不会产生声明数量的元素，这不是强制性的。buggy 流产生的值可能小于元素的下限，也可能大于元素的上限。
size_hint() 主要用于优化，例如为流的元素保留空间，但不得信任，例如可以省略不安全代码中的边界检查。
size_hint() 的不正确实现不应导致违反内存安全性。
也就是说，该实现应提供正确的估计，因为否则将违反 trait 的协议。
默认实现返回 (0，None) 对任何流都是正确的。