library/core/src/task/poll.rs

   1 #![stable(feature = "futures_api", since = "1.36.0")]
   2
   3 use crate::ops::Try;
   4 use crate::result::Result;
   5
   6 /// Indicates whether a value is available or if the current task has been
   7 /// scheduled to receive a wakeup instead.
   8 #[must_use = "this `Poll` may be a `Pending` variant, which should be handled"]
   9 #[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
  10 #[stable(feature = "futures_api", since = "1.36.0")]
  11 pub enum Poll<T> {
  12     /// Represents that a value is immediately ready.
  13     #[lang = "Ready"]
  14     #[stable(feature = "futures_api", since = "1.36.0")]
  15     Ready(#[stable(feature = "futures_api", since = "1.36.0")] T),
  16
  17     /// Represents that a value is not ready yet.
  18     ///
  19     /// When a function returns `Pending`, the function *must* also
  20     /// ensure that the current task is scheduled to be awoken when
  21     /// progress can be made.
  22     #[lang = "Pending"]
  23     #[stable(feature = "futures_api", since = "1.36.0")]
  24     Pending,
  25 }
  26
  27 impl<T> Poll<T> {
  28     /// Changes the ready value of this `Poll` with the closure provided.
  29     #[stable(feature = "futures_api", since = "1.36.0")]
  30     pub fn map<U, F>(self, f: F) -> Poll<U>
  31     where
  32         F: FnOnce(T) -> U,
  33     {
  34         match self {
  35             Poll::Ready(t) => Poll::Ready(f(t)),
  36             Poll::Pending => Poll::Pending,
  37         }
  38     }
  39
  40     /// Returns `true` if this is `Poll::Ready`
  41     #[inline]
  42     #[rustc_const_stable(feature = "const_poll", since = "1.49.0")]
  43     #[stable(feature = "futures_api", since = "1.36.0")]
  44     pub const fn is_ready(&self) -> bool {
  45         matches!(*self, Poll::Ready(_))
  46     }
  47
  48     /// Returns `true` if this is `Poll::Pending`
  49     #[inline]
  50     #[rustc_const_stable(feature = "const_poll", since = "1.49.0")]
  51     #[stable(feature = "futures_api", since = "1.36.0")]
  52     pub const fn is_pending(&self) -> bool {
  53         !self.is_ready()
  54     }
  55 }
  56
  57 impl<T, E> Poll<Result<T, E>> {
  58     /// Changes the success value of this `Poll` with the closure provided.
  59     #[stable(feature = "futures_api", since = "1.36.0")]
  60     pub fn map_ok<U, F>(self, f: F) -> Poll<Result<U, E>>
  61     where
  62         F: FnOnce(T) -> U,
  63     {
  64         match self {
  65             Poll::Ready(Ok(t)) => Poll::Ready(Ok(f(t))),
  66             Poll::Ready(Err(e)) => Poll::Ready(Err(e)),
  67             Poll::Pending => Poll::Pending,
  68         }
  69     }
  70
  71     /// Changes the error value of this `Poll` with the closure provided.
  72     #[stable(feature = "futures_api", since = "1.36.0")]
  73     pub fn map_err<U, F>(self, f: F) -> Poll<Result<T, U>>
  74     where
  75         F: FnOnce(E) -> U,
  76     {
  77         match self {
  78             Poll::Ready(Ok(t)) => Poll::Ready(Ok(t)),
  79             Poll::Ready(Err(e)) => Poll::Ready(Err(f(e))),
  80             Poll::Pending => Poll::Pending,
  81         }
  82     }
  83 }
  84
  85 impl<T, E> Poll<Option<Result<T, E>>> {
  86     /// Changes the success value of this `Poll` with the closure provided.
  87     #[stable(feature = "poll_map", since = "1.51.0")]
  88     pub fn map_ok<U, F>(self, f: F) -> Poll<Option<Result<U, E>>>
  89     where
  90         F: FnOnce(T) -> U,
  91     {
  92         match self {
  93             Poll::Ready(Some(Ok(t))) => Poll::Ready(Some(Ok(f(t)))),
  94             Poll::Ready(Some(Err(e))) => Poll::Ready(Some(Err(e))),
  95             Poll::Ready(None) => Poll::Ready(None),
  96             Poll::Pending => Poll::Pending,
  97         }
  98     }
  99
 100     /// Changes the error value of this `Poll` with the closure provided.
 101     #[stable(feature = "poll_map", since = "1.51.0")]
 102     pub fn map_err<U, F>(self, f: F) -> Poll<Option<Result<T, U>>>
 103     where
 104         F: FnOnce(E) -> U,
 105     {
 106         match self {
 107             Poll::Ready(Some(Ok(t))) => Poll::Ready(Some(Ok(t))),
 108             Poll::Ready(Some(Err(e))) => Poll::Ready(Some(Err(f(e)))),
 109             Poll::Ready(None) => Poll::Ready(None),
 110             Poll::Pending => Poll::Pending,
 111         }
 112     }
 113 }
 114
 115 #[stable(feature = "futures_api", since = "1.36.0")]
 116 impl<T> From<T> for Poll<T> {
 117     /// Convert to a `Ready` variant.
 118     ///
 119     /// # Example
 120     ///
 121     /// ```
 122     /// # use core::task::Poll;
 123     /// assert_eq!(Poll::from(true), Poll::Ready(true));
 124     /// ```
 125     fn from(t: T) -> Poll<T> {
 126         Poll::Ready(t)
 127     }
 128 }
 129
 130 #[stable(feature = "futures_api", since = "1.36.0")]
 131 impl<T, E> Try for Poll<Result<T, E>> {
 132     type Ok = Poll<T>;
 133     type Error = E;
 134
 135     #[inline]
 136     fn into_result(self) -> Result<Self::Ok, Self::Error> {
 137         match self {
 138             Poll::Ready(Ok(x)) => Ok(Poll::Ready(x)),
 139             Poll::Ready(Err(e)) => Err(e),
 140             Poll::Pending => Ok(Poll::Pending),
 141         }
 142     }
 143
 144     #[inline]
 145     fn from_error(e: Self::Error) -> Self {
 146         Poll::Ready(Err(e))
 147     }
 148
 149     #[inline]
 150     fn from_ok(x: Self::Ok) -> Self {
 151         x.map(Ok)
 152     }
 153 }
 154
 155 #[stable(feature = "futures_api", since = "1.36.0")]
 156 impl<T, E> Try for Poll<Option<Result<T, E>>> {
 157     type Ok = Poll<Option<T>>;
 158     type Error = E;
 159
 160     #[inline]
 161     fn into_result(self) -> Result<Self::Ok, Self::Error> {
 162         match self {
 163             Poll::Ready(Some(Ok(x))) => Ok(Poll::Ready(Some(x))),
 164             Poll::Ready(Some(Err(e))) => Err(e),
 165             Poll::Ready(None) => Ok(Poll::Ready(None)),
 166             Poll::Pending => Ok(Poll::Pending),
 167         }
 168     }
 169
 170     #[inline]
 171     fn from_error(e: Self::Error) -> Self {
 172         Poll::Ready(Some(Err(e)))
 173     }
 174
 175     #[inline]
 176     fn from_ok(x: Self::Ok) -> Self {
 177         x.map(|x| x.map(Ok))
 178     }
 179 }