library/core/src/async_iter/async_iter.rs

   1 use crate::ops::DerefMut;
   2 use crate::pin::Pin;
   3 use crate::task::{Context, Poll};
   4
   5 /// An interface for dealing with asynchronous iterators.
   6 ///
   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].
  10 ///
  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 pub trait AsyncIterator {
  16     /// The type of items yielded by the async iterator.
  17     type Item;
  18
  19     /// Attempt to pull out the next value of this async iterator, registering the
  20     /// current task for wakeup if the value is not yet available, and returning
  21     /// `None` if the async iterator is exhausted.
  22     ///
  23     /// # Return value
  24     ///
  25     /// There are several possible return values, each indicating a distinct
  26     /// async iterator state:
  27     ///
  28     /// - `Poll::Pending` means that this async iterator's next value is not ready
  29     /// yet. Implementations will ensure that the current task will be notified
  30     /// when the next value may be ready.
  31     ///
  32     /// - `Poll::Ready(Some(val))` means that the async iterator has successfully
  33     /// produced a value, `val`, and may produce further values on subsequent
  34     /// `poll_next` calls.
  35     ///
  36     /// - `Poll::Ready(None)` means that the async iterator has terminated, and
  37     /// `poll_next` should not be invoked again.
  38     ///
  39     /// # Panics
  40     ///
  41     /// Once an async iterator has finished (returned `Ready(None)` from `poll_next`), calling its
  42     /// `poll_next` method again may panic, block forever, or cause other kinds of
  43     /// problems; the `AsyncIterator` trait places no requirements on the effects of
  44     /// such a call. However, as the `poll_next` method is not marked `unsafe`,
  45     /// Rust's usual rules apply: calls must never cause undefined behavior
  46     /// (memory corruption, incorrect use of `unsafe` functions, or the like),
  47     /// regardless of the async iterator's state.
  48     fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>;
  49
  50     /// Returns the bounds on the remaining length of the async iterator.
  51     ///
  52     /// Specifically, `size_hint()` returns a tuple where the first element
  53     /// is the lower bound, and the second element is the upper bound.
  54     ///
  55     /// The second half of the tuple that is returned is an <code>[Option]<[usize]></code>.
  56     /// A [`None`] here means that either there is no known upper bound, or the
  57     /// upper bound is larger than [`usize`].
  58     ///
  59     /// # Implementation notes
  60     ///
  61     /// It is not enforced that an async iterator implementation yields the declared
  62     /// number of elements. A buggy async iterator may yield less than the lower bound
  63     /// or more than the upper bound of elements.
  64     ///
  65     /// `size_hint()` is primarily intended to be used for optimizations such as
  66     /// reserving space for the elements of the async iterator, but must not be
  67     /// trusted to e.g., omit bounds checks in unsafe code. An incorrect
  68     /// implementation of `size_hint()` should not lead to memory safety
  69     /// violations.
  70     ///
  71     /// That said, the implementation should provide a correct estimation,
  72     /// because otherwise it would be a violation of the trait's protocol.
  73     ///
  74     /// The default implementation returns <code>(0, [None])</code> which is correct for any
  75     /// async iterator.
  76     #[inline]
  77     fn size_hint(&self) -> (usize, Option<usize>) {
  78         (0, None)
  79     }
  80 }
  81
  82 #[unstable(feature = "async_iterator", issue = "79024")]
  83 impl<S: ?Sized + AsyncIterator + Unpin> AsyncIterator for &mut S {
  84     type Item = S::Item;
  85
  86     fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
  87         S::poll_next(Pin::new(&mut **self), cx)
  88     }
  89
  90     fn size_hint(&self) -> (usize, Option<usize>) {
  91         (**self).size_hint()
  92     }
  93 }
  94
  95 #[unstable(feature = "async_iterator", issue = "79024")]
  96 impl<P> AsyncIterator for Pin<P>
  97 where
  98     P: DerefMut,
  99     P::Target: AsyncIterator,
 100 {
 101     type Item = <P::Target as AsyncIterator>::Item;
 102
 103     fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
 104         <P::Target as AsyncIterator>::poll_next(self.as_deref_mut(), cx)
 105     }
 106
 107     fn size_hint(&self) -> (usize, Option<usize>) {
 108         (**self).size_hint()
 109     }
 110 }