Currently, constructing a waker requires calling the unsafe
`Waker::from_raw` API. This API requires the user to manually construct
a vtable for the waker themself - which is both cumbersome and very
error prone. This API would provide an ergonomic, straightforward and
guaranteed memory-safe way of constructing a waker.
It has been our longstanding intention that the `Waker` type essentially
function as an `Arc<dyn Wake>`, with a `Wake` trait as defined here. Two
considerations prevented the original API from being shipped as simply
an `Arc<dyn Wake>`:
- We want to support futures on embedded systems, which may not have an
allocator, and in optimized executors for which this API may not be
best-suited. Therefore, we have always explicitly supported the
maximally-flexible (but also memory-unsafe) `RawWaker` API, and
`Waker` has always lived in libcore.
- Because `Waker` lives in libcore and `Arc` lives in liballoc, it has
not been feasible to provide a constructor for `Waker` from `Arc<dyn
Wake>`.
Therefore, the Wake trait was left out of the initial version of the
task waker API.
However, as Rust 1.41, it is possible under the more flexible orphan
rules to implement `From<Arc<W>> for Waker where W: Wake` in liballoc.
Therefore, we can now define this constructor even though `Waker` lives
in libcore.
This PR adds these APIs:
- A `Wake` trait, which contains two methods
- A required method `wake`, which is called by `Waker::wake`
- A provided method `wake_by_ref`, which is called by
`Waker::wake_by_ref` and which implementors can override if they
can optimize this use case.
- An implementation of `From<Arc<W>> for Waker where W: Wake + Send +
Sync + 'static`
- A similar implementation of `From<Arc<W>> for RawWaker`.
06ede350c2