src/libcore/future/future.rs

   1 // Copyright 2018 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 #![unstable(feature = "futures_api",
  12             reason = "futures in libcore are unstable",
  13             issue = "50547")]
  14
  15 use mem::PinMut;
  16 use marker::Unpin;
  17 use task::{self, Poll};
  18
  19 /// A future represents an asychronous computation.
  20 ///
  21 /// A future is a value that may not have finished computing yet. This kind of
  22 /// "asynchronous value" makes it possible for a thread to continue doing useful
  23 /// work while it waits for the value to become available.
  24 ///
  25 /// # The `poll` method
  26 ///
  27 /// The core method of future, `poll`, *attempts* to resolve the future into a
  28 /// final value. This method does not block if the value is not ready. Instead,
  29 /// the current task is scheduled to be woken up when it's possible to make
  30 /// further progress by `poll`ing again. The wake up is performed using
  31 /// `cx.waker()`, a handle for waking up the current task.
  32 ///
  33 /// When using a future, you generally won't call `poll` directly, but instead
  34 /// `await!` the value.
  35 pub trait Future {
  36     /// The result of the `Future`.
  37     type Output;
  38
  39     /// Attempt to resolve the future to a final value, registering
  40     /// the current task for wakeup if the value is not yet available.
  41     ///
  42     /// # Return value
  43     ///
  44     /// This function returns:
  45     ///
  46     /// - [`Poll::Pending`] if the future is not ready yet
  47     /// - [`Poll::Ready(val)`] with the result `val` of this future if it
  48     ///   finished successfully.
  49     ///
  50     /// Once a future has finished, clients should not `poll` it again.
  51     ///
  52     /// When a future is not ready yet, `poll` returns
  53     /// `Poll::Pending`. The future will *also* register the
  54     /// interest of the current task in the value being produced. For example,
  55     /// if the future represents the availability of data on a socket, then the
  56     /// task is recorded so that when data arrives, it is woken up (via
  57     /// [`cx.waker()`]). Once a task has been woken up,
  58     /// it should attempt to `poll` the future again, which may or may not
  59     /// produce a final value.
  60     ///
  61     /// Note that if `Pending` is returned it only means that the *current* task
  62     /// (represented by the argument `cx`) will receive a notification. Tasks
  63     /// from previous calls to `poll` will *not* receive notifications.
  64     ///
  65     /// # Runtime characteristics
  66     ///
  67     /// Futures alone are *inert*; they must be *actively* `poll`ed to make
  68     /// progress, meaning that each time the current task is woken up, it should
  69     /// actively re-`poll` pending futures that it still has an interest in.
  70     ///
  71     /// The `poll` function is not called repeatedly in a tight loop for
  72     /// futures, but only whenever the future itself is ready, as signaled via
  73     /// the `Waker` inside `task::Context`. If you're familiar with the
  74     /// `poll(2)` or `select(2)` syscalls on Unix it's worth noting that futures
  75     /// typically do *not* suffer the same problems of "all wakeups must poll
  76     /// all events"; they are more like `epoll(4)`.
  77     ///
  78     /// An implementation of `poll` should strive to return quickly, and must
  79     /// *never* block. Returning quickly prevents unnecessarily clogging up
  80     /// threads or event loops. If it is known ahead of time that a call to
  81     /// `poll` may end up taking awhile, the work should be offloaded to a
  82     /// thread pool (or something similar) to ensure that `poll` can return
  83     /// quickly.
  84     ///
  85     /// # Panics
  86     ///
  87     /// Once a future has completed (returned `Ready` from `poll`),
  88     /// then any future calls to `poll` may panic, block forever, or otherwise
  89     /// cause bad behavior. The `Future` trait itself provides no guarantees
  90     /// about the behavior of `poll` after a future has completed.
  91     ///
  92     /// [`Poll::Pending`]: ../task/enum.Poll.html#variant.Pending
  93     /// [`Poll::Ready(val)`]: ../task/enum.Poll.html#variant.Ready
  94     /// [`cx.waker()`]: ../task/struct.Context.html#method.waker
  95     fn poll(self: PinMut<Self>, cx: &mut task::Context) -> Poll<Self::Output>;
  96 }
  97
  98 impl<'a, F: ?Sized + Future + Unpin> Future for &'a mut F {
  99     type Output = F::Output;
 100
 101     fn poll(mut self: PinMut<Self>, cx: &mut task::Context) -> Poll<Self::Output> {
 102         F::poll(PinMut::new(&mut **self), cx)
 103     }
 104 }
 105
 106 impl<'a, F: ?Sized + Future> Future for PinMut<'a, F> {
 107     type Output = F::Output;
 108
 109     fn poll(mut self: PinMut<Self>, cx: &mut task::Context) -> Poll<Self::Output> {
 110         F::poll((*self).reborrow(), cx)
 111     }
 112 }