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 #[doc(alias = "Stream")]
  16 pub trait AsyncIterator {
  17     /// The type of items yielded by the async iterator.
  18     type Item;
  19
  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.
  23     ///
  24     /// # Return value
  25     ///
  26     /// There are several possible return values, each indicating a distinct
  27     /// async iterator state:
  28     ///
  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.
  32     ///
  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.
  36     ///
  37     /// - `Poll::Ready(None)` means that the async iterator has terminated, and
  38     /// `poll_next` should not be invoked again.
  39     ///
  40     /// # Panics
  41     ///
  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>>;
  50
  51     /// Returns the bounds on the remaining length of the async iterator.
  52     ///
  53     /// Specifically, `size_hint()` returns a tuple where the first element
  54     /// is the lower bound, and the second element is the upper bound.
  55     ///
  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`].
  59     ///
  60     /// # Implementation notes
  61     ///
  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.
  65     ///
  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
  70     /// violations.
  71     ///
  72     /// That said, the implementation should provide a correct estimation,
  73     /// because otherwise it would be a violation of the trait's protocol.
  74     ///
  75     /// The default implementation returns <code>(0, [None])</code> which is correct for any
  76     /// async iterator.
  77     #[inline]
  78     fn size_hint(&self) -> (usize, Option<usize>) {
  79         (0, None)
  80     }
  81 }
  82
  83 #[unstable(feature = "async_iterator", issue = "79024")]
  84 impl<S: ?Sized + AsyncIterator + Unpin> AsyncIterator for &mut S {
  85     type Item = S::Item;
  86
  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)
  89     }
  90
  91     fn size_hint(&self) -> (usize, Option<usize>) {
  92         (**self).size_hint()
  93     }
  94 }
  95
  96 #[unstable(feature = "async_iterator", issue = "79024")]
  97 impl<P> AsyncIterator for Pin<P>
  98 where
  99     P: DerefMut,
 100     P::Target: AsyncIterator,
 101 {
 102     type Item = <P::Target as AsyncIterator>::Item;
 103
 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)
 106     }
 107
 108     fn size_hint(&self) -> (usize, Option<usize>) {
 109         (**self).size_hint()
 110     }
 111 }