library/core/src/future/pending.rs

   1 use crate::fmt::{self, Debug};
   2 use crate::future::Future;
   3 use crate::marker;
   4 use crate::pin::Pin;
   5 use crate::task::{Context, Poll};
   6
   7 /// Creates a future which never resolves, representing a computation that never
   8 /// finishes.
   9 ///
  10 /// This `struct` is created by [`pending()`]. See its
  11 /// documentation for more.
  12 #[stable(feature = "future_readiness_fns", since = "1.48.0")]
  13 #[must_use = "futures do nothing unless you `.await` or poll them"]
  14 pub struct Pending<T> {
  15     _data: marker::PhantomData<T>,
  16 }
  17
  18 /// Creates a future which never resolves, representing a computation that never
  19 /// finishes.
  20 ///
  21 /// # Examples
  22 ///
  23 /// ```no_run
  24 /// use core::future;
  25 ///
  26 /// # async fn run() {
  27 /// let future = future::pending();
  28 /// let () = future.await;
  29 /// unreachable!();
  30 /// # }
  31 /// ```
  32 #[stable(feature = "future_readiness_fns", since = "1.48.0")]
  33 pub fn pending<T>() -> Pending<T> {
  34     Pending { _data: marker::PhantomData }
  35 }
  36
  37 #[stable(feature = "future_readiness_fns", since = "1.48.0")]
  38 impl<T> Future for Pending<T> {
  39     type Output = T;
  40
  41     fn poll(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<T> {
  42         Poll::Pending
  43     }
  44 }
  45
  46 #[stable(feature = "future_readiness_fns", since = "1.48.0")]
  47 impl<T> Unpin for Pending<T> {}
  48
  49 #[stable(feature = "future_readiness_fns", since = "1.48.0")]
  50 impl<T> Debug for Pending<T> {
  51     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  52         f.debug_struct("Pending").finish()
  53     }
  54 }
  55
  56 #[stable(feature = "future_readiness_fns", since = "1.48.0")]
  57 impl<T> Clone for Pending<T> {
  58     fn clone(&self) -> Self {
  59         pending()
  60     }
  61 }