55use marker:: Unpin ;
66use ops;
77use pin:: Pin ;
8- use task:: { Poll , LocalWaker } ;
8+ use task:: { Poll , Waker } ;
99
1010/// A future represents an asynchronous computation.
1111///
@@ -19,13 +19,14 @@ use task::{Poll, LocalWaker};
1919/// final value. This method does not block if the value is not ready. Instead,
2020/// the current task is scheduled to be woken up when it's possible to make
2121/// further progress by `poll`ing again. The wake up is performed using
22- /// `cx.waker()`, a handle for waking up the current task.
22+ /// the `waker` argument of the `poll()` method, which is a handle for waking
23+ /// up the current task.
2324///
2425/// When using a future, you generally won't call `poll` directly, but instead
2526/// `await!` the value.
2627#[ must_use = "futures do nothing unless polled" ]
2728pub trait Future {
28- /// The result of the `Future` .
29+ /// The type of value produced on completion .
2930type Output ;
3031
3132 /// Attempt to resolve the future to a final value, registering
@@ -42,16 +43,16 @@ pub trait Future {
4243/// Once a future has finished, clients should not `poll` it again.
4344///
4445/// When a future is not ready yet, `poll` returns `Poll::Pending` and
45- /// stores a clone of the [`LocalWaker `] to be woken once the future can
46+ /// stores a clone of the [`Waker `] to be woken once the future can
4647/// make progress. For example, a future waiting for a socket to become
47- /// readable would call `.clone()` on the [`LocalWaker `] and store it.
48+ /// readable would call `.clone()` on the [`Waker `] and store it.
4849/// When a signal arrives elsewhere indicating that the socket is readable,
49- /// `[LocalWaker ::wake]` is called and the socket future's task is awoken.
50+ /// `[Waker ::wake]` is called and the socket future's task is awoken.
5051/// Once a task has been woken up, it should attempt to `poll` the future
5152/// again, which may or may not produce a final value.
5253///
5354/// Note that on multiple calls to `poll`, only the most recent
54- /// [`LocalWaker `] passed to `poll` should be scheduled to receive a
55+ /// [`Waker `] passed to `poll` should be scheduled to receive a
5556/// wakeup.
5657///
5758/// # Runtime characteristics
@@ -67,44 +68,35 @@ pub trait Future {
6768/// typically do *not* suffer the same problems of "all wakeups must poll
6869/// all events"; they are more like `epoll(4)`.
6970///
70- /// An implementation of `poll` should strive to return quickly, and must
71- /// *never* block. Returning quickly prevents unnecessarily clogging up
71+ /// An implementation of `poll` should strive to return quickly, and should
72+ /// not block. Returning quickly prevents unnecessarily clogging up
7273/// threads or event loops. If it is known ahead of time that a call to
7374/// `poll` may end up taking awhile, the work should be offloaded to a
7475/// thread pool (or something similar) to ensure that `poll` can return
7576/// quickly.
7677///
77- /// # [`LocalWaker`], [`Waker`] and thread-safety
78- ///
79- /// The `poll` function takes a [`LocalWaker`], an object which knows how to
80- /// awaken the current task. [`LocalWaker`] is not `Send` nor `Sync`, so in
81- /// order to make thread-safe futures the [`LocalWaker::into_waker`] method
82- /// should be used to convert the [`LocalWaker`] into a thread-safe version.
83- /// [`LocalWaker::wake`] implementations have the ability to be more
84- /// efficient, however, so when thread safety is not necessary,
85- /// [`LocalWaker`] should be preferred.
78+ /// An implementation of `poll` may also never cause memory unsafety.
8679///
8780/// # Panics
8881///
8982/// Once a future has completed (returned `Ready` from `poll`),
9083/// then any future calls to `poll` may panic, block forever, or otherwise
91- /// cause bad behavior. The `Future` trait itself provides no guarantees
92- /// about the behavior of `poll` after a future has completed.
84+ /// cause any kind of bad behavior expect causing memory unsafety.
85+ /// The `Future` trait itself provides no guarantees about the behavior
86+ /// of `poll` after a future has completed.
9387///
9488/// [`Poll::Pending`]: ../task/enum.Poll.html#variant.Pending
9589/// [`Poll::Ready(val)`]: ../task/enum.Poll.html#variant.Ready
96- /// [`LocalWaker`]: ../task/struct.LocalWaker.html
97- /// [`LocalWaker::into_waker`]: ../task/struct.LocalWaker.html#method.into_waker
98- /// [`LocalWaker::wake`]: ../task/struct.LocalWaker.html#method.wake
9990/// [`Waker`]: ../task/struct.Waker.html
100- fn poll ( self : Pin < & mut Self > , lw : & LocalWaker ) -> Poll < Self :: Output > ;
91+ /// [`Waker::wake`]: ../task/struct.Waker.html#method.wake
92+ fn poll ( self : Pin < & mut Self > , waker : & Waker ) -> Poll < Self :: Output > ;
10193}
10294
10395impl < ' a , F : ?Sized + Future + Unpin > Future for & ' a mut F {
10496 type Output = F :: Output ;
10597
106- fn poll ( mut self : Pin < & mut Self > , lw : & LocalWaker ) -> Poll < Self :: Output > {
107- F :: poll ( Pin :: new ( & mut * * self ) , lw )
98+ fn poll ( mut self : Pin < & mut Self > , waker : & Waker ) -> Poll < Self :: Output > {
99+ F :: poll ( Pin :: new ( & mut * * self ) , waker )
108100 }
109101}
110102
@@ -115,7 +107,7 @@ where
115107{
116108 type Output = <<P as ops:: Deref >:: Target as Future >:: Output ;
117109
118- fn poll ( self : Pin < & mut Self > , lw : & LocalWaker ) -> Poll < Self :: Output > {
119- Pin :: get_mut ( self ) . as_mut ( ) . poll ( lw )
110+ fn poll ( self : Pin < & mut Self > , waker : & Waker ) -> Poll < Self :: Output > {
111+ Pin :: get_mut ( self ) . as_mut ( ) . poll ( waker )
120112 }
121113}
0 commit comments