Crate tokio_notify_aggregator

source ·
Expand description

Tokio Notify Aggregator

tokio_notify_aggregator provides a mechanism to aggregate multiple Tokio Notify instances into a single notification source. This allows for waiting on notifications from any of a set of Notify instances.

Usage

NotifyAggregator can be used in scenarios where you need to wait for notifications from multiple sources, but are not concerned with which specific source the notification came from.

To wait for notifications, NotifyAggregator mimics the API of Notify - that is a call to NotifyAggregator::notified can be awaited in the same manner as Notify::notified.

While a NotifyAggregator can be created and awaited on in a single statement, where appropriate it is recommended to create the aggregator and then re-await it as needed. This prevents (re)spawning of new tasks to handle each registered Notify instance.

The aggregator also includes a graceful shutdown mechanism. When the NotifyAggregator is dropped, it automatically signals all registered Notify tasks to stop, preventing potential resource leaks due to never ending tasks.

Examples

Basic usage involves creating a NotifyAggregator, adding Notify instances to it, and then awaiting notifications:

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

#[tokio::main]
async fn main() {
    let aggregator = NotifyAggregator::new();
    let notifier = Arc::new(Notify::new());
    aggregator.add_notifier(notifier.clone());

    // Wait for a notification
    aggregator.notified().await;
}

NotifyAggregator also supports initialisation from an iterator of Arc<Notify> instances and chained additions of Arc<Notify>.

Creating a NotifyAggregator from an iterator:

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

#[tokio::main]
async fn main() {
   let notifiers = vec![Arc::new(Notify::new()), Arc::new(Notify::new())];
   let aggregator = NotifyAggregator::from_iter(notifiers.into_iter());

   // Wait for a notification
   aggregator.notified().await;
}

Chained addition of Arc<Notify> instances. If only a single notification requires awaiting, creation and waiting be done as a single statement:

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

#[tokio::main]
async fn main() {
    let notifier1 = Arc::new(Notify::new());
    let notifier2 = Arc::new(Notify::new());

    // Create a temporary aggregator, add notifiers, and await a notification
    NotifyAggregator::new()
        .add_notifier(notifier1.clone())
        .add_notifier(notifier2.clone())
        .notified().await;
}

Structs