Struct stakker::sync::Waker

pub struct Waker { /* private fields */ }

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

Obtain an instance using Core::waker, and pass it to the thread that needs to wake the main thread. 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.

Implementations

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 hierarchical 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 hierarchy 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, making the next wake more efficient, so this scales well.

Note that this operation has to be as cheap as possible because with a channel for example, you’ll need to call it every time you add an item. Trying to detect when you add the first item to an empty queue is unreliable due to races (for example calling channel.is_empty() first and then channel.send() would race with the main thread removing items). So unless the channel has specific support for detecting writing to an empty queue (some kind of channel.send_and_was_empty() call), it’s necessary to wake on every send.

Trait Implementations

impl Drop for Waker

fn drop(&mut self)

Executes the destructor for this type.