Struct async_stdio::WakerCtrl

pub struct WakerCtrl(_);

Waker control for the AsStdIo wrapper

Internally, it's an AtomicWaker, so the waker it points to can be updated with waker_ctrl.register(cx.waker()).

Methods from Deref<Target = AtomicWaker>

pub fn register(&self, waker: &Waker)

Registers the waker to be notified on calls to wake.

The new task will take place of any previous tasks that were registered by previous calls to register. Any calls to wake that happen after a call to register (as defined by the memory ordering rules), will notify the register caller's task and deregister the waker from future notifications. Because of this, callers should ensure register gets invoked with a new Waker each time they require a wakeup.

It is safe to call register with multiple other threads concurrently calling wake. This will result in the register caller's current task being notified once.

This function is safe to call concurrently, but this is generally a bad idea. Concurrent calls to register will attempt to register different tasks to be notified. One of the callers will win and have its task set, but there is no guarantee as to which caller will succeed.

Examples

Here is how register is used when implementing a flag.

use futures::future::Future;
use futures::task::{Context, Poll, AtomicWaker};
use std::sync::atomic::AtomicBool;
use std::sync::atomic::Ordering::SeqCst;
use std::pin::Pin;

struct Flag {
    waker: AtomicWaker,
    set: AtomicBool,
}

impl Future for Flag {
    type Output = ();

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
        // Register **before** checking `set` to avoid a race condition
        // that would result in lost notifications.
        self.waker.register(cx.waker());

        if self.set.load(SeqCst) {
            Poll::Ready(())
        } else {
            Poll::Pending
        }
    }
}

pub fn wake(&self)

Calls wake on the last Waker passed to register.

If register has not been called yet, then this does nothing.

pub fn take(&self) -> Option<Waker>

Returns the last Waker passed to register, so that the user can wake it.

Sometimes, just waking the AtomicWaker is not fine grained enough. This allows the user to take the waker and then wake it separately, rather than performing both steps in one atomic action.

If a waker has not been registered, this returns None.

Trait Implementations

impl DerefMut for WakerCtrl

fn deref_mut(&mut self) -> &mut AtomicWaker

Mutably dereferences the value.

impl Deref for WakerCtrl

type Target = AtomicWaker

The resulting type after dereferencing.

fn deref(&self) -> &AtomicWaker

Dereferences the value.

impl ArcWake for WakerCtrl

fn wake_by_ref(arc_self: &Arc<Self>)

Indicates that the associated task is ready to make progress and should be polled.

fn wake(self: Arc<Self>)

Indicates that the associated task is ready to make progress and should be polled.

fn into_waker(self: Arc<Self>) -> Waker

Creates a Waker from an Arc, if T implements ArcWake.