|
1 | 1 | //! Composable asynchronous iteration. |
2 | 2 | //! |
3 | | -//! If futures are asynchronous values, then streams are asynchronous |
4 | | -//! iterators. If you've found yourself with an asynchronous collection of some kind, |
| 3 | +//! If you've found yourself with an asynchronous collection of some kind, |
5 | 4 | //! and needed to perform an operation on the elements of said collection, |
6 | | -//! you'll quickly run into 'streams'. Streams are heavily used in idiomatic |
7 | | -//! asynchronous Rust code, so it's worth becoming familiar with them. |
| 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 | 7 | //! |
9 | 8 | //! Before explaining more, let's talk about how this module is structured: |
10 | 9 | //! |
11 | 10 | //! # Organization |
12 | 11 | //! |
13 | 12 | //! This module is largely organized by type: |
14 | 13 | //! |
15 | | -//! * [Traits] are the core portion: these traits define what kind of streams |
| 14 | +//! * [Traits] are the core portion: these traits define what kind of async iterators |
16 | 15 | //! exist and what you can do with them. The methods of these traits are worth |
17 | 16 | //! putting some extra study time into. |
18 | | -//! * Functions provide some helpful ways to create some basic streams. |
| 17 | +//! * Functions provide some helpful ways to create some basic async iterators. |
19 | 18 | //! * Structs are often the return types of the various methods on this |
20 | 19 | //! module's traits. You'll usually want to look at the method that creates |
21 | 20 | //! the `struct`, rather than the `struct` itself. For more detail about why, |
22 | | -//! see '[Implementing Stream](#implementing-stream)'. |
| 21 | +//! see '[Implementing Async Iterator](#implementing-async-iterator)'. |
23 | 22 | //! |
24 | 23 | //! [Traits]: #traits |
25 | 24 | //! |
26 | | -//! That's it! Let's dig into streams. |
| 25 | +//! That's it! Let's dig into async iterators. |
27 | 26 | //! |
28 | | -//! # Stream |
| 27 | +//! # Async Iterators |
29 | 28 | //! |
30 | | -//! The heart and soul of this module is the [`Stream`] trait. The core of |
31 | | -//! [`Stream`] looks like this: |
| 29 | +//! The heart and soul of this module is the [`AsyncIterator`] trait. The core of |
| 30 | +//! [`AsyncIterator`] looks like this: |
32 | 31 | //! |
33 | 32 | //! ``` |
34 | 33 | //! # use core::task::{Context, Poll}; |
35 | 34 | //! # use core::pin::Pin; |
36 | | -//! trait Stream { |
| 35 | +//! trait AsyncIterator { |
37 | 36 | //! type Item; |
38 | 37 | //! fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>; |
39 | 38 | //! } |
40 | 39 | //! ``` |
41 | 40 | //! |
42 | | -//! Unlike `Iterator`, `Stream` makes a distinction between the [`poll_next`] |
43 | | -//! method which is used when implementing a `Stream`, and a (to-be-implemented) |
44 | | -//! `next` method which is used when consuming a stream. Consumers of `Stream` |
| 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` |
45 | 44 | //! only need to consider `next`, which when called, returns a future which |
46 | | -//! yields `Option<Stream::Item>`. |
| 45 | +//! yields `Option<AsyncIterator::Item>`. |
47 | 46 | //! |
48 | 47 | //! The future returned by `next` will yield `Some(Item)` as long as there are |
49 | 48 | //! elements, and once they've all been exhausted, will yield `None` to indicate |
50 | 49 | //! that iteration is finished. If we're waiting on something asynchronous to |
51 | | -//! resolve, the future will wait until the stream is ready to yield again. |
| 50 | +//! resolve, the future will wait until the async iterator is ready to yield again. |
52 | 51 | //! |
53 | | -//! Individual streams may choose to resume iteration, and so calling `next` |
| 52 | +//! Individual async iterators may choose to resume iteration, and so calling `next` |
54 | 53 | //! again may or may not eventually yield `Some(Item)` again at some point. |
55 | 54 | //! |
56 | | -//! [`Stream`]'s full definition includes a number of other methods as well, |
| 55 | +//! [`AsyncIterator`]'s full definition includes a number of other methods as well, |
57 | 56 | //! but they are default methods, built on top of [`poll_next`], and so you get |
58 | 57 | //! them for free. |
59 | 58 | //! |
60 | 59 | //! [`Poll`]: super::task::Poll |
61 | | -//! [`poll_next`]: Stream::poll_next |
| 60 | +//! [`poll_next`]: AsyncIterator::poll_next |
62 | 61 | //! |
63 | | -//! # Implementing Stream |
| 62 | +//! # Implementing Async Iterator |
64 | 63 | //! |
65 | | -//! Creating a stream of your own involves two steps: creating a `struct` to |
66 | | -//! hold the stream's state, and then implementing [`Stream`] for that |
| 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 |
67 | 66 | //! `struct`. |
68 | 67 | //! |
69 | | -//! Let's make a stream named `Counter` which counts from `1` to `5`: |
| 68 | +//! Let's make an async iterator named `Counter` which counts from `1` to `5`: |
70 | 69 | //! |
71 | 70 | //! ```no_run |
72 | | -//! #![feature(async_stream)] |
73 | | -//! # use core::stream::Stream; |
| 71 | +//! #![feature(async_iterator)] |
| 72 | +//! # use core::async_iter::AsyncIterator; |
74 | 73 | //! # use core::task::{Context, Poll}; |
75 | 74 | //! # use core::pin::Pin; |
76 | 75 | //! |
77 | 76 | //! // First, the struct: |
78 | 77 | //! |
79 | | -//! /// A stream which counts from one to five |
| 78 | +//! /// An async iterator which counts from one to five |
80 | 79 | //! struct Counter { |
81 | 80 | //! count: usize, |
82 | 81 | //! } |
|
90 | 89 | //! } |
91 | 90 | //! } |
92 | 91 | //! |
93 | | -//! // Then, we implement `Stream` for our `Counter`: |
| 92 | +//! // Then, we implement `AsyncIterator` for our `Counter`: |
94 | 93 | //! |
95 | | -//! impl Stream for Counter { |
| 94 | +//! impl AsyncIterator for Counter { |
96 | 95 | //! // we will be counting with usize |
97 | 96 | //! type Item = usize; |
98 | 97 | //! |
|
113 | 112 | //! |
114 | 113 | //! # Laziness |
115 | 114 | //! |
116 | | -//! Streams are *lazy*. This means that just creating a stream doesn't _do_ a |
117 | | -//! whole lot. Nothing really happens until you call `poll_next`. This is |
118 | | -//! sometimes a source of confusion when creating a stream solely for its side |
| 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 |
119 | 118 | //! effects. The compiler will warn us about this kind of behavior: |
120 | 119 | //! |
121 | 120 | //! ```text |
122 | | -//! warning: unused result that must be used: streams do nothing unless polled |
| 121 | +//! warning: unused result that must be used: async iterators do nothing unless polled |
123 | 122 | //! ``` |
124 | 123 |
|
| 124 | +mod async_iter; |
125 | 125 | mod from_iter; |
126 | | -mod stream; |
127 | 126 |
|
| 127 | +pub use async_iter::AsyncIterator; |
128 | 128 | pub use from_iter::{from_iter, FromIter}; |
129 | | -pub use stream::Stream; |
0 commit comments