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,
threadContext.contextualFunction(function1)),
then the action runs with the already-captured context.
propagated from the thread
that creates the completion stage or marked to be cleared, 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 the executor 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 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.
Managed executors can forward all contextualised async tasks to a backing executor service
if set with ContextManager..
Otherwise, a new backing executor service may be created, unless the implementation has its own
default executor service.
| Modifier and Type | Class and Description |
|---|---|
| public static interface | ManagedExecutor.
Builder for |
| Modifier and Type | Method and Description |
|---|---|
| public static ManagedExecutor. | |
| public < result type of the completable future. U> CompletableFuture | Returns: the new completable future.result with which the completable future is completed. value)Returns a new CompletableFuture that is already completed with the specified value. |
| public < result type of the completion stage. U> CompletionStage | Returns: the new completion stage.result with which the completable future is completed. value)Returns a new CompletionStage that is already completed with the specified value. |
| public < completable future result type. T> CompletableFuture | Returns: the new completable future.a completable future whose completion triggers completion of the new completable
future that is created by this method. stage)
Returns a new |
| public < completion stage result type. T> CompletionStage | Returns: the new completion stage.a completion stage whose completion triggers completion of the new stage
that is created by this method. stage)
Returns a new |
| public < result type of the completable future. U> CompletableFuture | Returns: the new completable future.exception or error with which the completable future is completed. ex)Returns a new CompletableFuture that is already exceptionally completed with the specified Throwable. |
| public < result type of the completion stage. U> CompletionStage | Returns: the new completion stage.exception or error with which the stage is completed. ex)Returns a new CompletionStage that is already exceptionally completed with the specified Throwable. |
| public ThreadContext | Returns: a ThreadContext with the same propagation settings as this ManagedExecutor.Returns a |
| public < result type of the completion stage. U> CompletableFuture | |
| public CompletableFuture | |
| public < result type of the supplier and completion stage. U> CompletableFuture | Returns: the new completion stage.an action returning the value to be used to complete the returned completion stage. supplier)Returns a new CompletableFuture that is completed by a task running in this executor after it runs the given action. |
| builder | back to summary |
|---|---|
| public static ManagedExecutor. Creates a new
| |
| completedFuture | back to summary |
|---|---|
| public <U> CompletableFuture 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.
| |
| completedStage | back to summary |
|---|---|
| public <U> CompletionStage 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.
| |
| copy | back to summary |
|---|---|
| public <T> CompletableFuture
Returns a new The new completable future is backed by the ManagedExecutor upon which copy is invoked, which serves as the default asynchronous execution facility for the new stage and all dependent stages created from it, and so forth. When dependent stages are created from the new completable future, thread context is captured and/or cleared by the ManagedExecutor. 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 by supplying a pre-contextualized action. Invocation of this method does not impact thread context propagation for the supplied completable future or any dependent stages created from it, other than the new dependent completable future that is created by this method.
| |
| copy | back to summary |
|---|---|
| public <T> CompletionStage
Returns a new The new completion stage is backed by the ManagedExecutor upon which copy is invoked, which serves as the default asynchronous execution facility for the new stage and all dependent stages created from it, and so forth. When dependent stages are created from the new completion stage, thread context is captured and/or cleared by the ManagedExecutor. 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 by supplying a pre-contextualized action. Invocation of this method does not impact thread context propagation for the supplied stage or any dependent stages created from it, other than the new dependent completion stage that is created by this method.
| |
| failedFuture | back to summary |
|---|---|
| public <U> CompletableFuture 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.
| |
| failedStage | back to summary |
|---|---|
| public <U> CompletionStage 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.
| |
| getThreadContext | back to summary |
|---|---|
| public ThreadContext getThreadContext() Returns a
| |
| newIncompleteFuture | back to summary |
|---|---|
| public <U> CompletableFuture Returns a new incomplete 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.
| |
| runAsync | back to summary |
|---|---|
| public CompletableFuture 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.
| |
| supplyAsync | back to summary |
|---|---|
| public <U> CompletableFuture 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.
| |
Builder for ManagedExecutor instances.
Example usage:
ManagedExecutor executor = ManagedExecutor.builder()
.maxAsync(5)
.maxQueued(20)
.propagated(ThreadContext.SECURITY)
.build();
...
| Modifier and Type | Method and Description |
|---|---|
| public ManagedExecutor | Returns: new instance ofManagedExecutor.Builds a new |
| public ManagedExecutor. | |
| public ManagedExecutor. | Returns: the same builder instance upon which this method is invoked.upper bound on async completion stage actions and executor tasks. max)Establishes an upper bound on the number of async completion stage actions and async executor tasks that can be running at any given point in time. |
| public ManagedExecutor. | Returns: the same builder instance upon which this method is invoked.upper bound on async actions and tasks that can be queued. max)Establishes an upper bound on the number of async actions and async tasks that can be queued up for execution. |
| public ManagedExecutor. | Returns: the same builder instance upon which this method is invoked.types of thread context to capture and propagate. types)Defines the set of thread context types to capture from the thread that creates a dependent stage (or that submits a task) and which to propagate to the thread where the action or task executes. |
| build | back to summary |
|---|---|
| public ManagedExecutor build() Builds a new After All created instances of
| |
| cleared | back to summary |
|---|---|
| public ManagedExecutor. Defines the set of thread context types to clear from the thread where the action or task executes. The previous context is resumed on the thread after the action or task ends. This set replaces the For example, if the user specifies
Constants for specifying some of the core context types are provided
on The MicroProfile Config property,
| |
| maxAsync | back to summary |
|---|---|
| public ManagedExecutor. Establishes an upper bound on the number of async completion stage
actions and async executor tasks that can be running at any given point
in time. There is no guarantee that async actions or tasks will start
running immediately, even when the The default value of
| |
| maxQueued | back to summary |
|---|---|
| public ManagedExecutor. Establishes an upper bound on the number of async actions and async tasks that can be queued up for execution. Async actions and tasks are rejected if no space in the queue is available to accept them. The default value of
| |
| propagated | back to summary |
|---|---|
| public ManagedExecutor. Defines the set of thread context types to capture from the thread that creates a dependent stage (or that submits a task) and which to propagate to the thread where the action or task executes. This set replaces the Constants for specifying some of the core context types are provided
on The MicroProfile Config property, Thread context types which are not otherwise included in this set are cleared from the thread of execution for the duration of the action or task.
| |