Package ec.util

# Class ThreadPool

java.lang.Object
ec.util.ThreadPool

All Implemented Interfaces:
  `Serializable`

public class ThreadPool extends Object implements Serializable
ThreadPool.java A simple, lightweight thread pool, for those who cannot or will not use Java's baroque java.util.concurrent package.

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 Thread 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 Thread; otherwise you shouldn't really play around with the underlying thread even if you can obtain it (via Thread.currentThread() 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, though 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: but 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.

See Also:
  - Serialized Form

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `ThreadPool.Worker`
  A Worker is a special kind of object which represents an underlying Worker thread usable in the ThreadPool.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ThreadPool()`

- ## Method Summary

  Modifier and Type
  Method
  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, 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(String[] args)`
  `ThreadPool.Worker`
  `start(Runnable run)`
  Start a thread on the given Runnable and returns it.
  `ThreadPool.Worker`
  `start(Runnable run, int maximumOutstandingWorkers)`
  Start a thread on the given Runnable and returns it.
  `ThreadPool.Worker`
  `start(Runnable run, int maximumOutstandingWorkers, String name)`
  Start a thread on the given Runnable with a given thread name (for debugging purposes) and returns it.
  `ThreadPool.Worker`
  `start(Runnable run, String name)`
  Start a thread on the given Runnable with a given thread name (for debugging purposes).

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### ThreadPool

    public ThreadPool()

- ## Method Details

  - ### start

    public ThreadPool.Worker start(Runnable run)
    Start a thread on the given Runnable and returns it.

  - ### start

    public ThreadPool.Worker start(Runnable run, String name)
    Start a thread on the given Runnable with a given thread name (for debugging purposes).

  - ### start

    public ThreadPool.Worker start(Runnable run, int maximumOutstandingWorkers)
    Start a thread on the given Runnable and returns it. This method blocks and does not start the thread as long as doing so would cause the number of outstanding workers to exceed the provided maximum number. This method can be used to limit the number of jobs processed by the ThreadPool at any one time.

  - ### start

    public ThreadPool.Worker start(Runnable run, int maximumOutstandingWorkers, String name)
    Start a thread on the given Runnable with a given thread name (for debugging purposes) and returns it. This method blocks and does not start the thread as long as doing so would cause the number of outstanding workers to exceed the provided maximum number. This method can be used to limit the number of jobs processed by the ThreadPool at any one time.

  - ### getTotalWorkers

    public int getTotalWorkers()
    Returns the total number of workers, both pooled and outstanding (working on something).

  - ### getPooledWorkers

    public int getPooledWorkers()
    Returns the total number of pooled workers (those not working on something right now).

  - ### getOutstandingWorkers

    public int getOutstandingWorkers()
    Returns the total number of outstanding workers (those working on something right now).

  - ### join

    public boolean join(ThreadPool.Worker thread, Runnable run)
    Joins the given thread running the given Runnable. If the thread is not presently running this Runnable, then the method immediately returns. Else it blocks until the Runnable has terminated. Returns true if the worker was working on the provided Runnable, else false.

  - ### join

    public boolean join(ThreadPool.Worker thread)
    If the thread is presently running a Runnable of any kind, blocks until the Runnable has finished running. Else returns immediately. Returns true if the worker was working on some Runnable, else false.

  - ### joinAll

    public void joinAll()
    Waits until there are no outstanding workers: all pool workers are in the pool.

  - ### killPooled

    public void killPooled()
    Kills all unused workers in the pool. This can be used to reduce the pool to a manageable size if the number of workers in it has grown too large (an unlikely scenario). You can still use the ThreadPool after calling this function; but it will have to build new workers.

  - ### killAll

    public void killAll()
    Waits until there are no outstanding workers: all pool workers are in the pool. Then kills all the workers. This is the approprate way to shut down the ThreadPool in preparation for quitting your program. You can still use the ThreadPool after calling this function; but it will have to build new workers.

  - ### main

    public static void main(String[] args)