Struct AtomicWaker

struct AtomicWaker { ... }

A synchronization primitive for task wakeup.

Sometimes the task interested in a given event will change over time. An AtomicWaker can coordinate concurrent notifications with the consumer potentially "updating" the underlying task to wake up. This is useful in scenarios where a computation completes in another thread and wants to notify the consumer, but the consumer is in the process of being migrated to a new logical task.

Consumers should call register before checking the result of a computation and producers should call wake after producing the computation (this differs from the usual thread::park pattern). It is also permitted for wake to be called before register. This results in a no-op.

A single AtomicWaker may be reused for any number of calls to register or wake.

Memory ordering

Calling register "acquires" all memory "released" by calls to wake before the call to register. Later calls to wake will wake the registered waker (on contention this wake might be triggered in register).

For concurrent calls to register (should be avoided) the ordering is only guaranteed for the winning call.

Examples

Here is a simple example providing a Flag that can be signalled manually when it is ready.

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

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

#[derive(Clone)]
struct Flag(Arc<Inner>);

impl Flag {
    pub fn new() -> Self {
        Flag(Arc::new(Inner {
            waker: AtomicWaker::new(),
            set: AtomicBool::new(false),
        }))
    }

    pub fn signal(&self) {
        self.0.set.store(true, Relaxed);
        self.0.waker.wake();
    }
}

impl Future for Flag {
    type Output = ();

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
        // quick check to avoid registration if already done.
        if self.0.set.load(Relaxed) {
            return Poll::Ready(());
        }

        self.0.waker.register(cx.waker());

        // Need to check condition **after** `register` to avoid a race
        // condition that would result in lost notifications.
        if self.0.set.load(Relaxed) {
            Poll::Ready(())
        } else {
            Poll::Pending
        }
    }
}

Implementations

impl AtomicWaker

const fn new() -> Self

Create an AtomicWaker.

fn register(self: &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::Relaxed;
use std::pin::Pin;

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

impl Future for Flag {
    type Output = ();

    fn poll(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(Relaxed) {
            Poll::Ready(())
        } else {
            Poll::Pending
        }
    }
}

fn wake(self: &Self)

Calls wake on the last Waker passed to register.

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

fn take(self: &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.

impl Debug for AtomicWaker

fn fmt(self: &Self, f: &mut Formatter<'_>) -> Result

impl Default for AtomicWaker

fn default() -> Self

impl Freeze for AtomicWaker

impl RefUnwindSafe for AtomicWaker

impl Send for AtomicWaker

impl Sync for AtomicWaker

impl Unpin for AtomicWaker

impl UnsafeUnpin for AtomicWaker

impl UnwindSafe for AtomicWaker

impl<T> Any for AtomicWaker

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for AtomicWaker

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for AtomicWaker

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> From for AtomicWaker

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into for AtomicWaker

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for AtomicWaker

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for AtomicWaker

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>