ExecutorProtocol

public protocol ExecutorProtocol : AnyObject

A protocol that defines objects that execute futures.

Executors provide the context in which futures execute. This context may be the current or a background thread, a Dispatch queue, a run loop, etc. Executors typically enqueue submitted futures in a ready to run queue and immediately return to the caller. This queue is later on consumed by the executor in its execution context, driving futures to completion by polling them. The polling algorithm is roughly:

var context = self.makeContext()
while var future = self.readyToRunQueue.pop() {
    if future.poll(&context).isReady {
        self.drop(future)
    } else {
        self.pendingFutures.push(future)
    }
}

Futures that are ready to run are polled by the executor. If the future returns that it completed (see Poll), it is let go by the executor, which causes the future and associated resources to be released. Otherwise, it is added into a pending futures registry. Before returning, the future registers the context’s waker (see Context and WakerProtocol) to receive a notification when the external event the future is waiting on fires. As a result of the notification, the future is added back into the ready to run queue and the process repeats until the future signifies completion.

Futures are submitted for execution via the trySubmit(_:) method of an executor. Executors guarantee that submitted futures will be executed asynchronously. In other words, trySubmit(_:) merely schedules the future to be executed at some point in the future and returns to the caller immediately. This is an important invariant that custom implementations must also maintain, since it removes all concerns about reentrancy.

Executors may deny to receive the future, in which case trySubmit(_:) returns an appropriate error of type Failure. This can be the case when the executor is shutting down or is at capacity and needs to provide backpressure. Executors that never fail, declare their Failure type as Never.

This protocol makes no guarantees on the safety of concurrent calls to trySubmit(_:). Each executor implementation is free to declare support for concurrent submissions, documenting the fact accordingly. This ambiguity is not a problem in practice since you typically use concrete executor types so you always know the specifics. The built-in QueueExecutor is an executor that supports concurrent submissions.