async_iter.rs - source
Skip to main content core/async_iter/ async_iter.rs 1 use crate ::ops::DerefMut ; 2 use crate ::pin::Pin ; 3 use crate ::task::{ Context , Poll }; 4 5 /// A trait 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 #[lang = "async_iterator" ] 17 pub trait AsyncIterator { 18 /// The type of items yielded by the async iterator. 19 type Item; 20 21 /// Attempts to pull out the next value of this async iterator, registering the 22 /// current task for wakeup if the value is not yet available, and returning 23 /// `None` if the async iterator is exhausted.
24 /// 25 /// # Return value 26 /// 27 /// There are several possible return values, each indicating a distinct 28 /// async iterator state: 29 /// 30 /// - `Poll::Pending` means that this async iterator's next value is not ready 31 /// yet. Implementations will ensure that the current task will be notified 32 /// when the next value may be ready. 33 /// 34 /// - `Poll::Ready(Some(val))` means that the async iterator has successfully 35 /// produced a value, `val`, and may produce further values on subsequent 36 /// `poll_next` calls.
37 /// 38 /// - `Poll::Ready(None)` means that the async iterator has terminated, and 39 /// `poll_next` should not be invoked again. 40 /// 41 /// # Panics 42 /// 43 /// Once an async iterator has finished (returned `Ready(None)` from `poll_next`), calling its 44 /// `poll_next` method again may panic, block forever, or cause other kinds of 45 /// problems; the `AsyncIterator` trait places no requirements on the effects of 46 /// such a call.
However, as the `poll_next` method is not marked `unsafe`, 47 /// Rust's usual rules apply: calls must never cause undefined behavior 48 /// (memory corruption, incorrect use of `unsafe` functions, or the like), 49 /// regardless of the async iterator's state. 50 #[lang = "async_iterator_poll_next" ] 51 fn poll_next( self : Pin < &mut Self >, cx: &mut Context < '_ >) -> Poll < Option < Self ::Item>>; 52 53 /// Returns the bounds on the remaining length of the async iterator.
54 /// 55 /// Specifically, `size_hint()` returns a tuple where the first element 56 /// is the lower bound, and the second element is the upper bound. 57 /// 58 /// The second half of the tuple that is returned is an <code>[Option]<[usize]></code>. 59 /// A [`None`] here means that either there is no known upper bound, or the 60 /// upper bound is larger than [`usize`]. 61 /// 62 /// # Implementation notes 63 /// 64 /// It is not enforced that an async iterator implementation yields the declared 65 /// number of elements.
A buggy async iterator may yield less than the lower bound 66 /// or more than the upper bound of elements. 67 /// 68 /// `size_hint()` is primarily intended to be used for optimizations such as 69 /// reserving space for the elements of the async iterator, but must not be 70 /// trusted to e.g., omit bounds checks in unsafe code. An incorrect 71 /// implementation of `size_hint()` should not lead to memory safety 72 /// violations.
73 /// 74 /// That said, the implementation should provide a correct estimation, 75 /// because otherwise it would be a violation of the trait's protocol. 76 /// 77 /// The default implementation returns <code>(0, [None])</code> which is correct for any 78 /// async iterator. 79 #[inline] 80 fn size_hint( & self ) -> ( usize , Option < usize >) { 81 ( 0 , None ) 82 } 83 } 84 85 #[unstable(feature = "async_iterator" , issue = "79024" )] 86 impl <S: ?
Sized + AsyncIterator + Unpin > AsyncIterator for &mut S { 87 type Item = S::Item; 88 89 fn poll_next( mut self : Pin < &mut Self >, cx: &mut Context < '_ >) -> Poll < Option < Self ::Item>> { 90 S:: poll_next ( Pin :: new ( &mut ** self ), cx ) 91 } 92 93 fn size_hint( & self ) -> ( usize , Option < usize >) { 94 ( ** self ). size_hint () 95 } 96 } 97 98 #[unstable(feature = "async_iterator" , issue = "79024" )] 99 impl <P> AsyncIterator for Pin <P> 100 where 101 P: DerefMut , 102 P::Target: AsyncIterator , 103 { 104 type Item = <P::Target as AsyncIterator>:: Item ; 105 106 fn poll_next( self : Pin < &mut Self >, cx: &mut Context < '_ >) -> Poll < Option < Self ::Item>> { 107 <P::Target as AsyncIterator>:: poll_next ( self . as_deref_mut (), cx ) 108 } 109 110 fn size_hint( & self ) -> ( usize , Option < usize >) { 111 ( ** self ). size_hint () 112 } 113 } 114 115 #[unstable(feature = "async_gen_internals" , issue = "none" )] 116 impl <T> Poll < Option <T>> { 117 /// A helper function for internal desugaring -- produces `Ready(Some(t))`, 118 /// which corresponds to the async iterator yielding a value.
119 #[doc(hidden)] 120 #[unstable(feature = "async_gen_internals" , issue = "none" )] 121 #[lang = "AsyncGenReady" ] 122 pub fn async_gen_ready(t: T) -> Self { 123 Poll:: Ready ( Some ( t )) 124 } 125 126 /// A helper constant for internal desugaring -- produces `Pending`, 127 /// which corresponds to the async iterator pending on an `.await`. 128 #[doc(hidden)] 129 #[unstable(feature = "async_gen_internals" , issue = "none" )] 130 #[lang = "AsyncGenPending" ] 131 // FIXME(gen_blocks): This probably could be deduplicated.
132 pub const PENDING: Self = Poll:: Pending ; 133 134 /// A helper constant for internal desugaring -- produces `Ready(None)`, 135 /// which corresponds to the async iterator finishing its iteration. 136 #[doc(hidden)] 137 #[unstable(feature = "async_gen_internals" , issue = "none" )] 138 #[lang = "AsyncGenFinished" ] 139 pub const FINISHED: Self = Poll:: Ready ( None ); 140 } 141 142 /// Converts something into an async iterator 143 #[unstable(feature = "async_iterator" , issue = "79024" )] 144 #[rustc_diagnostic_item = "IntoAsyncIterator" ] 145 pub trait IntoAsyncIterator { 146 /// The type of the item yielded by the iterator 147 type Item; 148 /// The type of the resulting iterator 149 type IntoAsyncIter: AsyncIterator <Item = Self ::Item>; 150 151 /// Converts `self` into an async iterator 152 #[lang = "into_async_iter_into_iter" ] 153 fn into_async_iter( self ) -> Self ::IntoAsyncIter; 154 } 155 156 #[unstable(feature = "async_iterator" , issue = "79024" )] 157 impl <I: AsyncIterator > IntoAsyncIterator for I { 158 type Item = I::Item; 159 type IntoAsyncIter = I; 160 161 fn into_async_iter( self ) -> Self ::IntoAsyncIter { 162 self 163 } 164 }