io.smallrye.context.api

Annotation Type ManagedExecutorConfig

@Retention(value=RUNTIME)
 @Target(value={FIELD,METHOD,TYPE,PARAMETER})
public @interface ManagedExecutorConfig

Annotates a CDI injection point for a ManagedExecutor such that the container creates a new instance, which is identified within an application by its unique name. The unique name is generated as the fully qualified class name (with each component delimited by .) and the injection point's field name or method name and parameter position, all delimited by /, unless annotated with the NamedInstance qualifier, in which case the unique name is specified by the NamedInstance.value() attribute of that qualifier.

For example, the following injection points share a single ManagedExecutor instance,

   @Inject  @NamedInstance("exec1")  @ManagedExecutorConfig(maxAsync=5)
 ManagedExecutor executor;

  @Inject
 void setCompletableFuture( @NamedInstance("exec1") ManagedExecutor exec) {
     completableFuture = exec.newIncompleteFuture();
 }

  @Inject
 void setCompletionStage( @NamedInstance("exec1") ManagedExecutor exec) {
     completionStage = exec.supplyAsync(supplier);
 }
 
 

Alternatively, the following injection points each represent a distinct ManagedExecutor instance,

   @Inject  @ManagedExecutorConfig(propagated=ThreadContext.CDI)
 ManagedExecutor exec2;

  @Inject  @ManagedExecutorConfig(maxAsync=5)
 ManagedExecutor exec3;
 
 

When the application stops, the container automatically shuts down instances of ManagedExecutor that it created. The application can manually use the ExecutorService.shutdown() or ExecutorService.shutdownNow() methods to shut down a managed executor at an earlier point.

A ManagedExecutor will fail to inject, raising DefinitionException on application startup, if multiple injection points are annotated to create instances with the same name.

Author:

Matej Novotny

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
String[]	cleared Defines the set of thread context types to clear from the thread where the action or task executes.
int	maxAsync 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.
int	maxQueued Establishes an upper bound on the number of async actions and async tasks that can be queued up for execution.
String[]	propagated 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.

Element Detail

cleared

public abstract String[] cleared

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.

By default, no context is cleared/suspended from execution thread.

ThreadContext.ALL_REMAINING is automatically appended to the set of cleared context if the propagated() set does not include ThreadContext.ALL_REMAINING.

Constants for specifying some of the core context types are provided on ThreadContext. Other thread context types must be defined by the specification that defines the context type or by a related MicroProfile specification.

A ManagedExecutor must fail to inject, raising DefinitionException on application startup, if a context type specified within this set is unavailable or if the propagated() set includes one or more of the same types as this set.

Default:

{}

propagated

public abstract String[] propagated

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.

The default set of propagated thread context types is ThreadContext.ALL_REMAINING, which includes all available thread context types that support capture and propagation to other threads, except for those that are explicitly cleared.

Constants for specifying some of the core context types are provided on ThreadContext. Other thread context types must be defined by the specification that defines the context type or by a related MicroProfile specification.

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.

A ManagedExecutor must fail to inject, raising DefinitionException on application startup, if a context type specified within this set is unavailable or if the cleared() set includes one or more of the same types as this set.

Default:

"Remaining"

maxAsync

public abstract int maxAsync

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. Async actions and tasks remain queued until the ManagedExecutor starts executing them.

The default value of -1 indicates no upper bound, although practically, resource constraints of the system will apply.

A ManagedExecutor must fail to inject, raising DefinitionException on application startup, if the maxAsync value is 0 or less than -1.

Default:

-1

maxQueued

public abstract int maxQueued

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 -1 indicates no upper bound, although practically, resource constraints of the system will apply.

A ManagedExecutor must fail to inject, raising DefinitionException on application startup, if the maxQueued value is 0 or less than -1.

Default:

-1