1use super::assert_future;
2use core::pin::Pin;
3use futures_core::future::{FusedFuture, Future};
4use futures_core::task::{Context, Poll};
5
6/// Future for the [`always_ready`](always_ready()) function.
7#[must_use = "futures do nothing unless you `.await` or poll them"]
8pub struct AlwaysReady<T, F: Fn() -> T>(F);
9
10impl<T, F: Fn() -> T> core::fmt::Debug for AlwaysReady<T, F> {
11 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
12 f.debug_tuple(name:"AlwaysReady").finish()
13 }
14}
15
16impl<T, F: Fn() -> T + Clone> Clone for AlwaysReady<T, F> {
17 fn clone(&self) -> Self {
18 Self(self.0.clone())
19 }
20}
21
22impl<T, F: Fn() -> T + Copy> Copy for AlwaysReady<T, F> {}
23
24impl<T, F: Fn() -> T> Unpin for AlwaysReady<T, F> {}
25
26impl<T, F: Fn() -> T> FusedFuture for AlwaysReady<T, F> {
27 fn is_terminated(&self) -> bool {
28 false
29 }
30}
31
32impl<T, F: Fn() -> T> Future for AlwaysReady<T, F> {
33 type Output = T;
34
35 #[inline]
36 fn poll(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<T> {
37 Poll::Ready(self.0())
38 }
39}
40
41/// Creates a future that is always immediately ready with a value.
42///
43/// This is particularly useful in avoiding a heap allocation when an API needs [`Box<dyn Future<Output = T>>`],
44/// as [`AlwaysReady`] does not have to store a boolean for `is_finished`.
45///
46/// # Examples
47///
48/// ```
49/// # futures::executor::block_on(async {
50/// use std::mem::size_of_val;
51///
52/// use futures::future;
53///
54/// let a = future::always_ready(|| 1);
55/// assert_eq!(size_of_val(&a), 0);
56/// assert_eq!(a.await, 1);
57/// assert_eq!(a.await, 1);
58/// # });
59/// ```
60pub fn always_ready<T, F: Fn() -> T>(prod: F) -> AlwaysReady<T, F> {
61 assert_future::<T, _>(AlwaysReady(prod))
62}
63