Struct tokio::sync::Notify

pub struct Notify { /* private fields */ }

Notify a single task to wake up.

Notify provides a basic mechanism to notify a single task of an event. Notify itself does not carry any data. Instead, it is to be used to signal another task to perform an operation.

Notify can be thought of as a Semaphore starting with 0 permits. notified().await waits for a permit to become available, and notify() sets a permit if there currently are no available permits.

The synchronization details of Notify are similar to thread::park and Thread::unpark from std. A Notify value contains a single permit. notified().await waits for the permit to be made available, consumes the permit, and resumes. notify() sets the permit, waking a pending task if there is one.

If notify() is called before notfied().await, then the next call to notified().await will complete immediately, consuming the permit. Any subsequent calls to notified().await will wait for a new permit.

If notify() is called multiple times before notified().await, only a single permit is stored. The next call to notified().await will complete immediately, but the one after will wait for a new permit.

Examples

Basic usage.

use tokio::sync::Notify;
use std::sync::Arc;

#[tokio::main]
async fn main() {
    let notify = Arc::new(Notify::new());
    let notify2 = notify.clone();

    tokio::spawn(async move {
        notify2.notified().await;
        println!("received notification");
    });

    println!("sending notification");
    notify.notify();
}

Unbound mpsc channel.

use tokio::sync::Notify;

use std::collections::VecDeque;
use std::sync::Mutex;

struct Channel<T> {
    values: Mutex<VecDeque<T>>,
    notify: Notify,
}

impl<T> Channel<T> {
    pub fn send(&self, value: T) {
        self.values.lock().unwrap()
            .push_back(value);

        // Notify the consumer a value is available
        self.notify.notify();
    }

    pub async fn recv(&self) -> T {
        loop {
            // Drain values
            if let Some(value) = self.values.lock().unwrap().pop_front() {
                return value;
            }

            // Wait for values to be available
            self.notify.notified().await;
        }
    }
}

Implementations

impl Notify

pub fn new() -> Notify

Create a new Notify, initialized without a permit.

Examples

use tokio::sync::Notify;

let notify = Notify::new();

pub async fn notified(&self)

Wait for a notification.

Each Notify value holds a single permit. If a permit is available from an earlier call to notify(), then notified().await will complete immediately, consuming that permit. Otherwise, notified().await waits for a permit to be made available by the next call to notify().

Examples

use tokio::sync::Notify;
use std::sync::Arc;

#[tokio::main]
async fn main() {
    let notify = Arc::new(Notify::new());
    let notify2 = notify.clone();

    tokio::spawn(async move {
        notify2.notified().await;
        println!("received notification");
    });

    println!("sending notification");
    notify.notify();
}

pub fn notify(&self)

Notifies a waiting task

If a task is currently waiting, that task is notified. Otherwise, a permit is stored in this Notify value and the next call to notified().await will complete immediately consuming the permit made available by this call to notify().

At most one permit may be stored by Notify. Many sequential calls to notify will result in a single permit being stored. The next call to notified().await will complete immediately, but the one after that will wait.

Examples

use tokio::sync::Notify;
use std::sync::Arc;

#[tokio::main]
async fn main() {
    let notify = Arc::new(Notify::new());
    let notify2 = notify.clone();

    tokio::spawn(async move {
        notify2.notified().await;
        println!("received notification");
    });

    println!("sending notification");
    notify.notify();
}

Trait Implementations

impl Debug for Notify

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

Formats the value using the given formatter.

impl Default for Notify

fn default() -> Notify

Returns the “default value” for a type.