Package com.google.common.util.concurrent

Class ExecutionSequencer

java.lang.Object

com.google.common.util.concurrent.ExecutionSequencer

public final class ExecutionSequencer
extends java.lang.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(com.google.common.util.concurrent.ListenableFuture<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.

Since:

26.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
(package private) static class	ExecutionSequencer.RunningState
private static class	ExecutionSequencer.TaskNonReentrantExecutor	This class helps avoid a StackOverflowError when large numbers of tasks are submitted with MoreExecutors.directExecutor().
private static class	ExecutionSequencer.ThreadConfinedTaskQueue	This object is unsafely published, but avoids problematic races by relying exclusively on the identity equality of its Thread field so that the task field is only accessed by a single thread.

Field Summary

Fields

Modifier and Type	Field	Description
private ExecutionSequencer.ThreadConfinedTaskQueue	latestTaskQueue
private java.util.concurrent.atomic.AtomicReference<ListenableFuture<java.lang.Void>>	ref	This reference acts as a pointer tracking the head of a linked list of ListenableFutures.

Constructor Summary

Constructors

Modifier	Constructor	Description
private	ExecutionSequencer()

Method Summary

Modifier and Type	Method	Description
static ExecutionSequencer	create()	Creates a new instance.
<T> ListenableFuture<T>	submit(java.util.concurrent.Callable<T> callable, java.util.concurrent.Executor executor)	Enqueues a task to run when the previous task (if any) completes.
<T> ListenableFuture<T>	submitAsync(AsyncCallable<T> callable, java.util.concurrent.Executor executor)	Enqueues a task to run when the previous task (if any) completes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ref

private final java.util.concurrent.atomic.AtomicReference<ListenableFuture<java.lang.Void>> ref

This reference acts as a pointer tracking the head of a linked list of ListenableFutures.

latestTaskQueue

private ExecutionSequencer.ThreadConfinedTaskQueue latestTaskQueue

Constructor Detail

ExecutionSequencer

private ExecutionSequencer()

Method Detail

create

public static ExecutionSequencer create()

Creates a new instance.

submit

public <T> ListenableFuture<T> submit(java.util.concurrent.Callable<T> callable,
                                      java.util.concurrent.Executor executor)

Enqueues a task to run when the previous task (if any) completes.

Cancellation does not propagate from the output future to a callable that has begun to execute, but if the output future is cancelled before Callable.call() is invoked, Callable.call() will not be invoked.

submitAsync

public <T> ListenableFuture<T> submitAsync(AsyncCallable<T> callable,
                                           java.util.concurrent.Executor executor)

Enqueues a task to run when the previous task (if any) completes.

Cancellation does not propagate from the output future to the future returned from callable or a callable that has begun to execute, but if the output future is cancelled before AsyncCallable.call() is invoked, AsyncCallable.call() will not be invoked.