Enum Signal 

pub enum Signal {
    Open(Receiver),
    Closed(i32),
}

A one-time broadcast that can be awaited by many tasks. It is often used for coordinating shutdown across many tasks.

Each Signal tracks its lifecycle to enable proper shutdown coordination. To minimize overhead, it is recommended to wait on a reference to it (i.e. &mut signal) in loops rather than creating multiple Signals.

Example

Basic Usage

use commonware_runtime::{Spawner, Runner, deterministic, signal::Signaler};

let executor = deterministic::Runner::default();
executor.start(|context| async move {
    // Setup signaler and get future
    let (signaler, signal) = Signaler::new();

    // Signal shutdown
    signaler.signal(2);

    // Wait for shutdown in task
    let sig = signal.await.unwrap();
    println!("Received signal: {}", sig);
});

Advanced Usage

While Futures::Shared is efficient, there is still meaningful overhead to cloning it (i.e. in each iteration of a loop). To avoid a performance regression from introducing Signaler, it is recommended to wait on a reference to Signal (i.e. &mut signal).

Note: Polling the same Signal after it has resolved will always panic. When waiting on a reference to a Signal, ensure it is either fused or not polled again after it has yielded a result.

use commonware_macros::select;
use commonware_runtime::{Clock, Spawner, Runner, deterministic, Metrics, signal::Signaler};
use futures::channel::oneshot;
use std::time::Duration;

let executor = deterministic::Runner::default();
executor.start(|context| async move {
    // Setup signaler and get future
    let (signaler, mut signal) = Signaler::new();

    // Loop on the signal until resolved
    let (tx, rx) = oneshot::channel();
    context.with_label("waiter").spawn(|context| async move {
        loop {
            // Wait for signal or sleep
            select! {
                 sig = &mut signal => {
                     println!("Received signal: {}", sig.unwrap());
                     break;
                 },
                 _ = context.sleep(Duration::from_secs(1)) => {},
            };
        }
        let _ = tx.send(());
    });

    // Send signal
    signaler.signal(9);

    // Wait for task
    rx.await.expect("shutdown signaled");
});

Variants

Open(Receiver)

A signal that will resolve when the signaler marks it as resolved.

Closed(i32)

A signal that has been resolved with a known value.

Trait Implementations

impl Clone for Signal

fn clone(&self) -> Signal

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Future for Signal

type Output = Result<i32, Canceled>

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.