Struct nb_executor::Signals

pub struct Signals<'a, S> { /* private fields */ }

Signal state manager and event listener.

Signals maintains the signal state of an Executor. This consists of the raised signal set and the wakeup signal set. Upon polling the future, the raised signal set is frozen to the then-current value of the event mask, all bits in the wakeup signal set are removed from the event mask (atomically), and the wakeup signal set is cleared. Current poll functions which are driven by any of the raised signals will be attempted. If a poll function is not attempted or does not yet resolve to an output then its signal mask will be OR-ed into the wakeup signal set. The future won’t be polled again until a raised signal matches the wakeup signal set.

The type parameter S is an EventMask.

Delayed signals

The executor will examine the event mask after polling the future to check for any immediate updates. Since the raised signal set remains frozen during polling, any signal raised by the future itself won’t become visible until this happens. This also means that external events are not tested for until the future yields. Correct programs are not able to observe this behavior.

Implementations

impl<'a, S: EventMask> Signals<'a, S>

pub fn watch(pending: &'a Events<S>) -> Self

Associate a new Signals to an event mask.

This indirectly links the executor to the event mask, since creating an Executor requires a Signals.

pub async fn drive<T, E, F>(&self, signals: S, poll: F) -> Result<T, E> where
    F: Unpin + FnMut() -> Result<T, E>, 

Asynchronously drive a fallible poll function to completion.

The future produced by this method checks on each poll whether any of the signals in signals is present in the raised signal set. If that is the case, it invokes the poll function. If the poll function succeeds or fails with nb::Error::Other, the future completes immediately with that value. If the poll function returns nb::Error::WouldBlock, or if none of the signals in signals is present in the raised signal sent, then signals is added to the wakeup signal set and the future pends.

poll() must handle spurious calls gracefully. There is no guarantee that any of the intended effects of any signal in signals has actually taken place. poll() may not block.

pub async fn drive_infallible<T, F>(&self, signals: S, poll: F) -> T where
    F: Unpin + FnMut() -> Result<T, Infallible>, 

Asynchronously drive an infallible poll function to completion.

This is a variant of Signals::drive() intended for cases where there is no proper error type. Although drive(sig, poll).await.unwrap() works the same, it often requires explicit type annotations if poll is a closure. This method should be preferre in such cases, as well as when poll is a wrapper around option.ok_or(WouldBlock).