[][src]Struct futures_util::task::AtomicWaker

pub struct AtomicWaker { /* fields omitted */ }

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.

AtomicWaker does not provide any memory ordering guarantees, as such the user should use caution and use other synchronization primitives to guard the result of the underlying computation.

Methods

impl AtomicWaker
[src]

Create an AtomicWaker.

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.

#![feature(pin, arbitrary_self_types, futures_api)]
use futures::future::Future;
use futures::task::{LocalWaker, 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>, lw: &LocalWaker) -> Poll<()> {
        // Register **before** checking `set` to avoid a race condition
        // that would result in lost notifications.
        self.waker.register(lw);

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

Calls wake on the last Waker passed to register.

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

Trait Implementations

impl Sync for AtomicWaker
[src]

impl Default for AtomicWaker
[src]

Returns the "default value" for a type. Read more

impl Send for AtomicWaker
[src]

impl Debug for AtomicWaker
[src]

Formats the value using the given formatter. Read more

Blanket Implementations

impl<T, U> Into for T where
    U: From<T>, 
[src]

Performs the conversion.

impl<T> From for T
[src]

Performs the conversion.

impl<T, U> TryFrom for T where
    T: From<U>, 
[src]

🔬 This is a nightly-only experimental API. (try_from)

The type returned in the event of a conversion error.

🔬 This is a nightly-only experimental API. (try_from)

Performs the conversion.

impl<T> Borrow for T where
    T: ?Sized
[src]

Important traits for &'_ mut I

Immutably borrows from an owned value. Read more

impl<T> Any for T where
    T: 'static + ?Sized
[src]

🔬 This is a nightly-only experimental API. (get_type_id)

this method will likely be replaced by an associated static

Gets the TypeId of self. Read more

impl<T> BorrowMut for T where
    T: ?Sized
[src]

Important traits for &'_ mut I

Mutably borrows from an owned value. Read more

impl<T, U> TryInto for T where
    U: TryFrom<T>, 
[src]

🔬 This is a nightly-only experimental API. (try_from)

The type returned in the event of a conversion error.

🔬 This is a nightly-only experimental API. (try_from)

Performs the conversion.