1use super::assert_future;
2use core::marker;
3use core::pin::Pin;
4use futures_core::future::{FusedFuture, Future};
5use futures_core::task::{Context, Poll};
6
7/// Future for the [`pending()`] function.
8#[derive(Debug)]
9#[must_use = "futures do nothing unless you `.await` or poll them"]
10pub struct Pending<T> {
11 _data: marker::PhantomData<T>,
12}
13
14impl<T> FusedFuture for Pending<T> {
15 fn is_terminated(&self) -> bool {
16 true
17 }
18}
19
20/// Creates a future which never resolves, representing a computation that never
21/// finishes.
22///
23/// The returned future will forever return [`Poll::Pending`].
24///
25/// # Examples
26///
27/// ```ignore
28/// # futures::executor::block_on(async {
29/// use futures::future;
30///
31/// let future = future::pending();
32/// let () = future.await;
33/// unreachable!();
34/// # });
35/// ```
36#[cfg_attr(docsrs, doc(alias = "never"))]
37pub fn pending<T>() -> Pending<T> {
38 assert_future::<T, _>(Pending { _data: marker::PhantomData })
39}
40
41impl<T> Future for Pending<T> {
42 type Output = T;
43
44 fn poll(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<T> {
45 Poll::Pending
46 }
47}
48
49impl<T> Unpin for Pending<T> {}
50
51impl<T> Clone for Pending<T> {
52 fn clone(&self) -> Self {
53 pending()
54 }
55}
56