Struct 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 process are implementation details that should 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 that 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 serves as proof of the call to race_free().

• If the park function intends to block or sleep, then it must first call Parked::is_idle(). It may be allowed to sleep only if that function 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 (only for blocking runners, see below).

• 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.

Delegating out of the park function

Blocking runners, such as Executor::block_on(), require that the park function’s event-safe context be exited in an atomic manner with respect to the start of whatever blocking operation. However, this requirement does not hold for Step as long as the park function never exits the event-safe context and it itself never blocks. Since Step::poll() will return after parking, the caller can perform potentially-blocking operations from the event-safe context. It must still release it atomically if it will sleep, though. With this technique it is even possible for the poll() caller to be an external event source.

Implementations

impl<'a> Park<'a>

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

Promise that new events won’t race with sleeps, then 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.