Task Wakeups with Waker

Future 一次polled 就能完成的，并不常见。而多数情况下，Future 需要确保一旦准备好前进，就再次进行轮询(poll) 。而这是通过Waker类型，辅助完成的。

每次 Future poll 时，都会将其作为“任务(task)”的一部分。任务是已提交给 executor 的顶级 Future 。

Waker提供一个wake()方法，它可以用来告诉 executor，应该唤醒的相关任务。当wake()被调用时， executor 知道与Waker相关联的任务是准备前进，并且，它的 Future 应再次进行 poll。

Waker还实现了clone()，这样就可以将其复制和存储。

让我们尝试使用Waker，实现一个简单的计时器 future。

Applied: Build a Timer

在本示例中，我们将在创建计时器（Timer）时，启动一个新线程，休眠下所需的时间，然后在时间窗口 elapsed(逝去) 后，向计时器发出信号。

这是我们需要开始的导入：

                        #![allow(unused_variables)]
                        fn main() {
                        use {
                            std::{
                                future::Future,
                                pin::Pin,
                                sync::{Arc, Mutex},
                                task::{Context, Poll, Waker},
                                thread,
                                time::Duration,
                            },
                        };
                        }
                        

让我们从定义 future 类型本身开始。我们的 future 需要一种方法，来让线程可以传达，timer elapsed 和 这个 future 应该完成的信息。我们将使用一个Arc<Mutex<..>>共享值，在线程和 Future 之间进行通信。

                        #![allow(unused_variables)]
                        fn main() {
                        pub struct TimerFuture {
                            shared_state: Arc<Mutex<SharedState>>,
                        }
                        
                        /// Shared state between the future and the waiting thread
                        struct SharedState {
                            /// Whether or not the sleep time has elapsed
                            completed: bool,
                        
                            /// The waker for the task that `TimerFuture` is running on.
                            /// The thread can use this after setting `completed = true` to tell
                            /// `TimerFuture`'s task to wake up, see that `completed = true`, and
                            /// move forward.
                            waker: Option<Waker>,
                        }
                        }
                        

现在，让我们实际编写Future实现！

                        #![allow(unused_variables)]
                        fn main() {
                        impl Future for TimerFuture {
                            type Output = ();
                            fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
                                // Look at the shared state to see if the timer has already completed.
                                let mut shared_state = self.shared_state.lock().unwrap();
                                if shared_state.completed {
                                    Poll::Ready(())
                                } else {
                                    // Set waker so that the thread can wake up the current task
                                    // when the timer has completed, ensuring that the future is polled
                                    // again and sees that `completed = true`.
                                    //
                                    // It's tempting to do this once rather than repeatedly cloning
                                    // the waker each time. However, the `TimerFuture` can move between
                                    // tasks on the executor, which could cause a stale waker pointing
                                    // to the wrong task, preventing `TimerFuture` from waking up
                                    // correctly.
                                    //
                                    // N.B. it's possible to check for this using the `Waker::will_wake`
                                    // function, but we omit that here to keep things simple.
                                    shared_state.waker = Some(cx.waker().clone());
                                    Poll::Pending
                                }
                            }
                        }
                        }
                        

很简单，对吧？如果线程设置了shared_state.completed = true，我们就搞定了！不然的话，我们会为当前任务，clone Waker，并将其传递给shared_state.waker，这样线程才能唤醒备份的任务。

重要的是，每次 Future 进行 poll，我们必须更新Waker，因为 Future 可能已经转移到，具有一个不同Waker的不同任务上了。这种情况在 Future poll 后，在任务之间传来传去时，会发生。

最后，我们需要实际构造计时器的 API ，并启动线程：

                        #![allow(unused_variables)]
                        fn main() {
                        impl TimerFuture {
                            /// Create a new `TimerFuture` which will complete after the provided
                            /// timeout.
                            pub fn new(duration: Duration) -> Self {
                                let shared_state = Arc::new(Mutex::new(SharedState {
                                    completed: false,
                                    waker: None,
                                }));
                        
                                // Spawn the new thread
                                let thread_shared_state = shared_state.clone();
                                thread::spawn(move || {
                                    thread::sleep(duration);
                                    let mut shared_state = thread_shared_state.lock().unwrap();
                                    // Signal that the timer has completed and wake up the last
                                    // task on which the future was polled, if one exists.
                                    shared_state.completed = true;
                                    if let Some(waker) = shared_state.waker.take() {
                                        waker.wake()
                                    }
                                });
                        
                                TimerFuture { shared_state }
                            }
                        }
                        }
                        

Woot！这就是我们构建一个简单的计时器 future 的全部。现在，如果我们只有一个 executor，来运行 future ...