net.spy.util
Class ThreadPool

java.lang.Object
  java.lang.ThreadGroup
      net.spy.util.ThreadPool

public class ThreadPool

extends ThreadGroup

A producer/consumer thread pool for easy parallelism.

Quick start example (assuming you want to do a million tasks, 15 at time):

 // Get a thread pool that will perform 15 tasks at a time
 ThreadPool tp=new ThreadPool("Test Pool", 15);
 // Start the thread pool
 tp.start();

 // Do the tasks in a loop, throttling to make sure all we don't
 // create too many objects that aren't ready to be used.
 for(int i=0; i<1000000; i++) {
     // Don't have more than 32 unclaimed tasks
     tp.waitForTaskCount(32);
     tp.addTask(new MyRunnableClass());
 }
 tp.waitForCompletion();
 
 

The ThreadPoolManager instance is responsible for sizing and resizing the pool. On start(), the ThreadPoolManager will size the pool to the start size configured in the ThreadPool. The manager will receive a notification after any task is added to the pool and may choose to take action at that point. Otherwise, it will sleep for a certain amount of time (one minute by default) and then begin its main loop verifying the number of idle threads satisfies the configuration.

If the number of idle threads is too low, it will create as many as is required to have the appropriate number of idle threads as long as the total number of threads will not exceed the configured maximum.

If the number of idle threads is too high, it will reduce the total number of threads by one (for each loop).

Constructor Summary

ThreadPool(String name)
Get an instance of ThreadPool with five threads and a normal priority.

ThreadPool(String name, int n)
Get an instance of ThreadPool with a normal priority.

ThreadPool(String name, int n, int priority)
Get an instance of ThreadPool.

Method Summary

void	addTask(Runnable r) Add a task for one of the threads to execute.
boolean	addTask(Runnable r, long timeout) Add a task for one of the threads to execute.
protected void	finalize() Shuts down in case you didn't.
int	getActiveThreadCount() Find out how many threads are still active (not shut down) in the pool.
int	getIdleThreadCount() Find out how many threads are idle.
int	getMaxTaskQueueSize() Get the maximum size of the task queue.
int	getMaxTotalThreads() Get the maximum number of total threads this pool may have.
int	getMinIdleThreads() Get the minimum number of idle threads.
int	getMinTotalThreads() Get the minimum number of threads that may exist in the thread pool at any moment.
ThreadPoolObserver	getMonitor() Get the monitor that receives notifications when a worker thread finishes a job.
int	getPriority() Get the priority that will be used for any new threads within this thread group.
int	getStartThreads() Get the number of threads to spin up when bringing up this ThreadPool.
int	getTaskCount() Find out how many tasks are in the queue.
int	getThreadCount() Get the total number of threads in this pool.
void	setMaxTaskQueueSize(int maxTaskQueueSize) Set the maximum size of the job queue.
void	setMaxTotalThreads(int maxTotalThreads) Set the maximum number of threads that may be in this pool.
void	setMinIdleThreads(int minIdleThreads) Set the minimum number of idle threads to maintain.
void	setMinTotalThreads(int minTotalThreads) Set the minimum number of threads that may exist in the thread pool at any moment.
void	setMonitor(ThreadPoolObserver monitor) Set the observer who will receive notification whenever a task is completed.
void	setPoolManagerClass(Class poolManagerClass) Set the PoolManager class.
void	setPriority(int priority) Set the priority to be used for any new threads within this threaad group.
void	setStartThreads(int startThreads) Set the number of threads to start when bringing up this pool.
void	setTasks(LinkedList tasks) Set the LinkedList to contain the tasks on which this ThreadPool will be listening.
void	shutdown() Tell all the threads to shut down after they finish their current tasks.
void	start() Start the ThreadPool.
String	toString() String me.
void	waitForCompletion() Shut down all of the threads after all jobs are complete, and wait for all tasks to complete.
void	waitForTaskCount(int num) Wait until there are no more than num tasks in the queue.
void	waitForThreads() Wait until there are no more threads processing.

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, uncaughtException

Methods inherited from class java.lang.Object

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

Constructor Detail

ThreadPool

public ThreadPool(String name,
                  int n,
                  int priority)

Get an instance of ThreadPool.

Parameters:

name - Name of the pool.

n - Number of threads.

ThreadPool

public ThreadPool(String name,
                  int n)

Get an instance of ThreadPool with a normal priority.

Parameters:

name - Name of the pool.

n - Number of threads.

ThreadPool

public ThreadPool(String name)

Get an instance of ThreadPool with five threads and a normal priority.

Parameters:

name - Name of the pool.

Method Detail

start

public void start()

Start the ThreadPool.

getIdleThreadCount

public int getIdleThreadCount()

Find out how many threads are idle. This is a snapshot, it is subject to change between the time that the number is calculated and the time that the value is returned.

Returns:

the number of threads not currently running a task

getThreadCount

public int getThreadCount()

Get the total number of threads in this pool.

Returns:

the number of threads

toString

public String toString()

String me.

setPoolManagerClass

public void setPoolManagerClass(Class poolManagerClass)

Set the PoolManager class. This class will be instantiated when the ThreadPool is started.

Parameters:

poolManagerClass - a subclass of ThreadPoolManager

getMaxTaskQueueSize

public int getMaxTaskQueueSize()

Get the maximum size of the task queue.

setMaxTaskQueueSize

public void setMaxTaskQueueSize(int maxTaskQueueSize)

Set the maximum size of the job queue. This is the number of unclaimed tasks that may be queued. If more than this many tasks are queued, exceptions will be thrown.

Parameters:

maxTaskQueueSize - a value > 0

getMinTotalThreads

public int getMinTotalThreads()

Get the minimum number of threads that may exist in the thread pool at any moment.

setMinTotalThreads

public void setMinTotalThreads(int minTotalThreads)

Set the minimum number of threads that may exist in the thread pool at any moment.

Parameters:

minTotalThreads - a value ≥ 0

getMinIdleThreads

public int getMinIdleThreads()

Get the minimum number of idle threads.

setMinIdleThreads

public void setMinIdleThreads(int minIdleThreads)

Set the minimum number of idle threads to maintain.

Parameters:

minIdleThreads - a value ≥ 0

getMaxTotalThreads

public int getMaxTotalThreads()

Get the maximum number of total threads this pool may have.

setMaxTotalThreads

public void setMaxTotalThreads(int maxTotalThreads)

Set the maximum number of threads that may be in this pool.

Parameters:

maxTotalThreads - a value ≥ 0

getStartThreads

public int getStartThreads()

Get the number of threads to spin up when bringing up this ThreadPool.

setStartThreads

public void setStartThreads(int startThreads)

Set the number of threads to start when bringing up this pool.

Parameters:

startThreads - a value ≥ 0

getPriority

public int getPriority()

Get the priority that will be used for any new threads within this thread group.

setPriority

public void setPriority(int priority)

Set the priority to be used for any new threads within this threaad group.

setTasks

public void setTasks(LinkedList tasks)

Set the LinkedList to contain the tasks on which this ThreadPool will be listening.

getMonitor

public ThreadPoolObserver getMonitor()

Get the monitor that receives notifications when a worker thread finishes a job.

setMonitor

public void setMonitor(ThreadPoolObserver monitor)

Set the observer who will receive notification whenever a task is completed.

addTask

public void addTask(Runnable r)

Add a task for one of the threads to execute. This method will add a new task to the queue and notify the queue of the new task (as well as notify the pool manager) then return immediately.

Throws:

IndexOutOfBoundsException - if the backing list is full

See Also:

ThreadPoolRunnable

addTask

public boolean addTask(Runnable r,
                       long timeout)

Add a task for one of the threads to execute. This method will add a new task to the queue, but only wait a certain amount of time for the task to get picked up. If the task is not picked up for execution by timeout milliseconds, the task will not be executed.

Parameters:

r - the task to execute

timeout - the number of milliseconds to wait for it to start

Returns:

true if the task was started

Throws:

IndexOutOfBoundsException - if the backing list is full

getTaskCount

public int getTaskCount()

Find out how many tasks are in the queue. This is the number of jobs that have not been accepted by threads, i.e. they haven't been started.

getActiveThreadCount

public int getActiveThreadCount()

Find out how many threads are still active (not shut down) in the pool.

shutdown

public void shutdown()

Tell all the threads to shut down after they finish their current tasks.

waitForCompletion

public void waitForCompletion()
                       throws InterruptedException

Shut down all of the threads after all jobs are complete, and wait for all tasks to complete.

This is a convenience method that calls waitforTaskCount(0), followed by shutdown(), followed by waitForThreads().

Throws:

InterruptedException - if waitForTaskCount or waitForThreads throws an exception

waitForTaskCount

public void waitForTaskCount(int num)
                      throws InterruptedException

Wait until there are no more than num tasks in the queue. This is good for throttling task additions.

Parameters:

num - the number of tasks for which to wait

Throws:

InterruptedException - if wait fails

waitForThreads

public void waitForThreads()
                    throws InterruptedException

Wait until there are no more threads processing. This will return when all threads have shut down.

Throws:

IllegalStateException - if shutdown() has not been called

InterruptedException - if sleep() is interrupted

finalize

protected void finalize()
                 throws Throwable

Shuts down in case you didn't.

Throws:

Throwable