1 //! Composable asynchronous iteration.
3 //! If you've found yourself with an asynchronous collection of some kind,
4 //! and needed to perform an operation on the elements of said collection,
5 //! you'll quickly run into 'async iterators'. Async Iterators are heavily used in
6 //! idiomatic asynchronous Rust code, so it's worth becoming familiar with them.
8 //! Before explaining more, let's talk about how this module is structured:
12 //! This module is largely organized by type:
14 //! * [Traits] are the core portion: these traits define what kind of async iterators
15 //! exist and what you can do with them. The methods of these traits are worth
16 //! putting some extra study time into.
17 //! * Functions provide some helpful ways to create some basic async iterators.
18 //! * Structs are often the return types of the various methods on this
19 //! module's traits. You'll usually want to look at the method that creates
20 //! the `struct`, rather than the `struct` itself. For more detail about why,
21 //! see '[Implementing Async Iterator](#implementing-async-iterator)'.
25 //! That's it! Let's dig into async iterators.
29 //! The heart and soul of this module is the [`AsyncIterator`] trait. The core of
30 //! [`AsyncIterator`] looks like this:
33 //! # use core::task::{Context, Poll};
34 //! # use core::pin::Pin;
35 //! trait AsyncIterator {
37 //! fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>;
41 //! Unlike `Iterator`, `AsyncIterator` makes a distinction between the [`poll_next`]
42 //! method which is used when implementing an `AsyncIterator`, and a (to-be-implemented)
43 //! `next` method which is used when consuming an async iterator. Consumers of `AsyncIterator`
44 //! only need to consider `next`, which when called, returns a future which
45 //! yields `Option<AsyncIterator::Item>`.
47 //! The future returned by `next` will yield `Some(Item)` as long as there are
48 //! elements, and once they've all been exhausted, will yield `None` to indicate
49 //! that iteration is finished. If we're waiting on something asynchronous to
50 //! resolve, the future will wait until the async iterator is ready to yield again.
52 //! Individual async iterators may choose to resume iteration, and so calling `next`
53 //! again may or may not eventually yield `Some(Item)` again at some point.
55 //! [`AsyncIterator`]'s full definition includes a number of other methods as well,
56 //! but they are default methods, built on top of [`poll_next`], and so you get
59 //! [`Poll`]: super::task::Poll
60 //! [`poll_next`]: AsyncIterator::poll_next
62 //! # Implementing Async Iterator
64 //! Creating an async iterator of your own involves two steps: creating a `struct` to
65 //! hold the async iterator's state, and then implementing [`AsyncIterator`] for that
68 //! Let's make an async iterator named `Counter` which counts from `1` to `5`:
71 //! #![feature(async_iterator)]
72 //! # use core::async_iter::AsyncIterator;
73 //! # use core::task::{Context, Poll};
74 //! # use core::pin::Pin;
76 //! // First, the struct:
78 //! /// An async iterator which counts from one to five
83 //! // we want our count to start at one, so let's add a new() method to help.
84 //! // This isn't strictly necessary, but is convenient. Note that we start
85 //! // `count` at zero, we'll see why in `poll_next()`'s implementation below.
87 //! fn new() -> Counter {
88 //! Counter { count: 0 }
92 //! // Then, we implement `AsyncIterator` for our `Counter`:
94 //! impl AsyncIterator for Counter {
95 //! // we will be counting with usize
96 //! type Item = usize;
98 //! // poll_next() is the only required method
99 //! fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
100 //! // Increment our count. This is why we started at zero.
103 //! // Check to see if we've finished counting or not.
104 //! if self.count < 6 {
105 //! Poll::Ready(Some(self.count))
107 //! Poll::Ready(None)
115 //! Async iterators are *lazy*. This means that just creating an async iterator doesn't
116 //! _do_ a whole lot. Nothing really happens until you call `poll_next`. This is
117 //! sometimes a source of confusion when creating an async iterator solely for its side
118 //! effects. The compiler will warn us about this kind of behavior:
121 //! warning: unused result that must be used: async iterators do nothing unless polled
127 pub use async_iter::AsyncIterator;
128 pub use from_iter::{from_iter, FromIter};