Interface ManagedExecutor
- All Superinterfaces:
Executor
,ExecutorService
A container-managed executor service that creates instances of CompletableFuture, which it backs as the default asynchronous execution facility, both for the CompletableFuture itself as well as all dependent stages created from it, as well as all dependent stages created from those, and so on.
Example usage:
ManagedExecutor executor = ManagedExecutor.builder().propagated(ThreadContext.APPLICATION).cleared(ThreadContext.ALL_REMAINING).build();
...
CompletableFuture<Integer> future = executor
.supplyAsync(supplier)
.thenApplyAsync(function1)
.thenApply(function2)
...
This specification allows for managed executors that propagate thread context as well as for
those that do not, which might offer better performance. If thread context propagation is
desired only for specific stages, or if you wish to override thread context propagation for
specific stages, the ThreadContext.contextual*
API methods can be used to
propagate thread context to individual actions.
Example of single action with context propagation:
CompletableFuture<?> future = executor .runAsync(runnable1) .thenRun(threadContext.contextualRunnable(runnable2)) .thenRunAsync(runnable3) ...
Managed executors that capture and propagate thread context must do so in a consistent and predictable manner, which is defined as follows,
-
If the supplied action is already contextual (for example,
threadContext.contextualFunction(function1))
, then the action runs with the already-captured context. -
Otherwise, each type of thread context is either
propagated
from the thread that creates the completion stage or marked to becleared
, according to the configuration of the managed executor that is the default asynchronous execution facility for the new stage and its parent stage. In the case that a managed executor is supplied as theexecutor
argument to a*Async
method, the supplied managed executor is used to run the action, but not to determine thread context propagation and clearing.
Each type of thread context is applied (either as cleared or as previously captured) to the thread that runs the action. The applied thread context is removed after the action completes, whether successfully or exceptionally, restoring the thread's prior context.
When dependent stages are created from the completion stage, and likewise from any dependent stages created from those, and so on, thread context is captured or cleared in the same manner. This guarantees that the action performed by each stage always runs under the thread context of the code that creates the stage, unless the user explicitly overrides this by supplying a pre-contextualized action.
Thread context is similarly captured, cleared, applied, and afterward restored for the
ExecutorService methods:
execute
, invokeAll
, invokeAny
, submit
This interface is intentionally kept compatible with ManagedExecutorService, with the hope that its methods might one day be contributed to that specification.
Managed executors that are created with the ManagedExecutor.Builder
or created for
injection into applications via CDI must support the life cycle methods, including:
awaitTermination, isShutdown, isTerminated, shutdown, shutdownNow.
The application must invoke shutdown
or shutdownNow
to terminate
the life cycle of each managed executor that it creates, once the managed executor is
no longer needed. When the application stops, the container invokes shutdownNow
for any remaining managed executors that the application did not already shut down.
The shutdown methods signal the managed executor that it does not need to remain active to
service subsequent requests and allow the container to properly clean up associated resources.
Managed executors which have a life cycle that is scoped to the container, including those obtained via mechanisms defined by EE Concurrency, must raise IllegalStateException upon invocation of the aforementioned life cycle methods, in order to preserve compatibility with that specification.
-
Nested Class Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic ManagedExecutor.Builder
builder()
Creates a newManagedExecutor.Builder
instance.<U> CompletableFuture<U>
completedFuture
(U value) Returns a new CompletableFuture that is already completed with the specified value.<U> CompletionStage<U>
completedStage
(U value) Returns a new CompletionStage that is already completed with the specified value.<U> CompletableFuture<U>
Returns a new CompletableFuture that is already exceptionally completed with the specified Throwable.<U> CompletionStage<U>
failedStage
(Throwable ex) Returns a new CompletionStage that is already exceptionally completed with the specified Throwable.<U> CompletableFuture<U>
Returns a new incompleteCompletableFuture
.Returns a new CompletableFuture that is completed by a task running in this executor after it runs the given action.<U> CompletableFuture<U>
supplyAsync
(Supplier<U> supplier) Returns a new CompletableFuture that is completed by a task running in this executor after it runs the given action.Methods inherited from interface java.util.concurrent.ExecutorService
awaitTermination, invokeAll, invokeAll, invokeAny, invokeAny, isShutdown, isTerminated, shutdown, shutdownNow, submit, submit, submit
-
Method Details
-
builder
Creates a newManagedExecutor.Builder
instance.- Returns:
- a new
ManagedExecutor.Builder
instance.
-
completedFuture
Returns a new CompletableFuture that is already completed with the specified value.
This executor is the default asynchronous execution facility for the new completion stage that is returned by this method and all dependent stages that are created from it, and all dependent stages that are created from those, and so forth.
- Type Parameters:
U
- result type of the completable future.- Parameters:
value
- result with which the completable future is completed.- Returns:
- the new completable future.
-
completedStage
Returns a new CompletionStage that is already completed with the specified value.
This executor is the default asynchronous execution facility for the new completion stage that is returned by this method and all dependent stages that are created from it, and all dependent stages that are created from those, and so forth.
- Type Parameters:
U
- result type of the completion stage.- Parameters:
value
- result with which the completable future is completed.- Returns:
- the new completion stage.
-
failedFuture
Returns a new CompletableFuture that is already exceptionally completed with the specified Throwable.
This executor is the default asynchronous execution facility for the new completion stage that is returned by this method and all dependent stages that are created from it, and all dependent stages that are created from those, and so forth.
- Type Parameters:
U
- result type of the completable future.- Parameters:
ex
- exception or error with which the completable future is completed.- Returns:
- the new completable future.
-
failedStage
Returns a new CompletionStage that is already exceptionally completed with the specified Throwable.
This executor is the default asynchronous execution facility for the new completion stage that is returned by this method and all dependent stages that are created from it, and all dependent stages that are created from those, and so forth.
- Type Parameters:
U
- result type of the completion stage.- Parameters:
ex
- exception or error with which the stage is completed.- Returns:
- the new completion stage.
-
newIncompleteFuture
Returns a new incomplete
CompletableFuture
.This executor is the default asynchronous execution facility for the new completion stage that is returned by this method and all dependent stages that are created from it, and all dependent stages that are created from those, and so forth.
- Type Parameters:
U
- result type of the completion stage.- Returns:
- the new completion stage.
-
runAsync
Returns a new CompletableFuture that is completed by a task running in this executor after it runs the given action.
This executor is the default asynchronous execution facility for the new completion stage that is returned by this method and all dependent stages that are created from it, and all dependent stages that are created from those, and so forth.
- Parameters:
runnable
- the action to run before completing the returned completion stage.- Returns:
- the new completion stage.
-
supplyAsync
Returns a new CompletableFuture that is completed by a task running in this executor after it runs the given action.
This executor is the default asynchronous execution facility for the new completion stage that is returned by this method and all dependent stages that are created from it, and all dependent stages that are created from those, and so forth.
- Type Parameters:
U
- result type of the supplier and completion stage.- Parameters:
supplier
- an action returning the value to be used to complete the returned completion stage.- Returns:
- the new completion stage.
-