net.spy.util
Class ThreadPool

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

All Implemented Interfaces:

java.lang.Thread.UncaughtExceptionHandler

public class ThreadPool
extends java.lang.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(java.lang.String name)
Get an instance of ThreadPool with five threads and a normal priority.

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

ThreadPool(java.lang.String name, int n, int prio)
Get an instance of ThreadPool.

Method Summary

void	addTask(java.lang.Runnable r) Add a task for one of the threads to execute.
boolean	addTask(java.lang.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 mtqs) Set the maximum size of the job queue.
void	setMaxTotalThreads(int mtt) Set the maximum number of threads that may be in this pool.
void	setMinIdleThreads(int mit) Set the minimum number of idle threads to maintain.
void	setMinTotalThreads(int mtt) Set the minimum number of threads that may exist in the thread pool at any moment.
void	setMonitor(ThreadPoolObserver m) Set the observer who will receive notification whenever a task is completed.
void	setPoolManagerClass(java.lang.Class pmc) Set the PoolManager class.
void	setPriority(int p) Set the priority to be used for any new threads within this threaad group.
void	setStartThreads(int st) Set the number of threads to start when bringing up this pool.
void	setTasks(java.util.LinkedList<net.spy.util.ThreadPool.Task> t) 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.
java.lang.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(java.lang.String name,
                  int n,
                  int prio)

Get an instance of ThreadPool.

Parameters:

name - Name of the pool.

n - Number of threads.

prio - Priority of the child threads.

ThreadPool

public ThreadPool(java.lang.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(java.lang.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 java.lang.String toString()

String me.

Overrides:

toString in class java.lang.ThreadGroup

setPoolManagerClass

public void setPoolManagerClass(java.lang.Class pmc)

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

Parameters:

pmc - a subclass of ThreadPoolManager

getMaxTaskQueueSize

public int getMaxTaskQueueSize()

Get the maximum size of the task queue.

setMaxTaskQueueSize

public void setMaxTaskQueueSize(int mtqs)

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:

mtqs - 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 mtt)

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

Parameters:

mtt - a value ≥ 0

getMinIdleThreads

public int getMinIdleThreads()

Get the minimum number of idle threads.

setMinIdleThreads

public void setMinIdleThreads(int mit)

Set the minimum number of idle threads to maintain.

Parameters:

mit - a value ≥ 0

getMaxTotalThreads

public int getMaxTotalThreads()

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

setMaxTotalThreads

public void setMaxTotalThreads(int mtt)

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

Parameters:

mtt - 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 st)

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

Parameters:

st - 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 p)

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

setTasks

public void setTasks(java.util.LinkedList<net.spy.util.ThreadPool.Task> t)

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 m)

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

addTask

public void addTask(java.lang.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:

java.lang.IndexOutOfBoundsException - if the backing list is full

See Also:

ThreadPoolRunnable

addTask

public boolean addTask(java.lang.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:

java.lang.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 java.lang.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:

java.lang.InterruptedException - if waitForTaskCount or waitForThreads throws an exception

waitForTaskCount

public void waitForTaskCount(int num)
                      throws java.lang.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:

java.lang.InterruptedException - if wait fails

waitForThreads

public void waitForThreads()
                    throws java.lang.InterruptedException

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

Throws:

java.lang.IllegalStateException - if shutdown() has not been called

java.lang.InterruptedException - if sleep() is interrupted

finalize

protected void finalize()
                 throws java.lang.Throwable

Shuts down in case you didn't.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable