11 Task Manager and Thread Pool Configuration

This chapter provides guidelines for configuring the task manager and thread pool management features for an OC4J instance. It contains the following sections:

Configuring the OC4J Task Manager
Using Thread Pools

Configuring the OC4J Task Manager

The task manager is a background process that executes all pending tasks, such as timing out HTTP sessions and checking for changed configuration files. By default, it executes every second (1000 milliseconds).

The interval at which the task manager executes is specified in milliseconds in the taskmanager-granularity attribute of the <application-server> element in the server.xml configuration file. This is an OC4J container-level parameter. The default is 1000 milliseconds.

For example, the following entry in server.xml configures the task manager to execute every minute (60000 milliseconds):

<application-server ...  taskmanager-granularity="60000" ...>

Note that you must restart OC4J after making modifications to server.xml.

Note:

You can also set this parameter through the granularity attribute in the TaskManager MBean, which is accessible through the JMX Browser in the Application Server Control Console.

See Chapter 12, "Using MBeans in OC4J" for details on accessing and using MBeans to manage OC4J processes.

Using Thread Pools

Thread pools create and store threads for use and re-use by an OC4J process. Re-using existing threads rather than creating new threads on demand improves performance and reduces the burden on the JVM and underlying operating system.

This section covers the following topics:

Using the Default Thread Pool Configuration
Managing Thread Pool Configurations

Using the Default Thread Pool Configuration

By default, a single thread pool is created at OC4J startup. New threads are created and added to the pool on an as-needed basis. As each thread is released, it is returned to the pool to remain idle until it is needed by a new request.

There is no limit on the number of threads that can be created within the pool in this configuration. Idle threads in the pool are re-used before a new thread is spawned, unless the number of requests exceeds the number of available threads. After 10 minutes of inactivity, idle threads are automatically destroyed.

This default configuration should be sufficient for most OC4J usage scenarios.

Managing Thread Pool Configurations

Note:

Configuring thread pools or modifying the default configuration should be considered expert-mode tasks. It is strongly recommended that the default single thread pool configuration be used.

You can optionally enforce limits on the default thread pool created at OC4J startup through the following:

Adding the <global-thread-pool> element to server.xml. (This element is not included by default.) This element includes min, max, queue, and keepAlive attributes.
Updating the attributes of the ApplicationServerThreadPool MBean, which is accessible through the System MBean Browser in Application Server Control Console. See "Using the System MBean Browser" for details on accessing and using MBeans to manage OC4J.

Alternatively, you can create two different thread pools, effectively dividing different types of threads among the pools:

A worker thread pool containing worker threads used in processing RMI, HTTP and AJP requests, as well as MDB listener threads. These are process-intensive and use database resources.
A connection thread pool containing threads such as listener threads, JDBC connection threads, and RMI server connection threads, and background threads. These threads are typically not process intensive.

To create these two separate thread pools, you must configure the min, max, queue, and keepAlive attributes for the worker thread pool and the cx-min, cx-max, cx-queue, and cx-keepAlive attributes for the connection thread pool. All of these attributes must be configured if creating pools; otherwise you will see the following error message:

Error initializing server: Invalid Thread Pool parameter: null

See Table 11-1 for descriptions of the attributes of <global-thread-pool>.

The following example initializes two thread pools for the OC4J process. Each contains a minimum of 10 threads and maximum of 100 threads. The number of requests outstanding in each queue can be 200 requests. Also, idle threads are kept alive for 700 seconds. The thread pool information is printed at startup.

<application-server ...>
 ...
 <global-thread-pool min="10" max="100" queue="200" keepAlive="700000" 
  cx-min="10" cx-max="100" cx-queue="200" cx-keepAlive="700000" debug="true"/>
 ...
</application-server>

Table 11-1 below describes the attributes of the <global-thread-pool> element, which also correspond to attributes of the ApplicationServerThreadPool MBean. Note that the <global-thread-pool> element is not included in server.xml by default.

Table 11-1 Attributes of <global-thread-pool>

Attribute	Description
min	The minimum number of threads to create in the pool. By default, a minimum number of threads are pre-allocated and placed in the thread pool when the container starts. If you add the `<global-thread-pool>` element to `server.xml`, the default value is set to `20`. To disable the thread pool, set this value to `0`.
max	The maximum number of threads that can be created in the pool. New threads are spawned if the maximum size is not reached and if there are no idle threads. Idle threads are used first before a new thread is spawned. Note if `<global-thread-pool>` is added to `server.xml`, the default is set to `40`. If this element is not specified, there is no default value.
queue	The maximum number of requests that can be kept in the queue. The default is `80`.
keepAlive	The length of time, in milliseconds, to keep a thread alive (idle) while waiting for a new request. After the timeout is reached, the thread is destroyed. To never destroy threads, set to `-1`. The default is `600000` milliseconds (10 minutes), which is also the minimum value allowed if not `-1`.
cx-min	The minimum number of threads to create in the connection thread pool. The minimum value that can be specified is `1`.
cx-max	The maximum number of threads that can be created in the connection pool. The default is `40`.
cx-queue	The maximum number of threads that can be kept in the queue in the connection pool. The default is `80`.
cx-keepAlive	The length of time, in milliseconds, to keep a thread alive (idle) while waiting for a new request. After the timeout is reached, the thread is destroyed. To never destroy threads, set to `-1`. The default is `600000` milliseconds (10 minutes), which is also the minimum value allowed if not `-1`.
debug	If `true`, prints the application server thread pool information to the console at startup. The default is `false`.

A work management thread pool containing worker threads used by resource adapters, such as the JMS connector, is created within the OC4J process if needed by a resource adapter deployed to the OC4J instance.

This pool is managed in either of the following ways:

Adding the <work-manager-thread-pool> element to server.xml. (This element is not included by default.)
Updating the attributes of the WorkManagerThreadPool MBean, which is accessible through the System MBean Browser in Application Server Control Console. See "Using the System MBean Browser" for details on accessing and using MBeans to manage OC4J.

The following server.xml entry configures the work management thread pool to create a minimum of 10 threads and print thread pool information to the console:

<application-server ...>
 ...
 <work-manager-thread-pool min="10" debug="true"/>
 ...
</application-server>

Note that the work management thread pool is completely independent of the other two pools; the worker and connection thread pool attributes do not have to be configured in order to activate this pool.

Table 11-2 below describes the attributes of the <work-manager-thread-pool> element, which also correspond to attributes of the WorkManagerThreadPool MBean. Note that the <global-thread-pool> element is not included in server.xml by default.

Table 11-2 Attributes of <work-manager-thread-pool>

Attribute	Description
`min`	The minimum number of threads to create in the work management pool. To disable the thread pool, set this value to `0`.
`max`	The maximum number of threads that can be created in the work management thread pool. The default is `40`.
`queue`	The maximum number of threads that can be kept in the queue in the work management pool. The default is `0`, which means that no queue is maintained to handle a sudden burst of work requests.
`keepAlive`	The length of time, in milliseconds, to keep a thread alive (idle) while waiting for a new request. After the timeout is reached, the thread is destroyed. To never destroy threads, set to `-1`. The default is `600000` milliseconds (10 minutes), which is also the minimum value allowed if not `-1`.
`debug`	If `true`, prints the application server work management thread pool information to the console at startup. The default is `false`.

Additional notes on thread pool configuration:

The queue attributes should be at least twice the size of the maximum number of threads.
The minimum and maximum number of worker threads should be a multiple of the number of CPUs installed on your machine. However, this number should be small; the more threads you have, the more burden you put on the operating system and the garbage collector.
The cx-min and cx-max attributes are relative to the number of the physical connections you have at any point in time. The cx-queue handles bursts in connection traffic.