library/core/src/task/ready.rs

   1 use core::convert;
   2 use core::fmt;
   3 use core::ops::{ControlFlow, FromResidual, Try};
   4 use core::task::Poll;
   5
   6 /// Extracts the successful type of a [`Poll<T>`].
   7 ///
   8 /// This macro bakes in propagation of [`Pending`] signals by returning early.
   9 ///
  10 /// [`Poll<T>`]: crate::task::Poll
  11 /// [`Pending`]: crate::task::Poll::Pending
  12 ///
  13 /// # Examples
  14 ///
  15 /// ```
  16 /// #![feature(ready_macro)]
  17 ///
  18 /// use std::task::{ready, Context, Poll};
  19 /// use std::future::{self, Future};
  20 /// use std::pin::Pin;
  21 ///
  22 /// pub fn do_poll(cx: &mut Context<'_>) -> Poll<()> {
  23 ///     let mut fut = future::ready(42);
  24 ///     let fut = Pin::new(&mut fut);
  25 ///
  26 ///     let num = ready!(fut.poll(cx));
  27 ///     # drop(num);
  28 ///     // ... use num
  29 ///
  30 ///     Poll::Ready(())
  31 /// }
  32 /// ```
  33 ///
  34 /// The `ready!` call expands to:
  35 ///
  36 /// ```
  37 /// # #![feature(ready_macro)]
  38 /// # use std::task::{Context, Poll};
  39 /// # use std::future::{self, Future};
  40 /// # use std::pin::Pin;
  41 /// #
  42 /// # pub fn do_poll(cx: &mut Context<'_>) -> Poll<()> {
  43 ///     # let mut fut = future::ready(42);
  44 ///     # let fut = Pin::new(&mut fut);
  45 ///     #
  46 /// let num = match fut.poll(cx) {
  47 ///     Poll::Ready(t) => t,
  48 ///     Poll::Pending => return Poll::Pending,
  49 /// };
  50 ///     # drop(num);
  51 ///     # // ... use num
  52 ///     #
  53 ///     # Poll::Ready(())
  54 /// # }
  55 /// ```
  56 #[unstable(feature = "ready_macro", issue = "70922")]
  57 #[rustc_macro_transparency = "semitransparent"]
  58 pub macro ready($e:expr) {
  59     match $e {
  60         $crate::task::Poll::Ready(t) => t,
  61         $crate::task::Poll::Pending => {
  62             return $crate::task::Poll::Pending;
  63         }
  64     }
  65 }
  66
  67 /// Extracts the successful type of a [`Poll<T>`].
  68 ///
  69 /// See [`Poll::ready`] for details.
  70 #[unstable(feature = "poll_ready", issue = "89780")]
  71 pub struct Ready<T>(pub(crate) Poll<T>);
  72
  73 #[unstable(feature = "poll_ready", issue = "89780")]
  74 impl<T> Try for Ready<T> {
  75     type Output = T;
  76     type Residual = Ready<convert::Infallible>;
  77
  78     #[inline]
  79     fn from_output(output: Self::Output) -> Self {
  80         Ready(Poll::Ready(output))
  81     }
  82
  83     #[inline]
  84     fn branch(self) -> ControlFlow<Self::Residual, Self::Output> {
  85         match self.0 {
  86             Poll::Ready(v) => ControlFlow::Continue(v),
  87             Poll::Pending => ControlFlow::Break(Ready(Poll::Pending)),
  88         }
  89     }
  90 }
  91
  92 #[unstable(feature = "poll_ready", issue = "89780")]
  93 impl<T> FromResidual for Ready<T> {
  94     #[inline]
  95     fn from_residual(residual: Ready<convert::Infallible>) -> Self {
  96         match residual.0 {
  97             Poll::Pending => Ready(Poll::Pending),
  98         }
  99     }
 100 }
 101
 102 #[unstable(feature = "poll_ready", issue = "89780")]
 103 impl<T> FromResidual<Ready<convert::Infallible>> for Poll<T> {
 104     #[inline]
 105     fn from_residual(residual: Ready<convert::Infallible>) -> Self {
 106         match residual.0 {
 107             Poll::Pending => Poll::Pending,
 108         }
 109     }
 110 }
 111
 112 #[unstable(feature = "poll_ready", issue = "89780")]
 113 impl<T> fmt::Debug for Ready<T> {
 114     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 115         f.debug_tuple("Ready").finish()
 116     }
 117 }