public class ThreadPool
extends java.lang.Object
implements java.io.Serializable
A ThreadPool manages a set of "Workers", each of which manages a java.lang.Thread ready to be used to run a task for you. The threads are setDaemon(true), so they'll automatically die when the program is terminated. At any point in time, a Worker is either *pooled*, meaning it is in the ThreadPool and available to be used, or it is *outstanding*, meaning that it is presently working on a Runnable that has been assigned it.
You obtain a Worker from a ThreadPool by calling start(...), passing in a Runnable which is the code you wish the Worker to perform. When this Runnable is completed, that is, when its run() method exits, the Worker will automatically rejoin the ThreadPool and become available for use in future.
A Worker manages a Worker underneath in which the Runnable is run. The Worker has a method called interrupt() which you can call if you wish to have interrupt() called on the underlying Worker; otherwise you shouldn't really play around with the underlying Worker even if you can obtain it (via Worker.currentWorker() for example).
If there are no Workers presently available in the pool when you request one, a new Worker, and an associated underlying thread, will be created on the fly. When this Worker is done, it will enter the Pool with the others. Thus the total number of Workers will never shrink, tough it may stay the same size. If you want to trim the number of Workers presently in the Pool, you can call killPooled(), though it's not a common need.
You might wish to control the total number of workers at any particular time. You can do this by using a version of start() which takes a maximum number of workers. This version will block as long as the number of current working threads is greater than or equal to the desired maximum, then start() afterwards.
You can wait for an outstanding Worker to finish its task by calling join(...). You can wait for all outstanding Workers to finish their tasks by calling joinAll(...). This is useful for spawning a number of Workers, then waiting for them to all finish. And you can wait for all outstanding Workers to finish their tasks, followed by killing them and all their underlying threads (perhaps to clean up in preparation for quitting your program) by calling killAll(...).
ThreadPool is java.io.Serializable: if it is serialized out, it won't serialize out its worker threads, so when it is deserialized back in, the threads will be gone.
Modifier and Type | Class and Description |
---|---|
static interface |
ThreadPool.Worker
A Worker is a special kind of object which represents an underlying
Worker thread usable in the ThreadPool.
|
Constructor and Description |
---|
ThreadPool() |
Modifier and Type | Method and Description |
---|---|
int |
getOutstandingWorkers()
Returns the total number of outstanding workers (those working on something right now).
|
int |
getPooledWorkers()
Returns the total number of pooled workers (those not working on something right now).
|
int |
getTotalWorkers()
Returns the total number of workers, both pooled and outstanding (working on something).
|
boolean |
join(ThreadPool.Worker thread)
If the thread is presently running a Runnable of any kind, blocks until the Runnable has
finished running.
|
boolean |
join(ThreadPool.Worker thread,
java.lang.Runnable run)
Joins the given thread running the given Runnable.
|
void |
joinAll()
Waits until there are no outstanding workers: all pool workers are in the pool.
|
void |
killAll()
Waits until there are no outstanding workers: all pool workers are in the pool.
|
void |
killPooled()
Kills all unused workers in the pool.
|
static void |
main(java.lang.String[] args) |
ThreadPool.Worker |
start(java.lang.Runnable run)
Start a thread on the given Runnable and returns it.
|
ThreadPool.Worker |
start(java.lang.Runnable run,
int maximumOutstandingWorkers)
Start a thread on the given Runnable and returns it.
|
ThreadPool.Worker |
start(java.lang.Runnable run,
int maximumOutstandingWorkers,
java.lang.String name)
Start a thread on the given Runnable with a given thread name
(for debugging purposes) and returns it.
|
ThreadPool.Worker |
start(java.lang.Runnable run,
java.lang.String name)
Start a thread on the given Runnable with a given thread name (for debugging purposes).
|
public ThreadPool.Worker start(java.lang.Runnable run)
public ThreadPool.Worker start(java.lang.Runnable run, java.lang.String name)
public ThreadPool.Worker start(java.lang.Runnable run, int maximumOutstandingWorkers)
public ThreadPool.Worker start(java.lang.Runnable run, int maximumOutstandingWorkers, java.lang.String name)
public int getTotalWorkers()
public int getPooledWorkers()
public int getOutstandingWorkers()
public boolean join(ThreadPool.Worker thread, java.lang.Runnable run)
public boolean join(ThreadPool.Worker thread)
public void joinAll()
public void killPooled()
public void killAll()
public static void main(java.lang.String[] args)