Struct stakker::Waker

pub struct Waker { /* fields omitted */ }

Used to schedule a wake handler to be called in the main thread

Obtain an instance using Core::waker. This primitive would normally be used in conjunction with a channel or some other shared list or shared state, to alert a wake handler in the main thread that there is a new message that needs attention, or that some other change has occurred.

When this is dropped, either due to being manually dropped or due to a panic, a final call to the wake handler in the main thread is scheduled with the deleted argument set to true, and then the wake handler is removed.

Note that there is no mechanism for back-pressure or cancellation here, i.e. no way to inform a Waker that whatever the wake handler notifies has gone away or needs to pause. This should all be handled via whatever channel or shared state is used to communicate data from the other thread to the main thread. Usually cancellation would need to be flagged in a drop handler in the main thread, e.g. in an actor's drop handler. That way the other thread can recognise the situation and terminate, ensuring that things clean up nicely in case of failure of the actor.

Methods

impl Waker

pub fn wake(&self)

Schedule a call to the corresponding wake handler in the main thread, if it is not already scheduled to be called. If it is already scheduled (or a nearby handler is already scheduled), this requires just one SeqCst atomic operation. In the worst case it requires 3 atomic operations, and a wake-up call to the I/O poller.

This is handled using a heirarchical tree of usize bitmaps containing wake bits, one leaf wake bit for each Waker. At the top of the tree is the poll-waker. The wake-up only needs to ascend until it reaches a level which has already been woken. In the main thread, in response to the poll-wake the heirarchy is descended only on those branches where there are wake bits set. The wake bits are cleared and the corresponding wake handlers are called. The longer the poll-wake process takes, the more wakes will be accumulated in the bitmap, so this parallelizes well.

Trait Implementations

impl Drop for Waker

fn drop(&mut self)

Executes the destructor for this type.