Class ExecutionSequencer

  • @Beta
    public final class ExecutionSequencer
    extends Object
    Serializes execution of tasks, somewhat like an "asynchronous synchronized block." Each enqueued callable will not be submitted to its associated executor until the previous callable has returned -- and, if the previous callable was an AsyncCallable, not until the Future it returned is done (successful, failed, or cancelled).

    This class has limited support for cancellation and other "early completion":

    • While calls to submit and submitAsync return a Future that can be cancelled, cancellation never propagates to a task that has started to run -- neither to the callable itself nor to any Future returned by an AsyncCallable. (However, cancellation can prevent an unstarted task from running.) Therefore, the next task will wait for any running callable (or pending Future returned by an AsyncCallable) to complete, without interrupting it (and without calling cancel on the Future). So beware: Even if you cancel every precededing Future returned by this class, the next task may still have to wait..
    • Once an AsyncCallable returns a Future, this class considers that task to be "done" as soon as that Future completes in any way. Notably, a Future is "completed" even if it is cancelled while its underlying work continues on a thread, an RPC, etc. The Future is also "completed" if it fails "early" -- for example, if the deadline expires on a Future returned from Futures.withTimeout(<V>, java.time.Duration, java.util.concurrent.ScheduledExecutorService) while the Future it wraps continues its underlying work. So beware: Your AsyncCallable should not complete its Future until it is safe for the next task to start.

    An additional limitation: this class serializes execution of tasks but not any listeners of those tasks.

    This class is similar to MoreExecutors.newSequentialExecutor(java.util.concurrent.Executor). This class is different in a few ways:

    • Each task may be associated with a different executor.
    • Tasks may be of type AsyncCallable.
    • Running tasks cannot be interrupted. (Note that newSequentialExecutor does not return Future objects, so it doesn't support interruption directly, either. However, utilities that use that executor have the ability to interrupt tasks running on it. This class, by contrast, does not expose an Executor API.)

    If you don't need the features of this class, you may prefer newSequentialExecutor for its simplicity and ability to accommodate interruption.