Struct WakeFlag 

pub struct WakeFlag { /* private fields */ }

A Listener destination which can wake an async task.

This is similar to an async MPSC channel except that it carries no data, only wakeups. Like a channel, it has a sending side WakeFlagListener, a receiving side WakeFlag, and either side can notice when the other is closed (dropped).

Its intended use is to allow a looping task to sleep until it needs to take an action.

WakeFlag uses only atomic operations and no locks, and therefore may be used on no_std platforms. It is Send and Sync regardless of whether the "sync" crate feature is enabled.

Example

In this async code sample, we wake a task which updates output_cell based on the contents of input_cell:

use futures::join;
use nosy::{Source as _, unsync::Cell, future::WakeFlag};

let input_cell: Cell<i32> = Cell::new(0);
let input_source = input_cell.as_source();
let output_cell: Cell<i32> = Cell::new(0);
let output_source = output_cell.as_source();

let mut flag = WakeFlag::listening(true, &input_source);

join!(
    async move {
        // Woken task.
        // This async block owns `flag`, `input_source`, and `output_cell`.
        // Its loop will exit when it is impossible to have any more work to do,
        // that is, when `input_cell` is dropped.

        while flag.wait().await {
            // In a real application this might be some substantial computation.
            output_cell.set_if_unequal(input_source.get() * 10);
        }
    },
    async move {
        // Writing task.
        // This async block owns `input_cell`, and drops it when done making
        // changes.
        //
        // (Note: This “yield, then expect the result to have been computed
        // by now” strategy is not reliable, and therefore not appropriate,
        // in more complex async programs. It is used here only to prove
        // that the computation is actually being done in a reasonably short
        // example.)

        input_cell.set(1);
        yield_now().await;
        assert_eq!(output_source.get(), 10);

        input_cell.set(2);
        yield_now().await;
        assert_eq!(output_source.get(), 20);
    },
);

Implementations

impl WakeFlag

pub fn new(wake_immediately: bool) -> (Self, WakeFlagListener)

Constructs a WakeFlag and paired WakeFlagListener.

If wake_immediately is true, then the waiting task will be woken on the first call to wait(), even if no message has been received.

pub fn listening<L>(wake_immediately: bool, source: L) -> Self

where L: Listen, L::Listener: FromListener<WakeFlagListener, L::Msg>,

Constructs a WakeFlag with the given initial state and call Listen::listen() with its listener.

This is a convenience for calling WakeFlag::new() followed by source.listen(listener).

pub async fn wait(&mut self) -> bool

Suspend the current async task until at least one message is received, messages have already been received since the last call to wait(), or no more messages will arrive.

When a message is received, returns true. When no more messages will be received because all listeners have been dropped, returns false; afterward, calls to wait() will always immediately return false.

This function is “cancellation safe”: if the future is dropped before it completes, there is no effect on the state of the WakeFlag, as if wait() had never been called at all.

pub fn notify(&self)

Set the flag, causing the next call to wait() to return immediately.

This is equivalent to calling .receive(&[()]) on the listener, but can be done without access to the listener. It may be useful in situations where the task wishes to immediately wake again for some reason, without having separate logic for that.

Trait Implementations

impl Debug for WakeFlag

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

Formats the value using the given formatter.

impl Pointer for WakeFlag

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

Formats the value using the given formatter.

impl Stream for WakeFlag

As a Stream, WakeFlag will produce () once for each time WakeFlag::wait() would produce true.

type Item = ()

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.