Module core::async_iter

source ·
🔬This is a nightly-only experimental API. (async_iterator #79024)
Expand description

可组合的异步迭代。

如果您发现自己使用某种异步集合,并且需要对所述集合的元素执行操作,您将很快遇到异步迭代器。 异步迭代器在惯用的异步 Rust 代码中大量使用,因此熟悉它们是值得的。

在解释更多内容之前,让我们讨论一下该模块的结构:

Organization

该模块主要是按类型来组织的:

  • Traits 是核心部分:这些 traits 定义了存在什么样的异步迭代器以及您可以用它们做什么。这些 traits 的方法值得投入一些额外的学习时间。
  • 函数提供了一些有用的方法来创建一些基本的异步迭代器。
  • 结构体通常是该模块的 traits 上各种方法的返回类型。通常,您将需要查看创建 struct 的方法,而不是 struct 本身。 有关原因的更多详细信息,请参见 实现异步迭代器

就是这样! 让我们深入研究异步迭代器。

异步迭代器

这个模块的核心和灵魂是 AsyncIterator trait。AsyncIterator 的核心是这样的:

trait AsyncIterator {
    type Item;
    fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>;
}
Run

Iterator 不同,AsyncIterator 区分了实现 AsyncIterator 时使用的 poll_next 方法和使用异步迭代器时使用的 (to-be-implemented) next 方法。

AsyncIterator 的消费者只需要考虑 next,它在调用时会返回一个 future,它产生 Option<AsyncIterator::Item>

只要有元素,next 返回的 future 就会产生 Some(Item),一旦所有元素用完,就会产生 None 来指示迭代已完成。 如果我们正在等待异步解决问题,future 将等待异步迭代器再次准备好再次 yield。

单个异步迭代器可能会选择恢复迭代,因此再次调用 next 最终可能会或可能不会最终在某个时候再次产生 Some(Item)

AsyncIterator 的完整定义还包括许多其他方法,但它们是默认方法,建立在 poll_next 之上,因此您可以免费获得它们。

实现异步迭代器

创建自己的异步迭代器涉及两个步骤:创建一个 struct 来保存异步迭代器的状态,然后为该 struct 实现 AsyncIterator

让我们创建一个名为 Counter 的异步迭代器,它从 1 计数到 5:

#![feature(async_iterator)]

// 首先,结构体:

/// 一个从 1 计数到 5 的异步迭代器
struct Counter {
    count: usize,
}

// 我们希望计数从一开始,所以让我们添加一个 new() 方法来提供帮助。
// 这不是严格必要的,但很方便。
// 请注意,我们将 `count` 从零开始,我们将在下面的 `poll_next () ` 的实现中看到其原因。
impl Counter {
    fn new() -> Counter {
        Counter { count: 0 }
    }
}

// 然后,我们为我们的 `Counter` 实现 `AsyncIterator`:

impl AsyncIterator for Counter {
    // 我们将使用 usize 进行计数
    type Item = usize;

    // poll_next() 是唯一需要的方法
    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
        // 增加我们的数量。这就是为什么我们从零开始。
        self.count += 1;

        // 检查我们是否已经完成计数。
        if self.count < 6 {
            Poll::Ready(Some(self.count))
        } else {
            Poll::Ready(None)
        }
    }
}
Run

Laziness

异步迭代器是惰性的。这意味着仅仅创建一个异步迭代器并不能做很多事情。在您调用 poll_next 之前,什么都不会发生。 当创建一个异步迭代器仅仅为了它的副作用时,这有时是一个混乱的根源。 编译器将警告我们这种行为:

warning: unused result that must be used: async iterators do nothing unless polled

Structs

  • FromIterExperimental
    从迭代器创建的异步迭代器。

Traits

Functions

  • from_iterExperimental
    将迭代器转换为异步迭代器。