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 ] |
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> { |
41 | 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 | |
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 | /// ``` |
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 | |