10 Task Manager and Thread Pool Configuration

This chapter provides guidelines for configuring the task manager for an OC4J instance and configuring thread pools for OC4J instances and Web site applications. It contains the following sections:

Configuring the OC4J Task Manager
Configuring OC4J 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" ...>

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.

Configuring OC4J Thread Pools

Thread pools create and store threads for use and reuse by an OC4J process and applications deployed to the OC4J instance. Reusing existing threads rather than creating new threads on demand improves performance and reduces the burden on the JVM and underlying operating system.

Table 10-1 lists the thread pools available in OC4J 10g (10.1.3.1.0).

Table 10-1 OC4J Thread Pools

Thread Pool	Description
`system`	For the OC4J runtime to use The threads from this pool do not run any applications deployed on an OC4J instance. You should not change the configuration of this thread pool.
`http`	Serves HTTP and AJP requests If no `rmi request` thread pool exists, the `http` thread pool serves RMI requests. If no `rmi connection` thread pool exists, the `http` thread pool handles RMI connections.
`jca`	Serves work management requests from resource adapters If needed by a resource adapter deployed to an OC4J instance, a work management thread pool containing worker threads used by resource adapters, such as the JMS connector, is created within the OC4J process.
`rmi request`	Serves RMI requests This optional thread pool provides more control over allocation of thread resources.
`rmi connection`	Handles RMI connections This optional thread pool provides threads that block-read on the RMI connection.
Custom	For use by one or more applications Separate, custom thread pools for applications reduces contention for thread resources. A set of applications in a cluster can share a custom thread pool.

By default, three of these thread pools are created at OC4J startup:

system
http
jca

In each thread pool, idle threads are reused before a new thread is spawned, unless the number of requests exceeds the number of available threads. After 10 minutes of inactivity, an idle thread is automatically destroyed.

A <thread-pool> or <custom-thread-pool> element in the server.xml file defines each thread pool. Table 10-2 summarizes the attributes of these elements and gives the default attribute values.

You can use the default thread pool configuration or change it. For each OC4J instance, you can change the attribute values for any of the thread pools except system, and you can and add rmi request, rmi connection, and one or more custom thread pools. The following topics describe how to configure thread pools:

Changing the Thread Pool Configuration
Configuring Custom Thread Pools for Applications

Table 10-2 Attributes of <thread-pool> and <custom-thread-pool>

Attribute	Description
`name`	The `name` attribute specifies the thread pool name and has no default value. For a custom thread pool, the name can be any string value. In the `<thread-pool>` element, the name must be one of these values: `system` A thread pool for the OC4J runtime to use `http` A thread pool that serves HTTP and AJP requests and possibly RMI requests (if an `rmi request` thread pool is not configured) and RMI connections (if an `rmi connection` thread pool is not configured) `jca` The work management thread pool, for the J2CA work manager to serve resource adapter requests `rmi request` A thread pool that serves RMI requests `rmi connection` A thread pool whose threads block-read on the RMI connection The names of the threads in these named pools are prefixed with `SystemThreadGroup_`, `HTTPThreadGroup_`, `WorkManager_`, `RMIRequestThreadGroup_`, and `RMIConnectionThreadGroup_`, respectively, and suffixed with an incrementing counter.
`min`	The minimum number of threads to create in the pool. The default value is `0`. The minimum number of threads for a `jca` thread pool 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 value of `min` for an `rmi connection` thread pool is relative to the number of the physical connections you have at any point in time. The `queue` value handles bursts in connection traffic.
`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. The default value is `1024`. The `jca` thread pool uses three worker threads for internal use. For example, if you specify `max="16"`, then only 13 worker threads are available to service requests. Similarly, if the `max` value is `20`, then only 17 threads are available. So you need to set this value to your required maximum number of threads plus 3. The maximum number of threads for a `jca` thread pool 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 value of `max` for an `rmi connection` thread pool is relative to the number of the physical connections you have at any point in time. The `queue` value handles bursts in connection traffic.
`queue`	The maximum number of requests that can be kept in the queue. The default value is `0`. The `queue` value should be at least twice the size of the maximum number of threads. If the value is `0` OC4J uses `Integer.MAX_VALUE` as the maximum number.
`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. The default value is `600000`. To never destroy threads, set to `-1`. The default value, `600000` milliseconds (10 minutes), is also the minimum value allowed if the value is not `-1`. Setting `keepAlive` to `0` (zero) will cause high CPU usage due to active polling.
`stackSize`	The size of the thread pool stack. The default value is `0`.
`debug`	A value of `true` specifies printing the thread pool information for the application server to the console at startup. The default is `false`. If `debug` is `false`, the thread pool information is not printed.

Changing the Thread Pool Configuration

You can change the thread pool configuration for an OC4J instance through the Application Server Control Console or by editing the server.xml file, in the following ways:

Change attribute values for thread pools on the Thread Pool Configuration page in the Application Server Control Console.
Change the attributes of thread pool MBeans through the System MBean Browser in the Application Server Control Console.

See "Using the System MBean Browser" for details on accessing and using MBeans to manage OC4J.
Configure an rmi request or rmi connection thread pool, or both, by adding a <thread-pool> element for each to server.xml.

You must restart OC4J after making modifications to server.xml.

Note:

Configuring thread pools or modifying the default configuration are expert-mode tasks. Oracle recommends that you use the default thread pool configuration unless you need to change it.

Changing the Thread Pool Configuration Through the Application Server Control Console

To change the thread pool configuration for an OC4J instance through the Application Server Control Console:

Navigate to the OC4J Home page and then click Administration to display the OC4J Administration page, which contains a table listing the various administration tasks you can perform for the OC4J instance.
Under Properties on the Administration page, select Thread Pool Configuration to display the OC4J Thread Pool Configuration page.
Change the value of one or more attributes for any thread pool displayed on this page.

For information about attribute values, see Table 10-2 or "<thread-pool>".
Click Apply.
Restart the OC4J instance from the Cluster Topology page or the OC4J Home page.

You can also configure thread pools in the Application Server Control Console through MBeans, as "Changing the Thread Pool Configuration Through MBeans" describes in the following text.

Changing the Thread Pool Configuration Through MBeans

To change the attributes of thread pool MBeans through Application Server Control Console:

Navigate to the OC4J Home page and then click Administration to display the OC4J Administration page, which contains a table listing the various administration tasks you can perform for the OC4J instance.
Under JMX on the Administration page, select System MBean Browser to display the OC4J System MBean Browser page., which displays the system MBeans exposed by the OC4J instance.
Expand the navigation tree on the left of the page and select a thread pool for the OC4J instance under ThreadPool
Change any attributes of the thread pool that have edit boxes.

For information about attribute values, see Table 10-2 or "<thread-pool>".
Click Apply.

Adding <thread-pool> Elements to server.xml

The following example uses the <thread-pool> element to configure an rmi request thread pool in the server.xml file:

<thread-pool 
   name="rmi request" 
   min="50" 
   max="50" 
   queue="2560" 
   keepAlive="-1" 
   stackSize="0" 
   debug="true"/>

With this configuration, OC4J will create a separate thread pool to serve RMI requests. The thread pool will have these attributes:

A minimum of 5 threads
A maximum of 50 threads
A maximum of 2560 requests in the queue
A keepAlive value of -1 (no timeout)
A stackSize value of 0 (let the JVM decide)
The debug attribute set to true

The following example shows <thread-pool> elements that configure separate thread pools in server.xml, one to serve RMI requests, one to handle RMI connections, and one to serve HTTP and AJP requests:

<thread-pool 
   name="rmi request" 
   min="50" 
   max="50" 
   queue="2560" 
   keepAlive="-1" 
   stackSize="0"/>

<thread-pool 
   name="rmi connection" 
   min="44" 
   max="44" 
   queue="2560" 
   keepAlive="-1" 
   stackSize="0"/>

<thread-pool 
   name="http" 
   min="40" 
   max="40" 
   queue="2560" 
   keepAlive="-1" 
   stackSize="0"/>

The http thread pool is created by default when an OC4J instance starts up, with the default attribute values in Table 10-2. In addition to serving HTTP and AJP requests, this tread pool can serve RMI requests and handle RMI connections in the absence of separate rmi-* thread pools.

Note:

You must restart OC4J after making modifications to server.xml.

Configuring Custom Thread Pools for Applications

You can create a separate, custom thread pool for your applications to use in an OC4J instance by adding a <custom-thread-pool> element to the server.xml file. Then you can make the custom thread pool available to an application by referring to the thread pool in the custom-thread-pool attribute of the <web-site> element in the *-web-site.xml file for the application. A server-xml file can include more than one <custom-thread-pool> element, and you can configure more than one application to use each custom thread pool.

In server.xml, the <custom-thread-pool> element is a subelement of the <application-server> element and has the same attributes as the <thread-pool> element, except that the value of name is not restricted. For example:

<custom-thread-pool name="mypool" min="3" />

The name attribute is required, and all other attributes are optional. For a complete description of this element, see "<custom-thread-pool>".

For information about the <thread-pool> element, see "Changing the Thread Pool Configuration" and "<thread-pool>".

For information about the *-web-site.xml file, see "Overview of the Web Site Configuration Files (*-web-site.xml)". The custom-thread-pool attribute is described in Table B-24.

The following example configures an HTTP site to use a nondefault thread pool by adding the custom-thread-pool attribute to the <web-site> element in the default-web-site.xml file for the HTTP site:

<web-site xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/web-site-10_0.xsd" 
       protocol="http"
       port="8888"
       custom-thread-pool="mypool1"
       display-name="OC4J 10g (10.1.3) Default Web Site"
       schema-major-version="10"
       schema-minor-version="0"
     />

Converting from the Older Thread Pool Format

The <global-thread-pool> and <work-manager-thread-pool> elements in server.xml configure thread pools in an older format. These elements are deprecated in OC4J 10g (10.1.3.1.0). Table B-7 and Table B-23 describe the attributes of these elements.

If a server.xml file contains a <global-thread-pool> or <work-manager-thread-pool> element, OC4J 10g (10.1.3.1.0) updates the older element format to the new format in server.xml. For example, suppose a server.xml file contains the following elements:

<global-thread-pool 
   min="60" 
   max="60" 
   queue="20000" 
   keepAlive="-1" />
   
   <work-manager-thread-pool 
   min="23" 
   max="24" 
   queue="5000" 
   keepAlive="-1" />

After OC4J startup, instead of the <global-thread-pool> and <work-manager-thread-pool> elements, the server.xml file will contain the following <thread-pool> elements:

<thread-pool 
   name="http" 
   min="60" 
   max="60" 
   queue="20000" 
   keepAlive="-1" 
   stackSize="0" />
   
<thread-pool 
   name="jca" 
   min="23" 
   max="24" 
   queue="5000" 
   keepAlive="-1" />

Table 10-3 shows how the attributes of <global-thread-pool> and <work-manager-thread-pool> map to the new OC4J 10g (10.1.3.1.0) thread pools.

Table 10-3 Mapping of Old Thread Pool Configuration to New Thread Pools

Old Thread Pool Attributes	Value of name Attribute in <thread-pool>	New Thread Pool Attributes
`min`, `max`, `queue`, `keepAlive`, and `debug` attributes of `<global-thread-pool>`	`http`	`min`, `max`, `queue`, `keepAlive`, and `debug` attributes of `<thread-pool>`
`min`, `max`, `queue`, `keepAlive`, and `debug` `<work-manager-thread-pool>`	`jca`	`min`, `max`, `queue`, `keepAlive`, and `debug` attributes of `<thread-pool>`
`cx-min`, `cx-max`, `cx-queue`, `cx-keepAlive`, and `cx-debug` attributes of `<global-thread-pool>`	`rmi request`	`min`, `max`, `queue`, `keepAlive`, and `debug` attributes of `<thread-pool>`
`rmiRequest-min`, `rmiRequest-max`, `rmiRequest-queue`, `rmiRequest-keepAlive`, and `rmiRequest-debug` attributes of `<global-thread-pool>`	`rmi connection`	`min`, `max`, `queue`, `keepAlive`, and `debug` attributes of `<thread-pool>`

For example, OC4J would generate new <thread-pool> elements from the following <global-thread-pool> element:

<global-thread-pool
   keepAlive="-1"
   debug="false"
   cx-keepAlive="-1"
   cx-debug="false"
   rmiRequest-keepAlive="-1"
   rmiRequest-debug="false"
   min="40"
   max="40"
   queue="2560"
   cx-min="44"
   cx-max="44"
   cx-queue="2560"
   rmiRequest-min="50"
   rmiRequest-max="50"
   rmiRequest-queue="2560"/>

The equivalent <thread-pool> elements follow:

<thread-pool 
   name="rmi request" 
   min="50" 
   max="50" 
   queue="2560" 
   keepAlive="-1" 
   stackSize="0"/>

<thread-pool 
   name="rmi connection" 
   min="44" 
   max="44" 
   queue="2560" 
   keepAlive="-1" 
   stackSize="0"/>

<thread-pool 
   name="http" 
   min="40" 
   max="40" 
   queue="2560" 
   keepAlive="-1" 
   stackSize="0"/>