Trait core::stream::Stream[−][src]

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>) { ... }
}
🔬 This is a nightly-only experimental API. (async_stream #79024)
Expand description

用于处理异步迭代器的接口。

这是主流 trait。 有关一般的流概念的更多信息，请参见 模块级文档。 特别是，您可能想知道如何 实现 Stream。

Associated Types

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

流产生的项的类型。

Required methods

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

尝试拉出该流的下一个值，如果该值尚不可用，则注册当前任务以进行唤醒，如果流已用尽，则返回 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

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

返回流剩余长度上的边界。

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

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

实现说明

流实现不会产生声明数量的元素，这不是强制性的。buggy 流产生的值可能小于元素的下限，也可能大于元素的上限。

size_hint() 主要用于优化，例如为流的元素保留空间，但不能被信任，例如省略不安全代码中的边界检查。 size_hint() 的不正确实现不应导致违反内存安全性。

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

默认实现返回了 (0, None)，这对于任何流都是正确的。

Implementors