[−][src]Struct stakker::Waker
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
[src]
pub fn wake(&self)
[src]
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, 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
Auto Trait Implementations
impl !RefUnwindSafe for Waker
impl Send for Waker
impl Sync for Waker
impl Unpin for Waker
impl !UnwindSafe for Waker
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Any for T where
T: Any,
[src]
T: Any,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,