The implementation of waking a task on an executor.

This trait can be used to create a Waker. An executor can define an implementation of this trait, and use that to construct a Waker to pass to the tasks that are executed on that executor.

This trait is a memory-safe and ergonomic alternative to constructing a RawWaker. It supports the common executor design in which the data used to wake up a task is stored in an Arc. Some executors (especially those for embedded systems) cannot use this API, which is why RawWaker exists as an alternative for those systems.

To construct a Waker from some type W implementing this trait, wrap it in an Arc<W> and call Waker::from() on that. It is also possible to convert to RawWaker in the same way.

Examples

A basic block_on function that takes a future and runs it to completion on the current thread.

Note: This example trades correctness for simplicity. In order to prevent deadlocks, production-grade implementations will also need to handle intermediate calls to thread::unpark as well as nested invocations.

use std::future::Future;
use std::sync::Arc;
use std::task::{Context, Poll, Wake};
use std::thread::{self, Thread};
use core::pin::pin;

/// A waker that wakes up the current thread when called.
struct ThreadWaker(Thread);

impl Wake for ThreadWaker {
    fn wake(self: Arc<Self>) {
        self.0.unpark();
    }
}

/// Run a future to completion on the current thread.
fn block_on<T>(fut: impl Future<Output = T>) -> T {
    // Pin the future so it can be polled.
    let mut fut = pin!(fut);

    // Create a new context to be passed to the future.
    let t = thread::current();
    let waker = Arc::new(ThreadWaker(t)).into();
    let mut cx = Context::from_waker(&waker);

    // Run the future to completion.
    loop {
        match fut.as_mut().poll(&mut cx) {
            Poll::Ready(res) => return res,
            Poll::Pending => thread::park(),
        }
    }
}

block_on(async {
    println!("Hi from inside a future!");
});