future.rs.html -- source
Description: Source to the Rust file `src/libcore/future/future.rs`.
Keywords: rust, rustlang, rust-lang

      1
      2
      3
      4
      5
      6
      7
      8
      9
     10
     11
     12
     13
     14
     15
     16
     17
     18
     19
     20
     21
     22
     23
     24
     25
     26
     27
     28
     29
     30
     31
     32
     33
     34
     35
     36
     37
     38
     39
     40
     41
     42
     43
     44
     45
     46
     47
     48
     49
     50
     51
     52
     53
     54
     55
     56
     57
     58
     59
     60
     61
     62
     63
     64
     65
     66
     67
     68
     69
     70
     71
     72
     73
     74
     75
     76
     77
     78
     79
     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121

    #![unstable(feature = "futures_api",
                reason = "futures in libcore are unstable",
                issue = "50547")]

    use marker::Unpin;
    use ops;
    use pin::Pin;
    use task::{Poll, LocalWaker};

    /// A future represents an asynchronous computation.
    ///
    /// A future is a value that may not have finished computing yet. This kind of
    /// "asynchronous value" makes it possible for a thread to continue doing useful
    /// work while it waits for the value to become available.
    ///
    /// # The `poll` method
    ///
    /// The core method of future, `poll`, *attempts* to resolve the future into a
    /// final value. This method does not block if the value is not ready. Instead,
    /// the current task is scheduled to be woken up when it's possible to make
    /// further progress by `poll`ing again. The wake up is performed using
    /// `cx.waker()`, a handle for waking up the current task.
    ///
    /// When using a future, you generally won't call `poll` directly, but instead
    /// `await!` the value.
    #[must_use = "futures do nothing unless polled"]
    pub trait Future {
        /// The result of the `Future`.
        type Output;

        /// Attempt to resolve the future to a final value, registering
        /// the current task for wakeup if the value is not yet available.
        ///
        /// # Return value
        ///
        /// This function returns:
        ///
        /// - [`Poll::Pending`] if the future is not ready yet
        /// - [`Poll::Ready(val)`] with the result `val` of this future if it
        ///   finished successfully.
        ///
        /// Once a future has finished, clients should not `poll` it again.
        ///
        /// When a future is not ready yet, `poll` returns `Poll::Pending` and
        /// stores a clone of the [`LocalWaker`] to be woken once the future can
        /// make progress. For example, a future waiting for a socket to become
        /// readable would call `.clone()` on the [`LocalWaker`] and store it.
        /// When a signal arrives elsewhere indicating that the socket is readable,
        /// `[LocalWaker::wake]` is called and the socket future's task is awoken.
        /// Once a task has been woken up, it should attempt to `poll` the future
        /// again, which may or may not produce a final value.
        ///
        /// Note that on multiple calls to `poll`, only the most recent
        /// [`LocalWaker`] passed to `poll` should be scheduled to receive a
        /// wakeup.
        ///
        /// # Runtime characteristics
        ///
        /// Futures alone are *inert*; they must be *actively* `poll`ed to make
        /// progress, meaning that each time the current task is woken up, it should
        /// actively re-`poll` pending futures that it still has an interest in.
        ///
        /// The `poll` function is not called repeatedly in a tight loop-- instead,
        /// it should only be called when the future indicates that it is ready to
        /// make progress (by calling `wake()`). If you're familiar with the
        /// `poll(2)` or `select(2)` syscalls on Unix it's worth noting that futures
        /// typically do *not* suffer the same problems of "all wakeups must poll
        /// all events"; they are more like `epoll(4)`.
        ///
        /// An implementation of `poll` should strive to return quickly, and must
        /// *never* block. Returning quickly prevents unnecessarily clogging up
        /// threads or event loops. If it is known ahead of time that a call to
        /// `poll` may end up taking awhile, the work should be offloaded to a
        /// thread pool (or something similar) to ensure that `poll` can return
        /// quickly.
        ///
        /// # [`LocalWaker`], [`Waker`] and thread-safety
        ///
        /// The `poll` function takes a [`LocalWaker`], an object which knows how to
        /// awaken the current task. [`LocalWaker`] is not `Send` nor `Sync`, so in
        /// order to make thread-safe futures the [`LocalWaker::into_waker`] method
        /// should be used to convert the [`LocalWaker`] into a thread-safe version.
        /// [`LocalWaker::wake`] implementations have the ability to be more
        /// efficient, however, so when thread safety is not necessary,
        /// [`LocalWaker`] should be preferred.
        ///
        /// # Panics
        ///
        /// Once a future has completed (returned `Ready` from `poll`),
        /// then any future calls to `poll` may panic, block forever, or otherwise
        /// cause bad behavior. The `Future` trait itself provides no guarantees
        /// about the behavior of `poll` after a future has completed.
        ///
        /// [`Poll::Pending`]: ../task/enum.Poll.html#variant.Pending
        /// [`Poll::Ready(val)`]: ../task/enum.Poll.html#variant.Ready
        /// [`LocalWaker`]: ../task/struct.LocalWaker.html
        /// [`LocalWaker::into_waker`]: ../task/struct.LocalWaker.html#method.into_waker
        /// [`LocalWaker::wake`]: ../task/struct.LocalWaker.html#method.wake
        /// [`Waker`]: ../task/struct.Waker.html
        fn poll(self: Pin<&mut Self>, lw: &LocalWaker) -> Poll<Self::Output>;
    }

    impl<'a, F: ?Sized + Future + Unpin> Future for &'a mut F {
        type Output = F::Output;

        fn poll(mut self: Pin<&mut Self>, lw: &LocalWaker) -> Poll<Self::Output> {
            F::poll(Pin::new(&mut **self), lw)
        }
    }

    impl<P> Future for Pin<P>
    where
        P: Unpin + ops::DerefMut,
        P::Target: Future,
    {
        type Output = <<P as ops::Deref>::Target as Future>::Output;

        fn poll(self: Pin<&mut Self>, lw: &LocalWaker) -> Poll<Self::Output> {
            Pin::get_mut(self).as_mut().poll(lw)
        }
    }

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)