com.ls.util.threading
Class ThreadPool

java.lang.Object
  |
  +--java.lang.ThreadGroup
        |
        +--com.ls.util.threading.ThreadPool
Direct Known Subclasses:
StaticThreadPool

public abstract class ThreadPool
extends ThreadGroup

This class provides a pool of threads. The threads can be usesd for executing so-called "tasks". A task is a generic piece of code modelled as a class which implement the Runnable interface. Instances of such a class can be passed to this thread pool by calling runTask(Runnable). The pool dynamically allocates an idle thread for execution. The allocated thread executes the task by calling the Runnable.run() method.

Version:
$Revision: 1.9 $
Author:
Last modified by $Author: MFehrenbach $

Constructor Summary
ThreadPool(String name)
          Constructs a new thread pool with the given name.
 
Method Summary
 void join()
          Waits until all threads in this thread pool are terminated.
static ThreadPool newInstance(Properties props)
          Factory method that instaniates a new thread pool implementation according to the properties defined by the given 'props' argument.
abstract  void runTask(Runnable task)
          Executes the given task by a pool thread.
 void setLogger(ILogger logger)
          Sets the logging interface that should be used by this thread pool to report diagnostic messages.
protected  ThreadPoolWorker startNewWorker()
          Starts a new worker thread and adds it to this thread pool.
protected  ThreadPoolWorker[] startNewWorker(int amount)
          Performs the same task as startNewWorker() as often as specified by the 'amount' argument.
protected  void threadBusy(ThreadPoolWorker worker, Runnable task)
          Called by a worker thread to notify the thread pool, that the worker is going to execute the given task.
protected  void threadInitialize(ThreadPoolWorker worker)
          Called by a worker thread to notify the thread pool, that the worker thread is initializing.
protected  void threadReady(ThreadPoolWorker worker)
          Called by a worker thread to notify the thread pool, that the worker thread is ready to process a task.
protected  void threadShutdown(ThreadPoolWorker worker)
          Called by a worker thread to notify the thread pool that the worker will shut down.
protected  void threadTaskCompleted(ThreadPoolWorker worker, Runnable task)
          Called by a worker thread to inform the thread pool about successfull task execution.
protected  void threadTaskFailed(ThreadPoolWorker worker, Runnable task, Throwable error)
          Called by a worker thread to inform the thread pool about failure of task execution.
 void uncaughtException(Thread thread, Throwable thr)
          Called by the worker threads if an unexpected exception was raised in the threads ThreadPoolWorker.run() method.
abstract  void waitForIdlePool()
          Waits until all threads are ready for task execution, or in other words: waits until all currently processed tasks are finished.
abstract  void waitForIdleThread()
          Waites until a thread in the pool becomes ready for task execution.
 
Methods inherited from class java.lang.ThreadGroup
activeCount, activeGroupCount, allowThreadSuspension, checkAccess, destroy, enumerate, enumerate, enumerate, enumerate, getMaxPriority, getName, getParent, interrupt, isDaemon, isDestroyed, list, parentOf, resume, setDaemon, setMaxPriority, stop, suspend, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ThreadPool

public ThreadPool(String name)
Constructs a new thread pool with the given name. The name is mainly used to identify single worker threads in log histories. The worker thread names consist of the thread pool name with a "-" character and a sequential id appended. If the name of the thread pool is "RequestHandler", than the single threads in the pool have names like "RequestHandler-1", "RequestHandler-2", and so on.

Parameters:
name - The name of this thread pool.
Method Detail

newInstance

public static ThreadPool newInstance(Properties props)
                              throws BuildException
Factory method that instaniates a new thread pool implementation according to the properties defined by the given 'props' argument.
Parameters:
props - Properties required to instanatiate a new thread pool.
Returns:
A new thread pool instance
Throws:
BuildException - If the build failed due to invalid property values or reflection errors.

setLogger

public void setLogger(ILogger logger)
Sets the logging interface that should be used by this thread pool to report diagnostic messages. Passing null as argument will result in a NullPointerException later on.

Parameters:
logger - the logging interface which should be used for reporting

waitForIdleThread

public abstract void waitForIdleThread()
                                throws InterruptedException
Waites until a thread in the pool becomes ready for task execution.

Throws:
InterruptedException - If the caller thread gets interrupted while waiting.

waitForIdlePool

public abstract void waitForIdlePool()
                              throws InterruptedException
Waits until all threads are ready for task execution, or in other words: waits until all currently processed tasks are finished.

Throws:
InterruptedException - If the caller thread gets interrupted while waiting. *

runTask

public abstract void runTask(Runnable task)
                      throws InterruptedException
Executes the given task by a pool thread. If no pool thread is available this method blocks until one becomes available.

Parameters:
task - task to run
Throws:
InterruptedException - If the caller thread gets interrupted while waiting.

join

public void join()
          throws InterruptedException
Waits until all threads in this thread pool are terminated.

Throws:
InterruptedException - If the caller thread gets interrupted while waiting.

uncaughtException

public void uncaughtException(Thread thread,
                              Throwable thr)
Called by the worker threads if an unexpected exception was raised in the threads ThreadPoolWorker.run() method. By default this method reports the exception to an ILogger interface, which can be set by calling method setLogger(ILogger).
Overrides:
uncaughtException in class ThreadGroup
Parameters:
thread - The thread that caused the exception.
thr - The exception that has raised.

startNewWorker

protected ThreadPoolWorker startNewWorker()
Starts a new worker thread and adds it to this thread pool.
Returns:
The worker thread that has been created and started.

startNewWorker

protected ThreadPoolWorker[] startNewWorker(int amount)
Performs the same task as startNewWorker() as often as specified by the 'amount' argument. Returns all created worker threads in an array.
Parameters:
amount - The amount of worker threads, that should be created and started at once.
Returns:
An array containing all new worker threads.

threadInitialize

protected void threadInitialize(ThreadPoolWorker worker)
Called by a worker thread to notify the thread pool, that the worker thread is initializing.

Parameters:
worker - The worker thread that is initializing.

threadReady

protected void threadReady(ThreadPoolWorker worker)
Called by a worker thread to notify the thread pool, that the worker thread is ready to process a task. In this method, a thread pool implementation can call ThreadPoolWorker.runTask(Runnable) to assign the next pending task to the worker thread, for instance.

Parameters:
worker - The worker thread that is ready.

threadBusy

protected void threadBusy(ThreadPoolWorker worker,
                          Runnable task)
Called by a worker thread to notify the thread pool, that the worker is going to execute the given task.
Parameters:
worker - The worker that will be busy because of task execution.
task - The task that will be executed by the worker.

threadTaskCompleted

protected void threadTaskCompleted(ThreadPoolWorker worker,
                                   Runnable task)
Called by a worker thread to inform the thread pool about successfull task execution.
Parameters:
worker - The worker that has just successfully completed a task.
task - The task that succeeded.

threadTaskFailed

protected void threadTaskFailed(ThreadPoolWorker worker,
                                Runnable task,
                                Throwable error)
Called by a worker thread to inform the thread pool about failure of task execution.
Parameters:
worker - The worker that has failed to execute a task.
task - The task that failed.
error - The specific exception that was raised by the task.

threadShutdown

protected void threadShutdown(ThreadPoolWorker worker)
Called by a worker thread to notify the thread pool that the worker will shut down.
Parameters:
worker - The worker thread that will perform a shutdown.