[[EE_Concurrency_Utilities_Configuration]]
= EE Concurrency Utilities

ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

EE Concurrency Utilities (JSR 236) were introduced to
ease the task of writing multithreaded applications. Instances
of these utilities are managed by WildFly, and the related configuration.

[[context-services]]
== Context Services

The Context Service is a concurrency utility which creates contextual
proxies from existent objects. WildFly Context Services are also used to
propagate the context from a Jakarta EE application invocation thread, to
the threads internally used by the other EE Concurrency Utilities.
Context Service instances may be created using the subsystem XML
configuration:

[source,xml,options="nowrap"]
----
  <context-services>
    <context-service
 name="default"
 jndi-name="java:jboss/ee/concurrency/context/default"
 use-transaction-setup-provider="true" />
  </context-services>
----

The `name` attribute is mandatory, and it's value should be a unique
name within all Context Services.

The `jndi-name` attribute is also mandatory, and defines where in the
JNDI the Context Service should be placed.

The optional `use-trasaction-setup-provider` attribute indicates if the
contextual proxies built by the Context Service should suspend
transactions in context, when invoking the proxy objects, and its value
defaults to true.

Management clients, such as the WildFly CLI, may also be used to
configure Context Service instances. An example to `add` and `remove`
one named `other`:

[source,options="nowrap"]
----
/subsystem=ee/context-service=other:add(jndi-name=java\:jboss\/ee\/concurrency\/other)
/subsystem=ee/context-service=other:remove
----

[[managed-thread-factories]]
== Managed Thread Factories

The Managed Thread Factory allows Jakarta EE applications to create new
threads. WildFly Managed Thread Factory instances may also, optionally,
use a Context Service instance to propagate the Jakarta EE application
thread's context to the new threads. Instance creation is done through
the EE subsystem, by editing the subsystem XML configuration:

[source,xml,options="nowrap"]
----
  <managed-thread-factories>
    <managed-thread-factory
 name="default"
 jndi-name="java:jboss/ee/concurrency/factory/default"
 context-service="default"
 priority="1" />
  </managed-thread-factories>
----

The `name` attribute is mandatory, and it's value should be a unique
name within all Managed Thread Factories.

The `jndi-name` attribute is also mandatory, and defines where in the
JNDI the Managed Thread Factory should be placed.

The optional `context-service` references an existent Context Service by
its `name`. If specified then thread created by the factory will
propagate the invocation context, present when creating the thread.

The optional `priority` indicates the priority for new threads created
by the factory, and defaults to `5`.

Management clients, such as the WildFly CLI, may also be used to
configure Managed Thread Factory instances. An example to `add` and
`remove` one named `other`:

[source,options="nowrap"]
----
/subsystem=ee/managed-thread-factory=other:add(jndi-name=java\:jboss\/ee\/factory\/other)
/subsystem=ee/managed-thread-factory=other:remove
----

[[managed-executor-services]]
== Managed Executor Services

The Managed Executor Service is the Jakarta EE adaptation of Java SE
Executor Service, providing to Jakarta EE applications the functionality of
asynchronous task execution. WildFly is responsible to manage the
lifecycle of Managed Executor Service instances, which are specified
through the EE subsystem XML configuration:

[source,xml,options="nowrap"]
----
<managed-executor-services>
    <managed-executor-service
        name="default"
        jndi-name="java:jboss/ee/concurrency/executor/default"
        context-service="default"
        thread-factory="default"
        hung-task-threshold="60000"
        hung-task-termination-period="60000"
        core-threads="5"
        max-threads="25"
        keepalive-time="5000"
        queue-length="1000000"
        reject-policy="RETRY_ABORT" />
</managed-executor-services>
----

The `name` attribute is mandatory, and it's value should be a unique
name within all Managed Executor Services.

The `jndi-name` attribute is also mandatory, and defines where in the
JNDI the Managed Executor Service should be placed.

The optional `context-service` references an existent Context Service by
its `name`. If specified then the referenced Context Service will
capture the invocation context present when submitting a task to the
executor, which will then be used when executing the task.

The optional `thread-factory` references an existent Managed Thread
Factory by its `name`, to handle the creation of internal threads. If
not specified then a Managed Thread Factory with default configuration
will be created and used internally.

The mandatory `core-threads` provides the number of threads to keep in
the executor's pool, even if they are idle. If this is not defined or
is set to 0, the core pool size will be calculated based on the number
of available processors.

The optional `queue-length` indicates the number of tasks that can be
stored in the input queue. The default value is `0`, which means the
queue capacity is unlimited.

The executor's task queue is based on the values of the attributes
`core-threads` and `queue-length`:

* If `queue-length` is `0`, or `queue-length` is
`Integer.MAX_VALUE (2147483647)` and `core-threads` is `0`, direct
handoff queuing strategy will be used and a synchronous queue will be
created.
* If `queue-length` is `Integer.MAX_VALUE` but `core-threads` is not
`0`, an unbounded queue will be used.
* For any other valid value for `queue-length`, a bounded queue wil be
created.

The optional `hung-task-threshold` defines a runtime threshold value, in
milliseconds, for tasks to be considered hung by the executor.
A value of `0` will never consider tasks to be hung.

The optional `hung-task-termination-period` defines the period, in
milliseconds, for attempting the termination of hung tasks, by cancelling
their execution, and interrupting their executing threads. Please note
that the termination of a cancelled hung task is not guaranteed.
A value of `0`, which is the default, deactivates the periodic
cancellation of hung tasks. Management clients, such as the WildFly CLI,
may still be used to manually attempt the termination of hung tasks:
[source,options="nowrap"]
----
/subsystem=ee/managed-executor-service=other:terminate-hung-tasks
----

The optional `long-running-tasks` is a hint to optimize the execution of
long running tasks, and defaults to `false`.

The optional `max-threads` defines the the maximum number of threads
used by the executor, which defaults to Integer.MAX_VALUE (2147483647).

The optional `keepalive-time` defines the time, in milliseconds, that an
internal thread may be idle. The attribute default value is `60000`.

The optional reject-policy defines the policy to use when a task is
rejected by the executor. The attribute value may be the default
`ABORT`, which means an exception should be thrown, or `RETRY_ABORT`,
which means the executor will try to submit it once more, before
throwing an exception.

Management clients, such as the WildFly CLI, may also be used to
configure Managed Executor Service instances. An example to `add` and
`remove` one named `other`:

[source,options="nowrap"]
----
/subsystem=ee/managed-executor-service=other:add(jndi-name=java\:jboss\/ee\/executor\/other, core-threads=2)
/subsystem=ee/managed-executor-service=other:remove
----

[[managed-scheduled-executor-services]]
== Managed Scheduled Executor Services

The Managed Scheduled Executor Service is the Jakarta EE adaptation of Java
SE Scheduled Executor Service, providing to Jakarta EE applications the
functionality of scheduling task execution. WildFly is responsible to
manage the lifecycle of Managed Scheduled Executor Service instances,
which are specified through the EE subsystem XML configuration:

[source,xml,options="nowrap"]
----
<managed-scheduled-executor-services>
    <managed-scheduled-executor-service
        name="default"
        jndi-name="java:jboss/ee/concurrency/scheduler/default"
        context-service="default"
        thread-factory="default"
        hung-task-threshold="60000"
        core-threads="5"
        keepalive-time="5000"
        reject-policy="RETRY_ABORT" />
</managed-scheduled-executor-services>
----

The `name` attribute is mandatory, and it's value should be a unique
name within all Managed Scheduled Executor Services.

The `jndi-name` attribute is also mandatory, and defines where in the
JNDI the Managed Scheduled Executor Service should be placed.

The optional `context-service` references an existent Context Service by
its `name`. If specified then the referenced Context Service will
capture the invocation context present when submitting a task to the
executor, which will then be used when executing the task.

The optional `thread-factory` references an existent Managed Thread
Factory by its `name`, to handle the creation of internal threads. If
not specified then a Managed Thread Factory with default configuration
will be created and used internally.

The mandatory `core-threads` provides the number of threads to keep in
the executor's pool, even if they are idle. A value of `0` means there
is no limit.

The optional `hung-task-threshold` defines a runtime threshold value, in
milliseconds, for tasks to be considered hung by the executor.
A value of `0` will never consider tasks to be hung.

The optional `hung-task-termination-period` defines the period, in
milliseconds, for attempting the termination of hung tasks, by cancelling
their execution, and interrupting their executing threads. Please note
that the termination of a cancelled hung task is not guaranteed.
A value of `0`, which is the default, deactivates the periodic
cancellation of hung tasks. Management clients, such as the WildFly CLI,
may still be used to manually attempt the termination of hung tasks:
[source,options="nowrap"]
----
/subsystem=ee/managed-scheduled-executor-service=other:terminate-hung-tasks
----

The optional `long-running-tasks` is a hint to optimize the execution of
long running tasks, and defaults to `false`.

The optional `keepalive-time` defines the time, in milliseconds, that an
internal thread may be idle. The attribute default value is `60000`.

The optional reject-policy defines the policy to use when a task is
rejected by the executor. The attribute value may be the default
`ABORT`, which means an exception should be thrown, or `RETRY_ABORT`,
which means the executor will try to submit it once more, before
throwing an exception.

Management clients, such as the WildFly CLI, may also be used to
configure Managed Scheduled Executor Service instances. An example to
`add` and `remove` one named `other`:

[source,options="nowrap"]
----
/subsystem=ee/managed-scheduled-executor-service=other:add(jndi-name=java\:jboss\/ee\/scheduler\/other, core-threads=2)
/subsystem=ee/managed-scheduled-executor-service=other:remove
----
