futures_core/stream/
mod.rs

1//! Asynchronous streams.
2
3use Poll;
4use task;
5
6/// A stream of values produced asynchronously.
7///
8/// If `Future` is an asynchronous version of `Result`, then `Stream` is an
9/// asynchronous version of `Iterator`. A stream represents a sequence of
10/// value-producing events that occur asynchronously to the caller.
11///
12/// The trait is modeled after `Future`, but allows `poll_next` to be called
13/// even after a value has been produced, yielding `None` once the stream has
14/// been fully exhausted.
15///
16/// # Errors
17///
18/// Streams, like futures, also bake in errors through an associated `Error`
19/// type. An error on a stream **does not terminate the stream**. That is,
20/// after one error is received, another value may be received from the same
21/// stream (it's valid to keep polling). Thus a stream is somewhat like an
22/// `Iterator<Item = Result<T, E>>`, and is always terminated by returning
23/// `None`.
24pub trait Stream {
25    /// Values yielded by the stream.
26    type Item;
27
28    /// Errors yielded by the stream.
29    type Error;
30
31    /// Attempt to pull out the next value of this stream, registering the
32    /// current task for wakeup if the value is not yet available, and returning
33    /// `None` if the stream is exhausted.
34    ///
35    /// # Return value
36    ///
37    /// There are several possible return values, each indicating a distinct
38    /// stream state:
39    ///
40    /// - [`Ok(Pending)`](::Async) means that this stream's next value is not
41    /// ready yet. Implementations will ensure that the current task will be
42    /// notified when the next value may be ready.
43    ///
44    /// - [`Ok(Ready(Some(val)))`](::Async) means that the stream has
45    /// successfully produced a value, `val`, and may produce further values
46    /// on subsequent `poll_next` calls.
47    ///
48    /// - [`Ok(Ready(None))`](::Async) means that the stream has terminated, and
49    /// `poll_next` should not be invoked again.
50    ///
51    /// - `Err(err)` means that the stream encountered an error while trying to
52    /// `poll_next`. Subsequent calls to `poll_next` *are* allowed, and may
53    /// return further values or errors.
54    ///
55    /// # Panics
56    ///
57    /// Once a stream is finished, i.e. `Ready(None)` has been returned, further
58    /// calls to `poll_next` may result in a panic or other "bad behavior".  If this
59    /// is difficult to guard against then the `fuse` adapter can be used to
60    /// ensure that `poll_next` always returns `Ready(None)` in subsequent calls.
61    fn poll_next(&mut self, cx: &mut task::Context) -> Poll<Option<Self::Item>, Self::Error>;
62}
63
64impl<'a, S: ?Sized + Stream> Stream for &'a mut S {
65    type Item = S::Item;
66    type Error = S::Error;
67
68    fn poll_next(&mut self, cx: &mut task::Context) -> Poll<Option<Self::Item>, Self::Error> {
69        (**self).poll_next(cx)
70    }
71}
72
73if_std! {
74    use Async;
75    use never::Never;
76
77    impl<S: ?Sized + Stream> Stream for ::std::boxed::Box<S> {
78        type Item = S::Item;
79        type Error = S::Error;
80
81        fn poll_next(&mut self, cx: &mut task::Context) -> Poll<Option<Self::Item>, Self::Error> {
82            (**self).poll_next(cx)
83        }
84    }
85
86    #[cfg(feature = "nightly")]
87    impl<S: ?Sized + Stream> Stream for ::std::boxed::PinBox<S> {
88        type Item = S::Item;
89        type Error = S::Error;
90
91        fn poll_next(&mut self, cx: &mut task::Context) -> Poll<Option<Self::Item>, Self::Error> {
92            unsafe { ::core::mem::PinMut::get_mut_unchecked(self.as_pin_mut()).poll_next(cx) }
93        }
94    }
95
96    impl<S: Stream> Stream for ::std::panic::AssertUnwindSafe<S> {
97        type Item = S::Item;
98        type Error = S::Error;
99
100        fn poll_next(&mut self, cx: &mut task::Context) -> Poll<Option<S::Item>, S::Error> {
101            self.0.poll_next(cx)
102        }
103    }
104
105    impl<T> Stream for ::std::collections::VecDeque<T> {
106        type Item = T;
107        type Error = Never;
108
109        fn poll_next(&mut self, _cx: &mut task::Context) -> Poll<Option<Self::Item>, Self::Error> {
110            Ok(Async::Ready(self.pop_front()))
111        }
112    }
113}
futures_core/stream/mod.rs

futures_core/stream/
mod.rs
