library/core/src/future/ready.rs

   1 use crate::future::Future;
   2 use crate::pin::Pin;
   3 use crate::task::{Context, Poll};
   4
   5 /// A future that is immediately ready with a value.
   6 ///
   7 /// This `struct` is created by [`ready()`]. See its
   8 /// documentation for more.
   9 #[stable(feature = "future_readiness_fns", since = "1.48.0")]
  10 #[derive(Debug, Clone)]
  11 #[must_use = "futures do nothing unless you `.await` or poll them"]
  12 pub struct Ready<T>(Option<T>);
  13
  14 #[stable(feature = "future_readiness_fns", since = "1.48.0")]
  15 impl<T> Unpin for Ready<T> {}
  16
  17 #[stable(feature = "future_readiness_fns", since = "1.48.0")]
  18 impl<T> Future for Ready<T> {
  19     type Output = T;
  20
  21     #[inline]
  22     fn poll(mut self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<T> {
  23         Poll::Ready(self.0.take().expect("`Ready` polled after completion"))
  24     }
  25 }
  26
  27 impl<T> Ready<T> {
  28     /// Consumes the `Ready`, returning the wrapped value.
  29     ///
  30     /// # Panics
  31     ///
  32     /// Will panic if this [`Ready`] was already polled to completion.
  33     ///
  34     /// # Examples
  35     ///
  36     /// ```
  37     /// #![feature(ready_into_inner)]
  38     /// use std::future;
  39     ///
  40     /// let a = future::ready(1);
  41     /// assert_eq!(a.into_inner(), 1);
  42     /// ```
  43     #[unstable(feature = "ready_into_inner", issue = "101196")]
  44     #[must_use]
  45     #[inline]
  46     pub fn into_inner(self) -> T {
  47         self.0.expect("Called `into_inner()` on `Ready` after completion")
  48     }
  49 }
  50
  51 /// Creates a future that is immediately ready with a value.
  52 ///
  53 /// Futures created through this function are functionally similar to those
  54 /// created through `async {}`. The main difference is that futures created
  55 /// through this function are named and implement `Unpin`.
  56 ///
  57 /// # Examples
  58 ///
  59 /// ```
  60 /// use std::future;
  61 ///
  62 /// # async fn run() {
  63 /// let a = future::ready(1);
  64 /// assert_eq!(a.await, 1);
  65 /// # }
  66 /// ```
  67 #[stable(feature = "future_readiness_fns", since = "1.48.0")]
  68 pub fn ready<T>(t: T) -> Ready<T> {
  69     Ready(Some(t))
  70 }