com.iplanet.am.util
Class ThreadPool

java.lang.Object
  |
  +--com.iplanet.am.util.ThreadPool

public final class ThreadPool

extends java.lang.Object

ThreadPool is a generic thread pool that manages and recycles threads instead of creating them everytime some task needs to be run on a different thread. Thread pooling saves the virtual machine the work of creating brand new threads for every short-lived task. In addition, it minimizes overhead associated with getting a thread started and cleaning it up after it dies. By creating a pool of threads, a single thread from the pool can be reused any number of times for different tasks.

This reduces response time because a thread is already constructed and started and is simply waiting for its next task. This is particularly useful when using many short-lived tasks. This may not be useful for long-lived tasks.

Another characteristic of this thread pool is that it is fixed in size at the time of construction. All the threads are started, and then each goes into a wait state until a task is assigned to it. If all the threads in the pool are currently assigned a task, the pool is empty and new requests (tasks) will have to wait before being scheduled to run. This is a way to put an upper bound on the amount of resources any pool can use up.

In future, this class may be enhanced to provide support growing the size of the pool at runtime to facilitate dynamic tuning.

Constructor Summary

ThreadPool(java.lang.String poolName, int numThreads, boolean daemon, Debug debug)
Constructs a thread pool with the poolName and given number of threads.

Method Summary

void	destroy() Destroys the thread pool.
java.lang.String	getName() Get the name of this thread pool
void	run(java.lang.Runnable task) Runs the user-defined task.
void	stopIdleThreads() Stops all the idle threads in the pool.
java.lang.String	toString() Returns the string representation of this thread pool that includes the name, size and the number of currently idle threads

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ThreadPool

public ThreadPool(java.lang.String poolName,
                  int numThreads,
                  boolean daemon,
                  Debug debug)
           throws java.lang.IllegalArgumentException

Constructs a thread pool with the poolName and given number of threads. Another characteristic of this thread pool is that it is fixed in size at the time of construction. All the threads are started, and then each goes into a wait state until a task is assigned to it.

The size of the pool should be carefully choosen. If the size is too large, there may be excessive context switching and the performance may suffer. If the tasks are fairly distributed between CPU and I/O usage, start with a pool size of 10 per CPU; later experiment and fine-tune for optimal pool size. Ensure that the pool size is configurable at install/runtime.

Parameters:

poolName - name of the thread pool

numThreads - maximum number of threads in the thread pool.

daemon - if true, all threads created will be daemon threads. If false, all threads created will be non-daemon threads.

debug - Debug object to send debug messages to.

Throws:

java.lang.IllegalArgumentException - if poolName is null

Method Detail

run

public final void run(java.lang.Runnable task)
               throws java.lang.InterruptedException

Runs the user-defined task. To enable better debugging or profiling capabilities, the task Runnable should implement toString() to intuitively identify the task.

Parameters:

task - the user-defined Runnable to be scheduled for execution on this thread pool

Throws:

java.lang.InterruptedException - when the thread invoking run is interrupted.

stopIdleThreads

public final void stopIdleThreads()

Stops all the idle threads in the pool. Note that these stopped threads are no longer availble for future tasks because they are returned to underlying virtual machine. Also note that none of the active threads in the pool are stopped.

destroy

public final void destroy()

Destroys the thread pool. This stops all the threads, active and idle, in the pool and releases all resources.

toString

public java.lang.String toString()

Returns the string representation of this thread pool that includes the name, size and the number of currently idle threads

Overrides:

toString in class java.lang.Object

getName

public final java.lang.String getName()

Get the name of this thread pool

Returns:

the name of the thread pool