1 use crate::ops::DerefMut;
3 use crate::task::{Context, Poll};
5 /// A trait for dealing with asynchronous iterators.
7 /// This is the main async iterator trait. For more about the concept of async iterators
8 /// generally, please see the [module-level documentation]. In particular, you
9 /// may want to know how to [implement `AsyncIterator`][impl].
11 /// [module-level documentation]: index.html
12 /// [impl]: index.html#implementing-async-iterator
13 #[unstable(feature = "async_iterator", issue = "79024")]
14 #[must_use = "async iterators do nothing unless polled"]
15 #[doc(alias = "Stream")]
16 pub trait AsyncIterator {
17 /// The type of items yielded by the async iterator.
20 /// Attempt to pull out the next value of this async iterator, registering the
21 /// current task for wakeup if the value is not yet available, and returning
22 /// `None` if the async iterator is exhausted.
26 /// There are several possible return values, each indicating a distinct
27 /// async iterator state:
29 /// - `Poll::Pending` means that this async iterator's next value is not ready
30 /// yet. Implementations will ensure that the current task will be notified
31 /// when the next value may be ready.
33 /// - `Poll::Ready(Some(val))` means that the async iterator has successfully
34 /// produced a value, `val`, and may produce further values on subsequent
35 /// `poll_next` calls.
37 /// - `Poll::Ready(None)` means that the async iterator has terminated, and
38 /// `poll_next` should not be invoked again.
42 /// Once an async iterator has finished (returned `Ready(None)` from `poll_next`), calling its
43 /// `poll_next` method again may panic, block forever, or cause other kinds of
44 /// problems; the `AsyncIterator` trait places no requirements on the effects of
45 /// such a call. However, as the `poll_next` method is not marked `unsafe`,
46 /// Rust's usual rules apply: calls must never cause undefined behavior
47 /// (memory corruption, incorrect use of `unsafe` functions, or the like),
48 /// regardless of the async iterator's state.
49 fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>;
51 /// Returns the bounds on the remaining length of the async iterator.
53 /// Specifically, `size_hint()` returns a tuple where the first element
54 /// is the lower bound, and the second element is the upper bound.
56 /// The second half of the tuple that is returned is an <code>[Option]<[usize]></code>.
57 /// A [`None`] here means that either there is no known upper bound, or the
58 /// upper bound is larger than [`usize`].
60 /// # Implementation notes
62 /// It is not enforced that an async iterator implementation yields the declared
63 /// number of elements. A buggy async iterator may yield less than the lower bound
64 /// or more than the upper bound of elements.
66 /// `size_hint()` is primarily intended to be used for optimizations such as
67 /// reserving space for the elements of the async iterator, but must not be
68 /// trusted to e.g., omit bounds checks in unsafe code. An incorrect
69 /// implementation of `size_hint()` should not lead to memory safety
72 /// That said, the implementation should provide a correct estimation,
73 /// because otherwise it would be a violation of the trait's protocol.
75 /// The default implementation returns <code>(0, [None])</code> which is correct for any
78 fn size_hint(&self) -> (usize, Option<usize>) {
83 #[unstable(feature = "async_iterator", issue = "79024")]
84 impl<S: ?Sized + AsyncIterator + Unpin> AsyncIterator for &mut S {
87 fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
88 S::poll_next(Pin::new(&mut **self), cx)
91 fn size_hint(&self) -> (usize, Option<usize>) {
96 #[unstable(feature = "async_iterator", issue = "79024")]
97 impl<P> AsyncIterator for Pin<P>
100 P::Target: AsyncIterator,
102 type Item = <P::Target as AsyncIterator>::Item;
104 fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
105 <P::Target as AsyncIterator>::poll_next(self.as_deref_mut(), cx)
108 fn size_hint(&self) -> (usize, Option<usize>) {