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     #[stable(feature = "futures_api", since = "1.36.0")]
  43     pub fn is_ready(&self) -> bool {
  44         matches!(*self, Poll::Ready(_))
  45     }
  46
  47     /// Returns `true` if this is `Poll::Pending`
  48     #[inline]
  49     #[stable(feature = "futures_api", since = "1.36.0")]
  50     pub fn is_pending(&self) -> bool {
  51         !self.is_ready()
  52     }
  53 }
  54
  55 impl<T, E> Poll<Result<T, E>> {
  56     /// Changes the success value of this `Poll` with the closure provided.
  57     #[stable(feature = "futures_api", since = "1.36.0")]
  58     pub fn map_ok<U, F>(self, f: F) -> Poll<Result<U, E>>
  59     where
  60         F: FnOnce(T) -> U,
  61     {
  62         match self {
  63             Poll::Ready(Ok(t)) => Poll::Ready(Ok(f(t))),
  64             Poll::Ready(Err(e)) => Poll::Ready(Err(e)),
  65             Poll::Pending => Poll::Pending,
  66         }
  67     }
  68
  69     /// Changes the error value of this `Poll` with the closure provided.
  70     #[stable(feature = "futures_api", since = "1.36.0")]
  71     pub fn map_err<U, F>(self, f: F) -> Poll<Result<T, U>>
  72     where
  73         F: FnOnce(E) -> U,
  74     {
  75         match self {
  76             Poll::Ready(Ok(t)) => Poll::Ready(Ok(t)),
  77             Poll::Ready(Err(e)) => Poll::Ready(Err(f(e))),
  78             Poll::Pending => Poll::Pending,
  79         }
  80     }
  81 }
  82
  83 impl<T, E> Poll<Option<Result<T, E>>> {
  84     /// Changes the success value of this `Poll` with the closure provided.
  85     #[unstable(feature = "poll_map", issue = "63514")]
  86     pub fn map_ok<U, F>(self, f: F) -> Poll<Option<Result<U, E>>>
  87     where
  88         F: FnOnce(T) -> U,
  89     {
  90         match self {
  91             Poll::Ready(Some(Ok(t))) => Poll::Ready(Some(Ok(f(t)))),
  92             Poll::Ready(Some(Err(e))) => Poll::Ready(Some(Err(e))),
  93             Poll::Ready(None) => Poll::Ready(None),
  94             Poll::Pending => Poll::Pending,
  95         }
  96     }
  97
  98     /// Changes the error value of this `Poll` with the closure provided.
  99     #[unstable(feature = "poll_map", issue = "63514")]
 100     pub fn map_err<U, F>(self, f: F) -> Poll<Option<Result<T, U>>>
 101     where
 102         F: FnOnce(E) -> U,
 103     {
 104         match self {
 105             Poll::Ready(Some(Ok(t))) => Poll::Ready(Some(Ok(t))),
 106             Poll::Ready(Some(Err(e))) => Poll::Ready(Some(Err(f(e)))),
 107             Poll::Ready(None) => Poll::Ready(None),
 108             Poll::Pending => Poll::Pending,
 109         }
 110     }
 111 }
 112
 113 #[stable(feature = "futures_api", since = "1.36.0")]
 114 impl<T> From<T> for Poll<T> {
 115     fn from(t: T) -> Poll<T> {
 116         Poll::Ready(t)
 117     }
 118 }
 119
 120 #[stable(feature = "futures_api", since = "1.36.0")]
 121 impl<T, E> Try for Poll<Result<T, E>> {
 122     type Ok = Poll<T>;
 123     type Error = E;
 124
 125     #[inline]
 126     fn into_result(self) -> Result<Self::Ok, Self::Error> {
 127         match self {
 128             Poll::Ready(Ok(x)) => Ok(Poll::Ready(x)),
 129             Poll::Ready(Err(e)) => Err(e),
 130             Poll::Pending => Ok(Poll::Pending),
 131         }
 132     }
 133
 134     #[inline]
 135     fn from_error(e: Self::Error) -> Self {
 136         Poll::Ready(Err(e))
 137     }
 138
 139     #[inline]
 140     fn from_ok(x: Self::Ok) -> Self {
 141         x.map(Ok)
 142     }
 143 }
 144
 145 #[stable(feature = "futures_api", since = "1.36.0")]
 146 impl<T, E> Try for Poll<Option<Result<T, E>>> {
 147     type Ok = Poll<Option<T>>;
 148     type Error = E;
 149
 150     #[inline]
 151     fn into_result(self) -> Result<Self::Ok, Self::Error> {
 152         match self {
 153             Poll::Ready(Some(Ok(x))) => Ok(Poll::Ready(Some(x))),
 154             Poll::Ready(Some(Err(e))) => Err(e),
 155             Poll::Ready(None) => Ok(Poll::Ready(None)),
 156             Poll::Pending => Ok(Poll::Pending),
 157         }
 158     }
 159
 160     #[inline]
 161     fn from_error(e: Self::Error) -> Self {
 162         Poll::Ready(Some(Err(e)))
 163     }
 164
 165     #[inline]
 166     fn from_ok(x: Self::Ok) -> Self {
 167         x.map(|x| x.map(Ok))
 168     }
 169 }