Struct nb_executor::Park

pub struct Park<'a> { /* private fields */ }

A request to park the executor.

Parking is the mechanism by which the executor tries to wait for external event sources when no signal in the wakeup set is currently raised (see Signals). The executor might nonetheless resume immediately if a signal is raised before the atomic part of the park protocol takes place. Park functions implement the park protocol and must follow it strictly, you risk deadlocks otherwise.

The park protocol

• First, the executor determines that further progress is unlikely at this moment. The specifics of this are implementation details that must not be relied upon.

• The park function is called with a Park parameter.

• The park function enters a context wherein no external events may influence a correct decision to sleep or not. For example, a park function that does not sleep at all does not need to do anything here, since no external event can incorrectly change tha behavior. On the other hand, a park function that halts until a hardware interrupt occurs would need to enter an interrupt-free context to avoid deadlocks.

• The park function calls Park::race_free() while still in the event-safe context. This produces a Parked value that demonstrates the call to race_free().

• If the park function intends to block or sleep then it must first call Parked::is_idle() and may be allowed to sleep only if it returns true.

• If the park function is willing to sleep and is allowed to do so, it must atomically exit the event-safe context whilst entering the sleep state. A deadlock is again possible if both operations are not done atomically with respect to each other.

• If the park function sleeps, this state should be automatically exited when an external event occurs.

• The park function returns its Parked token.

• The executor resumes.

Implementations

impl<'a> Park<'a>

pub fn race_free(self) -> Parked<'a>

Promise that new events won’t race with sleeps and get a proof of parking.

Park functions must call this method to obtain the Parked object that they return, which also allows them to determine sleep permissibility. The caller promises that external events which may occur from the start of this call until optionally starting to sleep won’t result in race conditions.