Struct nb_executor::Executor

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

A single-threaded, single-future async executor.

Typical setup

• First, an event mask is created with Events::default(). Event masks are Send + Syncand shared references to them are enough for all operations, so they work well asstatic` items or other types of shared state. Distribute event mask references to the external event sources and keep one for the executor.

• The event mask is then watched with Signals::watch(). The resulting Signals is Send + !Sync. This means that operations become limited to one thread of execution from this point on, so this is usually done in some type of initialization or main function instead of in a shared or global context.

• A new executor is bound with Executor::bind(). Executors are !Send + !Sync: neither it nor the associated Signals may escape the current thread. This makes them appropriate for construction at the use site.

• A future is created. It needs a reference to the Signals object in order to drive poll functions, making it !Sync too.

• Finally, Executor::run_with_park() blocks and resolves the future while external event sources direct it through the event mask, possibly with help from the park function.

Implementations

impl<'a, S> Executor<'a, S>

pub fn bind(signals: &'a Signals<'_, S>) -> Self

Create a new executor with a given signal source.

The executor will be constructed with a waker that does nothing. It can be replaced by calling Executor::with_waker().

pub fn with_waker(&mut self, waker: Waker) -> &mut Self

Replaces the executor’s waker with a custom one.

No restrictions are imposed on the waker: nb-executor does not use wakers at all. Application code may define some communication between it and the park function.

impl<S> Executor<'_, S>

pub fn run_with_park<F, P>(&mut self, future: F, park: P) -> F::Output where
    F: Future,
    P: FnMut(Park<'_>) -> Parked<'_>, 

Execute a future on this executor, parking when no progress is possible.

This method will block until the future resolves. There are two possible states of operation while the future is executed:

• Polling: The future’s poll() method is called in order to attempt to resolve it. The signal state is prepared as documented in Signals when switching to the polling state. The next state after polling is unspecified, but will eventually lead to parking if the future pends consistently.

• Parking: This state is entered when useful work is unlikely at the current time. For details, see the parking protocol in Park. park must adhere to this protocol.

On method enter, the state is set to polling with an all-ones wakeup signal set. This ensures that all driven poll functions are called at least once.

pub fn run_busy<F: Future>(&mut self, future: F) -> F::Output

Execute a future in a busy-waiting loop.

This is equivalent to calling Executor::run_with_park() with a park function that never sleeps. This is most likely the wrong way to do whatever you intend, prefer to define a proper wake function.