Thread Pool Configuration in AS 6.x

Table of Contents

Deployment Descriptor Format

The Threads deployment descriptor is governed by an XML schema which defines and documents each element.  The full schema can be found here (2.0.0.CR1).  Since the deployment descriptor utilizes the JBossMC namespace-based configuration parsing, you have two options for how the descriptor may be written.

Standalone Descriptor

A standalone descriptor may be written, whose name is, or ends with, "jboss-threads.xml".  The format of such a descriptor will look like this:

<?xml version="1.0" encoding="UTF-8"?>

<threads xmlns="urn:jboss:threads:2.0">
    <!-- Descriptor contents here -->
</threads>

Inclusion in a Microcontainer Deployment

Due to the way that the Microcontainer processes XML deployments, it is possible to include your threads descriptor in the midst of a regular POJO deployment, like this:

<?xml version="1.0" encoding="UTF-8"?>

<deployment xmlns="urn:jboss:bean-deployer:2.0">
    <!-- JBossMC elements here -->
    <threads xmlns="urn:jboss:threads:2.0">
        <!-- Threads deployment elements here -->
    </threads>
</deployment>

Deploying Threading Components

Simple Thread Components

These are the basic building blocks of a standard threaded Java application.

Single Thread Deployment

To deploy a single thread to be executed, use the "thread" element:

<?xml version="1.0" encoding="UTF-8"?>

<threads xmlns="urn:jboss:threads:2.0">
    <thread name="MyProgramThread">
        <task name="MyRunnablePojo"/>
    </thread>
</threads>

Attributes

• name - required string attribute; specifies the bean deployment name for the thread.
• daemon - optional boolean attribute; specifies whether the thread should or should not be a daemon thread.  If not specified, the daemon setting is inherited from the thread factory.
• priority - optional integer attribute, valid range is 1 through 10 inclusive.  Specifies the priority value for the thread.  If not specified, the priority is inherited from the thread factory.

Child Elements

• task - required; specifies the bean deployment name of the Runnable task that this thread should execute.  Attributes of this element are: 
  • name - required string attribute; specifies the bean deployment name of the Runnable to use.
• thread-factory - optional; specifies the bean deployment name of the thread factory that should be used to create the thread.  The target object should implement java.util.concurrent.ThreadFactory.  If not specified, the system default thread factory is used.  Attributes of this element are: 
  • name - required string attribute; specifies the bean deployment name of the ThreadFactory to use
• exception-handler - optional; specifies the bean deployment name of the uncaught exception handler to use for the thread.  Attributes of this element are: 
  • name - required string attribute; specifies the bean deployment name of the UncaughtExceptionHandler to use
• task-filter - optional; specifies a task filter to be applied to the Runnable of this thread.  See Task Filters for more information.

Thread Group Deployment

To deploy a named java.lang.ThreadGroup instance, use the "thread-group" element:

<?xml version="1.0" encoding="UTF-8"?>

<threads xmlns="urn:jboss:threads:2.0">
    <!-- Define a parent and child thread group -->
    <thread-group name="ParentThreadGroup"/>

    <thread-group name="ChildThreadGroup">
        <parent-thread-group name="ParentThreadGroup"/>
    </thread-group>
</threads>

Attributes

• name - required string attribute; specifies the bean deployment name for the thread.
• group-name - optional string attribute; specifies the thread group name, if it is different from the bean deployment name.
• daemon - optional boolean attribute; specifies whether child threads should or should not be daemon threads.  If not specified, the daemon setting is inherited from the parent thread group.
• max-priority - optional integer attribute, valid range is 1 through 10 inclusive.  Specify a hard upper limit on thread priority for threads within this group and child groups.

Child Elements

• parent-thread-group - optional; specifies the bean deployment name of the parent thread group.  Attributes of this element are: 
  • name - required string attribute; specifies the bean deployment name.

Thread Factory Deployment

To deploy a configurable implementation of java.util.concurrent.ThreadFactory, use the "thread-factory" element:

<?xml version="1.0" encoding="UTF-8"?>

<threads xmlns="urn:jboss:threads:2.0">
    <thread-factory name="MyThreadFactory" thread-name-pattern="My Thread %t">
        <thread-group name="ChildThreadGroup"/>
    </thread-factory>
</threads>

Attributes

• name - required string attribute; specifies the bean deployment name for the thread.
• daemon - optional boolean attribute; specifies whether created threads should or should not be daemon threads.  If not specified, the daemon setting is inherited from the associated thread group.
• thread-name-pattern - optional string attribute; specifies a pattern which is used to create a name for the thread.  The pattern may contain the following format sequences:
  • %% - emit a % character
  • %t - emit the per-factory thread sequence number (counts up from 0; every factory has its own sequence)
  • %g - emit the global thread sequence number (counts up from 0 across all thread factories)
  • %f - emit the factory number (counts up from 0, once for each factory instance, so the value is unique for each factory)
  • %p - emit the complete thread group path name, seperated by ":" characters
  • %i - emit the thread ID
  • %G - emit the thread group name
• priority - optional integer attribute, valid range is 1 through 10 inclusive.  Specifies the priority value for created threads.  If not specified, the priority is inherited from the thread factory.

Child Elements

• thread-group - optional; specifies the bean deployment name of the thread group.  If not specified, the system default thread group is used.  Attributes of this element are:
  • name - required string attribute; specifies the bean deployment name.
• exception-handler - optional; specifies the bean deployment name of the uncaught exception handler to use for the thread.  Attributes of this element are:
  • name - required string attribute; specifies the bean deployment name.
• task-filter - optional; specifies a task filter to be applied to the Runnable of this thread.  See Task Filters for more information.

Executor Deployment Types

These deployment types represent various types of java.util.concurrent.Executor implementations - including thread pools and special task-ordering types.

Thread Factory Executor

This is the simplest type of executor which runs each task in a separate thread, which exits when the task is complete.  It is declared using the "thread-factory-executor" element:

<?xml version="1.0" encoding="UTF-8"?>

<threads xmlns="urn:jboss:threads:2.0">
    <thread-factory name="MyThreadFactory" thread-name-pattern="My Thread %t">
        <thread-group name="MyThreadGroup"/>
    </thread-factory>

    <!-- This is the Executor instance -->
    <thread-factory-executor name="MyExecutor">
        <thread-factory name="MyThreadFactory"/>
        <max-threads count="100" per-cpu="100"/>
    </thread-factory-executor>
</threads>

Attributes

• name - required string attribute; specifies the bean deployment name for the executor
• blocking - optional boolean attribute; specifies whether submitting threads should block when submitting tasks if the maximum number of threads is already running.

Child Elements

• thread-factory - required; specifies the bean deployment name of the thread factory that should be used to create the threads used by this executor.  The target object should implement java.util.concurrent.ThreadFactory.  If not specified, the system default thread factory is used.  Attributes of this element are:
  • name - required string attribute; specifies the bean deployment name of the ThreadFactory to use
• max-threads - optional; specifies the maximum number of threads which may be running concurrently.  Attributes are:
  • count - optional float attribute; specifies a fixed quantity.
  • per-cpu - optional float attribute; specifies a quantity which is multiplied by the number of available CPUs.  Both quantities are then added and the final result is the actual count used.
• task-filter - optional; specifies a task filter to be applied to tasks accepted by this Executor.  See Task Filters for more information.

Unbounded-Queue Thread Pool Executor

This type of thread pool always accepts tasks.  If fewer than the maximum number of threads are running, a new thread is started up to run the submitted task; otherwise, the task is placed into an unbounded FIFO queue to be executed when a thread becomes available.  Note that the single-thread executor type provided by Executors.singleThreadExecutor() is essentially an unbounded-queue executor with a thread limit of one.  This type of executor is deployed using the "unbounded-queue-thread-pool-executor" element:

<?xml version="1.0" encoding="UTF-8"?>

<threads xmlns="urn:jboss:threads:2.0">

    <thread-factory name="MyThreadFactory"/>

    <!-- Here is the Executor definition: -->
    <unbounded-queue-thread-pool-executor name="ThreadPool">
        <thread-factory name="MyThreadFactory"/>
        <max-threads count="10" per-cpu="3"/>
        <keepalive-time time="30" unit="seconds"/>
    </unbounded-queue-thread-pool-executor>
</threads>

Attributes

• name - required string attribute; specifies the bean deployment name for the executor

Child Elements

• max-threads - required; specifies the maximum number of threads which may be running concurrently.  Attributes are:
  • count - optional float attribute; specifies a fixed quantity.
  • per-cpu - optional float attribute; specifies a quantity which is multiplied by the number of available CPUs.  Both quantities are then added and the final result is the actual count used.
• keepalive-time - optional; specifies the length of time after which idle threads will exit.  Attributes are:
  • time - required integer attribute; specifies the amount of time
  • unit - required string attribute; specifies the time unit, e.g. "seconds", "ms", "min", etc.
• thread-factory - optional; specifies the bean deployment name of the thread factory that should be used to create the threads used by this executor.  The target object should implement java.util.concurrent.ThreadFactory.  If not specified, the system default thread factory is used.  Attributes of this element are:
  • name - required string attribute; specifies the bean deployment name of the ThreadFactory to use
• task-filter - optional; specifies a task filter to be applied to tasks accepted by this Executor.  See Task Filters for more information.

Bounded-Queue Thread Pool Executor

This is the most complex executor type.  This type of executor maintains a fixed-length queue and two pool sizes: a "core" size and a "maximum" size.  When a task is accepted, if the number of running pool threads is less than the "core" size, a new thread is started to execute the task.  Otherwise, if space remains in the queue, the task is placed in the queue.  Otherwise, if the number of running pool threads is less than the "maximum" size, a new thread is started to execute the task.  Otherwise, if blocking is enabled on the executor, the calling thread will block until space becomes available in the queue.  Otherwise, the task is delegated to the handoff executor, if one is configured.  Otherwise, the task is rejected.

The bounded-queue executor is configured via the "bounded-queue-thread-pool-executor" element:

<?xml version="1.0" encoding="UTF-8"?>

<threads xmlns="urn:jboss:threads:2.0">

    <thread-factory name="MyThreadFactory"/>

    <bounded-queue-thread-pool-executor name="ThreadPool" blocking="true">
        <thread-factory name="MyThreadFactory"/>
        <queue-length count="500" per-cpu="200"/>
        <core-threads count="5" per-cpu="2"/>
        <max-threads count="10" per-cpu="3"/>
        <keepalive-time time="30" unit="seconds"/>
    </bounded-queue-thread-pool-executor>
</threads>

Attributes

• name - required string attribute; specifies the bean deployment name for the executor
• allow-core-timeout - optional boolean attribute; specifies whether the configured keepalive-time applies to all threads (true), or only threads which exceed the core count (false); default is false
• blocking - optional boolean attribute; specifies whether submitting threads should block if the task cannot be immediately accepted; default is false

Child Elements

• core-threads - optional; specifies the size of the core pool size.  If omitted, the value will be equal to the value given for the "max-threads" element.  Attributes are:
  • count - optional float attribute; specifies a fixed quantity.
  • per-cpu - optional float attribute; specifies a quantity which is multiplied by the number of available CPUs.  Both quantities are then added and the final result is the actual count used.
• queue-length - required; specifies the fixed length of the task queue.  Attributes are:
  • count - optional float attribute; specifies a fixed quantity.
  • per-cpu - optional float attribute; specifies a quantity which is multiplied by the number of available CPUs.  Both quantities are then added and the final result is the actual count used.
• max-threads - required; specifies the maximum number of threads in the pool.  Attributes are:
  • count - optional float attribute; specifies a fixed quantity.
  • per-cpu - optional float attribute; specifies a quantity which is multiplied by the number of available CPUs.  Both quantities are then added and the final result is the actual count used.
• keepalive-time - optional; specifies the length of time after which idle threads will exit.  Attributes are:
  • time - required integer attribute; specifies the amount of time
  • unit - required string attribute; specifies the time unit, e.g. "seconds", "ms", "min", etc.
• thread-factory - optional; specifies the bean deployment name of the thread factory that should be used to create the threads used by this executor.  The target object should implement java.util.concurrent.ThreadFactory.  If not specified, the system default thread factory is used.  Attributes of this element are:
  • name - required string attribute; specifies the bean deployment name of the ThreadFactory to use
• handoff-executor - optional; specifies the bean deployment name of an executor which should handle tasks if this executor cannot immediately accept them.  JBossAS 6.x provides a direct executor called "DirectExecutor" which is always available if the submitting thread should execute the task.  Attributes of this element are:

• name - required string attribute; specifies the bean deployment name of the delegate Executor to use
• task-filter - optional; specifies a task filter to be applied to tasks accepted by this Executor.  See Task Filters for more information.

Queueless Thread Pool Executor

Sometimes, a simple thread pool is desired which runs tasks in separate threads, reusing threads as they complete their tasks with no intervening queue.  This type of pool is ideal for handling tasks which are long-running, perhaps utilizing blocking I/O, since tasks are always started immediately upon acceptance rather than accepting a task and then delaying its execution until other running tasks have completed.  This type of executor is declared using the "queueless-thread-pool-executor" element:

<?xml version="1.0" encoding="UTF-8"?>

<threads xmlns="urn:jboss:threads:2.0">

    <thread-factory name="MyThreadFactory"/>

    <queueless-thread-pool-executor name="MyExecutor">
        <max-threads count="200" per-cpu="500"/>
        <thread-factory name="MyThreadFactory"/>
    </queueless-thread-pool-executor>
</threads>

Attributes

• name - required string attribute; specifies the bean deployment name for the executor
• blocking - optional boolean attribute; specifies whether submitting threads should block if the task cannot be immediately accepted; default is false

Child Elements

• max-threads - required; specifies the maximum number of threads in the pool.  Attributes are:

• count - optional float attribute; specifies a fixed quantity.
• per-cpu - optional float attribute; specifies a quantity which is multiplied by the number of available CPUs.  Both quantities are then added and the final result is the actual count used.
• keepalive-time - optional; specifies the length of time after which idle threads will exit.  Attributes are:

• time - required integer attribute; specifies the amount of time
• unit - required string attribute; specifies the time unit, e.g. "seconds", "ms", "min", etc.
• thread-factory - optional; specifies the bean deployment name of the thread factory that should be used to create the threads used by this executor.  The target object should implement java.util.concurrent.ThreadFactory.  If not specified, the system default thread factory is used.  Attributes of this element are:
  • name - required string attribute; specifies the bean deployment name of the ThreadFactory to use
• handoff-executor - optional; specifies the bean deployment name of an executor which should handle tasks if this executor cannot immediately accept them.  JBossAS 6.x provides a direct executor called "DirectExecutor" which is always available if the submitting thread should execute the task.  Attributes of this element are:
  • name - required string attribute; specifies the bean deployment name of the delegate Executor to use
• task-filter - optional; specifies a task filter to be applied to tasks accepted by this Executor.  See Task Filters for more information.

Scheduled Executor

This is a special type of executor whose purpose is to execute tasks at specific times and time intervals, based on the java.util.concurrent.ScheduledThreadPoolExecutor class.  This type of executor is configured with the "scheduled-thread-pool-executor" element:

<?xml version="1.0" encoding="UTF-8"?>

<threads xmlns="urn:jboss:threads:2.0">

    <thread-factory name="MyThreadFactory"/>

    <scheduled-thread-pool-executor name="MyScheduler">
        <max-threads count="1" per-cpu="1"/>
        <thread-factory name="MyThreadFactory"/>
    </scheduled-thread-pool-executor>
</threads>

Attributes

• name - required string attribute; specifies the bean deployment name for the executor

Child Elements

• max-threads - required; specifies the maximum number of threads in the pool.  Attributes are:
  • count - optional float attribute; specifies a fixed quantity.
  • per-cpu - optional float attribute; specifies a quantity which is multiplied by the number of available CPUs.  Both quantities are then added and the final result is the actual count used.
• keepalive-time - optional; specifies the length of time after which idle threads will exit.  Attributes are:
  • time - required integer attribute; specifies the amount of time
  • unit - required string attribute; specifies the time unit, e.g. "seconds", "ms", "min", etc.
• thread-factory - optional; specifies the bean deployment name of the thread factory that should be used to create the threads used by this executor.  The target object should implement java.util.concurrent.ThreadFactory.  If not specified, the system default thread factory is used.  Attributes of this element are:
  • name - required string attribute; specifies the bean deployment name of the ThreadFactory to use
• task-filter - optional; specifies a task filter to be applied to tasks accepted by this Executor.  See Task Filters for more information.

Direct Executor

A direct executor is one which executes tasks in the calling thread.  It is declared via the "direct-executor" element:

<?xml version="1.0" encoding="UTF-8"?>

<threads xmlns="urn:jboss:threads:2.0">

    <direct-executor name="DirectExecutor"/>

</threads>

Attributes

• name - required string attribute; specifies the bean deployment name for the executor

Child Elements

• task-filter - optional; specifies a task filter to be applied to tasks accepted by this Executor.  See Task Filters for more information.

Unbounded Ordered Executor

This is a special executor type which executes all its tasks in order of submission, within a parent executor.  An unbounded ordered executor uses a queue of unlimited length.  It is declared with the "unbounded-ordered-executor" element:

<?xml version="1.0" encoding="UTF-8"?>

<threads xmlns="urn:jboss:threads:2.0">

    <unbounded-ordered-executor name="Ordered">
        <parent-executor name="ThreadPool"/>
    </unbounded-ordered-executor>

</threads>

Attributes

• name - required string attribute; specifies the bean deployment name for the executor

Child Elements

• parent-executor - required; specifies the executor which actually run the tasks.  Attributes:
  • name - required string attribute; specifies the bean deployment name for the executor

Bounded Ordered Executor

This type of ordered executor has a limited queue length.  When a task is submitted, if there is space in the queue, the task is enqueued for execution.  Otherwise, if blocking is enabled, the calling thread will block until space becomes available in the queue.  Otherwise, if a handoff executor is specified, the task will be delegated to it.  Otherwise, the task is rejected.  This type of executor is configured with the "bounded-ordered-executor" element:

<?xml version="1.0" encoding="UTF-8"?>

<threads xmlns="urn:jboss:threads:2.0">

    <bounded-ordered-executor name="Ordered">
        <queue-length count="100"/>
        <parent-executor name="ThreadPool"/>
    </bounded-ordered-executor>

</threads>

Attributes

• name - required string attribute; specifies the bean deployment name for the executor
• blocking - optional boolean attribute; specifies whether submitting threads should block if the task cannot be immediately accepted; default is false

Child Elements

• parent-executor - required; specifies the executor which actually run the tasks.  Attributes:
  • name - required string attribute; specifies the bean deployment name for the executor
• queue-length - required; specifies the fixed length of the task queue.  Attributes are:
  • count - optional float attribute; specifies a fixed quantity.
  • per-cpu - optional float attribute; specifies a quantity which is multiplied by the number of available CPUs.  Both quantities are then added and the final result is the actual count used.  Note that since this executor type is always single-threaded, it may not be useful to scale the queue length up by CPU count.
• handoff-executor - optional; specifies the bean deployment name of an executor which should handle tasks if this executor cannot immediately accept them.  JBossAS 6.x provides a direct executor called "DirectExecutor" which is always available if the submitting thread should execute the task.  Attributes of this element are:
  • name - required string attribute; specifies the bean deployment name of the delegate Executor to use

Task Filters

A task filter may be included within certain parent elements.  The purpose of this filter is to cause the running task to be affected in certain ways in order to add specific behavior to an executor.  Task filter declaration may contain zero or more filter elements.

    ...
    <task-filter>
        <!-- filter elements here -->
    </task-filter>

The possible filter elements follow.

Thread Name

The "thread-name" element changes the name of the running thread for the duration of a task.  This element has a single required attribute, "value", which contains the new name of the thread.

Thread Name Notation

The "thread-name-notation" element is similar to the "thread-name" element, except that the given name is appended to the existing thread name for the duration of the task.  This element has a single required attribute, "valie", which contains the notation to append to the thread name.

Log Exceptions

The "log-exceptions" element encapsulates the running task, and if it throws an exception, the exception is logged according to the parameters given.  The required "category" attribute specifies the logger category to use.  The optional "level" attribute specifies the log level to use (defaulting to ERROR if not specified).

Clear TLS

The "clear-tls" element causes all thread-local variables to be cleared after the task completes.  This element has no attributes.

Clear Context Classloader

The "clear-context-classloader" element causes the current thread context classloader to be cleared after the task completes.  The element has no attributes.

Initializer

The "initializer" element specifies a Runnable task which is run before every task.  The required "name" attribute specifies the bean deployment name of the Runnable task.

Cleaner

The "cleaner" element specifies a Runnable task which is run after every task.  The required "name" attribute specifies the bean deployment name of the Runnable task.