1 use super::assert_future;
2 use core::pin::Pin;
3 use futures_core::task::{Context, Poll};
4 use futures_core::{FusedFuture, Future, Stream};
5 use pin_project_lite::pin_project;
6
7 pin_project! {
8 /// Future for the [`poll_immediate`](poll_immediate()) function.
9 ///
10 /// It will never return [Poll::Pending](core::task::Poll::Pending)
11 #[derive(Debug, Clone)]
12 #[must_use = "futures do nothing unless you `.await` or poll them"]
13 pub struct PollImmediate<T> {
14 #[pin]
15 future: Option<T>
16 }
17 }
18
19 impl<T, F> Future for PollImmediate<F>
20 where
21 F: Future<Output = T>,
22 {
23 type Output = Option<T>;
24
25 #[inline]
poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<T>>26 fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<T>> {
27 let mut this = self.project();
28 let inner =
29 this.future.as_mut().as_pin_mut().expect("PollImmediate polled after completion");
30 match inner.poll(cx) {
31 Poll::Ready(t) => {
32 this.future.set(None);
33 Poll::Ready(Some(t))
34 }
35 Poll::Pending => Poll::Ready(None),
36 }
37 }
38 }
39
40 impl<T: Future> FusedFuture for PollImmediate<T> {
is_terminated(&self) -> bool41 fn is_terminated(&self) -> bool {
42 self.future.is_none()
43 }
44 }
45
46 /// A [Stream](crate::stream::Stream) implementation that can be polled repeatedly until the future is done.
47 /// The stream will never return [Poll::Pending](core::task::Poll::Pending)
48 /// so polling it in a tight loop is worse than using a blocking synchronous function.
49 /// ```
50 /// # futures::executor::block_on(async {
51 /// use futures::task::Poll;
52 /// use futures::{StreamExt, future, pin_mut};
53 /// use future::FusedFuture;
54 ///
55 /// let f = async { 1_u32 };
56 /// pin_mut!(f);
57 /// let mut r = future::poll_immediate(f);
58 /// assert_eq!(r.next().await, Some(Poll::Ready(1)));
59 ///
60 /// let f = async {futures::pending!(); 42_u8};
61 /// pin_mut!(f);
62 /// let mut p = future::poll_immediate(f);
63 /// assert_eq!(p.next().await, Some(Poll::Pending));
64 /// assert!(!p.is_terminated());
65 /// assert_eq!(p.next().await, Some(Poll::Ready(42)));
66 /// assert!(p.is_terminated());
67 /// assert_eq!(p.next().await, None);
68 /// # });
69 /// ```
70 impl<T, F> Stream for PollImmediate<F>
71 where
72 F: Future<Output = T>,
73 {
74 type Item = Poll<T>;
75
poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>76 fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
77 let mut this = self.project();
78 match this.future.as_mut().as_pin_mut() {
79 // inner is gone, so we can signal that the stream is closed.
80 None => Poll::Ready(None),
81 Some(fut) => Poll::Ready(Some(fut.poll(cx).map(|t| {
82 this.future.set(None);
83 t
84 }))),
85 }
86 }
87 }
88
89 /// Creates a future that is immediately ready with an Option of a value.
90 /// Specifically this means that [poll](core::future::Future::poll()) always returns [Poll::Ready](core::task::Poll::Ready).
91 ///
92 /// # Caution
93 ///
94 /// When consuming the future by this function, note the following:
95 ///
96 /// - This function does not guarantee that the future will run to completion, so it is generally incompatible with passing the non-cancellation-safe future by value.
97 /// - Even if the future is cancellation-safe, creating and dropping new futures frequently may lead to performance problems.
98 ///
99 /// # Examples
100 ///
101 /// ```
102 /// # futures::executor::block_on(async {
103 /// use futures::future;
104 ///
105 /// let r = future::poll_immediate(async { 1_u32 });
106 /// assert_eq!(r.await, Some(1));
107 ///
108 /// let p = future::poll_immediate(future::pending::<i32>());
109 /// assert_eq!(p.await, None);
110 /// # });
111 /// ```
112 ///
113 /// ### Reusing a future
114 ///
115 /// ```
116 /// # futures::executor::block_on(async {
117 /// use futures::{future, pin_mut};
118 /// let f = async {futures::pending!(); 42_u8};
119 /// pin_mut!(f);
120 /// assert_eq!(None, future::poll_immediate(&mut f).await);
121 /// assert_eq!(42, f.await);
122 /// # });
123 /// ```
poll_immediate<F: Future>(f: F) -> PollImmediate<F>124 pub fn poll_immediate<F: Future>(f: F) -> PollImmediate<F> {
125 assert_future::<Option<F::Output>, PollImmediate<F>>(PollImmediate { future: Some(f) })
126 }
127