Module async_iter

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

Composable asynchronous iteration.

If you’ve found yourself with an asynchronous collection of some kind, and needed to perform an operation on the elements of said collection, you’ll quickly run into ‘async iterators’. Async Iterators are heavily used in idiomatic asynchronous Rust code, so it’s worth becoming familiar with them.

Before explaining more, let’s talk about how this module is structured:

Organization

This module is largely organized by type:

• Traits are the core portion: these traits define what kind of async iterators exist and what you can do with them. The methods of these traits are worth putting some extra study time into.
• Functions provide some helpful ways to create some basic async iterators.
• Structs are often the return types of the various methods on this module’s traits. You’ll usually want to look at the method that creates the struct, rather than the struct itself. For more detail about why, see ‘Implementing Async Iterator’.

That’s it! Let’s dig into async iterators.

Async Iterators

The heart and soul of this module is the AsyncIterator trait. The core of AsyncIterator looks like this:

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

Unlike Iterator, AsyncIterator makes a distinction between the poll_next method which is used when implementing an AsyncIterator, and a (to-be-implemented) next method which is used when consuming an async iterator. Consumers of AsyncIterator only need to consider next, which when called, returns a future which yields Option<AsyncIterator::Item>.

The future returned by next will yield Some(Item) as long as there are elements, and once they’ve all been exhausted, will yield None to indicate that iteration is finished. If we’re waiting on something asynchronous to resolve, the future will wait until the async iterator is ready to yield again.

Individual async iterators may choose to resume iteration, and so calling next again may or may not eventually yield Some(Item) again at some point.

AsyncIterator’s full definition includes a number of other methods as well, but they are default methods, built on top of poll_next, and so you get them for free.

Implementing Async Iterator

Creating an async iterator of your own involves two steps: creating a struct to hold the async iterator’s state,