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

    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`.

# 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 {
            Self(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` [src]

#### `pub const fn new() -> AtomicWaker` [src]

Create an `AtomicWaker`.

#### `pub fn register(&self, waker: &Waker)` [src]

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
            }
        }
    }

#### `pub fn wake(&self)` [src]

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>` [src]

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 Debug for AtomicWaker` [src]

#### `pub fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>` [src]

Formats the value using the given formatter. Read more

### `impl Default for AtomicWaker` [src]

#### `pub fn default() -> AtomicWaker` [src]

Returns the “default value” for a type. Read more

### `impl Send for AtomicWaker` [src]

### `impl Sync for AtomicWaker` [src]

## Auto Trait Implementations

### `impl !RefUnwindSafe for AtomicWaker`

### `impl Unpin for AtomicWaker`

### `impl UnwindSafe for AtomicWaker`

## Blanket Implementations

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

#### `pub fn type_id(&self) -> TypeId` [src]

Gets the `TypeId` of `self`. Read more

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

#### `pub fn borrow(&self) -> &T` [src]

Immutably borrows from an owned value. Read more

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

#### `pub fn borrow_mut(&mut self) -> &mut T` [src]

Mutably borrows from an owned value. Read more

### `impl<T> From<T> for T` [src]

#### `pub fn from(t: T) -> T` [src]

Performs the conversion.

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

#### `pub fn into(self) -> U` [src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `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]

Performs the conversion.

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

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>` [src]

Performs the conversion.