it.pixel.util.threads
Class ThreadPool

java.lang.Object
  |
  +--it.pixel.util.threads.ThreadPool

public class ThreadPool

extends java.lang.Object

This class is the only class you want to use directly. It is the pool itself. Use this way

 
  RunnableWithParams rwp = new RunnableWithParams()
  {
    public void run(ThreadPool tp, Object params)
    {
      // your worker thread code here
    }
  };
  ThreadPool tp = new ThreadPool(rwp);
  tp.execute(new SomeClassOnlyYouKnowWhichOne());
  tp.execute(getSomeOtherParameter());
  tp.execute(getNextThingToDoFromTheFIFO());
  tp.execute("Hello world!");
  // and so on...
 

Nested Class Summary

private class

ThreadPool.PooledThread This class extends Thread and is the actual Runnable object.

Field Summary

private Semaphore	freeThreads Counts the number of inactive threads
protected int	increment The number of threads added to the end of the freelist when the number of free threads goes below the minimum
protected int	max The maximum number of threads over which no more can be created
protected int	maxFree The maximum number of free threads allowed
protected int	min The minimum number of threads under which no more can be discarded
protected int	minFree The minimum number of free threads allowed
private java.util.LinkedList	params The list of parameters to pass in FCFS order to the threads
static int	POOL_INCREMENT Default number of threads added to the end of the freelist when the number of free threads goes below the minimum
static int	POOL_MAX Default maximum pool size
static int	POOL_MAX_FREE Default maximum number of free threads allowed
static int	POOL_MIN Default minimum pool size
static int	POOL_MIN_FREE Default minimum number of free threads allowed
private RunnableWithParams	rwp The code to be executed by the threads of the pool.
private boolean	shutdown A flag that tells the sizeManager when it is time to stop
private java.lang.Thread	sizeManager A worker thread used by this class to adjust the freelist size.
private Semaphore	totalThreads Keeps the total number of threads

Constructor Summary

ThreadPool(RunnableWithParams rwp)
Creates the pool and initializes the limits with the repective default values.

ThreadPool(RunnableWithParams rwp, int min, int max, int min_free, int max_free, int increment)
Creates the pool and initializes the limits with the specified values.

Method Summary

private void	add(int nThreads) Called when the pool needs to grow
protected java.lang.Object	drawParams() Retrieves the first object on the worklist, and deletes it from the worklist.
void	ensureIncrement(int increment) First this method tries to set the value of increment alone by calling setLimits.
void	ensureMax(int max) First this method tries to set the value of max alone by calling setLimits.
void	ensureMaxFree(int maxFree) First this method tries to set the value of maxFree alone by calling setLimits.
void	ensureMin(int min) First this method tries to set the value of min alone by calling setLimits.
void	ensureMinFree(int minFree) First this method tries to set the value of minFree alone by calling setLimits.
void	execute(java.lang.Object p) Allocates a free thread from the freelist and starts the thread.
int	getIncrement() Gets the value of increment
int	getMax() Gets the value of max
int	getMaxFree() Gets the value of maxFree
int	getMin() Gets the value of min
int	getMinFree() Gets the value of minFree
RunnableWithParams	getRunnableWithParams() This method returns the RunnableWithParams instance passed to the constructor of this class.
private void	managePoolSize() This is the method executed by a worker thread that anynchronously increases the number of free threads in the pool as needed.
private void	queueParams(java.lang.Object p) Adds the specified object to the end of the worklist
void	setLimits(int min, int max, int min_free, int max_free, int increment) This method sets the limits for the number of threads in the pool.
void	shutdown() It tells the sizeManager it's time to stop, and waits for it to die.
boolean	timeToExit() Tells whether the shutdown method has already been called or not.

Methods inherited from class java.lang.Object

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

Field Detail

POOL_MIN_FREE

public static final int POOL_MIN_FREE

Default minimum number of free threads allowed

See Also:

Constant Field Values

POOL_MAX_FREE

public static final int POOL_MAX_FREE

Default maximum number of free threads allowed

See Also:

Constant Field Values

POOL_INCREMENT

public static final int POOL_INCREMENT

Default number of threads added to the end of the freelist when the number of free threads goes below the minimum

See Also:

Constant Field Values

POOL_MIN

public static final int POOL_MIN

Default minimum pool size

See Also:

Constant Field Values

POOL_MAX

public static final int POOL_MAX

Default maximum pool size

See Also:

Constant Field Values

minFree

protected int minFree

The minimum number of free threads allowed

maxFree

protected int maxFree

The maximum number of free threads allowed

min

protected int min

The minimum number of threads under which no more can be discarded

max

protected int max

The maximum number of threads over which no more can be created

increment

protected int increment

The number of threads added to the end of the freelist when the number of free threads goes below the minimum

freeThreads

private Semaphore freeThreads

Counts the number of inactive threads

totalThreads

private Semaphore totalThreads

Keeps the total number of threads

params

private java.util.LinkedList params

The list of parameters to pass in FCFS order to the threads

sizeManager

private java.lang.Thread sizeManager

A worker thread used by this class to adjust the freelist size.

shutdown

private boolean shutdown

A flag that tells the sizeManager when it is time to stop

rwp

private RunnableWithParams rwp

The code to be executed by the threads of the pool.

Constructor Detail

ThreadPool

public ThreadPool(RunnableWithParams rwp)

Creates the pool and initializes the limits with the repective default values.

Parameters:

rwp - The RunnableWithParams called by each thread.

ThreadPool

public ThreadPool(RunnableWithParams rwp,
                  int min,
                  int max,
                  int min_free,
                  int max_free,
                  int increment)

Creates the pool and initializes the limits with the specified values. This constructor throws an IllegalArgumentException if the limits are inconsistent.

Parameters:

rwp - The RunnableWithParams called by each thread.

min - Initial value for min

max - Initial value for max

min_free - Initial value for minFree

max_free - Initial value for maxFree

increment - Initial value for increment

Method Detail

managePoolSize

private final void managePoolSize()

This is the method executed by a worker thread that anynchronously increases the number of free threads in the pool as needed. This worker thread is not part of the pool, it is active from pool construction until its shutdown and it is not deterministic, in that it uses only an unpredictable approximation of the number of free threads in the pool to make decisions on the number of threads to create. This behavior is acceptable in most of the cases and it has better performances than an exact approach, which would require more synchronization.

add

private final void add(int nThreads)

Called when the pool needs to grow

Parameters:

nThreads - the number of threads to add to the freelist

execute

public void execute(java.lang.Object p)

Allocates a free thread from the freelist and starts the thread. The RunnableWithParams passed to the constructor will receive the parameter p.

Parameters:

p - The arguments to pass to the thread.

See Also:

RunnableWithParams

shutdown

public void shutdown()
              throws java.lang.InterruptedException

It tells the sizeManager it's time to stop, and waits for it to die.

java.lang.InterruptedException

See Also:

timeToExit()

queueParams

private void queueParams(java.lang.Object p)

Adds the specified object to the end of the worklist

Parameters:

p - The object to add

timeToExit

public boolean timeToExit()

Tells whether the shutdown method has already been called or not.

Returns:

True if the shotdown() method has already been called, false otherwise.

See Also:

shutdown()

drawParams

protected final java.lang.Object drawParams()

Retrieves the first object on the worklist, and deletes it from the worklist.

Returns:

The object to process, or null if the calling thread must terminate.

See Also:

execute(Object), RunnableWithParams

setLimits

public final void setLimits(int min,
                            int max,
                            int min_free,
                            int max_free,
                            int increment)

This method sets the limits for the number of threads in the pool. It checks for consistency between each others before making any change. If the check fails it throws an IllegalArgumentException. The method can be called at any time and the pool will adjust itself to fit the new limits. However this may happen after a while.

Parameters:

min - The minimum total number of threads in the pool

max - The maximum total number of threads in the pool

min_free - The minimum number of free threads in the pool

max_free - The maximum number of free threads in the pool

increment - The number of threads to add when needed

See Also:

min, max, minFree, maxFree, increment

getMin

public final int getMin()

Gets the value of min

Returns:

The minimum total number of threads in the pool

See Also:

min

getMax

public final int getMax()

Gets the value of max

Returns:

The maximum total number of threads in the pool

See Also:

max

getMinFree

public final int getMinFree()

Gets the value of minFree

Returns:

The minimum number of free threads in the pool

See Also:

minFree

getMaxFree

public final int getMaxFree()

Gets the value of maxFree

Returns:

The maximum number of free threads in the pool

See Also:

maxFree

getIncrement

public final int getIncrement()

Gets the value of increment

Returns:

The number of threads to add when needed

See Also:

increment

ensureMin

public final void ensureMin(int min)

First this method tries to set the value of min alone by calling setLimits. If that fails, it adjusts all other values in order to set min to the requested value by calling setLimits again with different arguments.

Parameters:

min - The minimum total number of threads in the pool

See Also:

min, setLimits(int, int, int, int, int)

ensureMax

public final void ensureMax(int max)

First this method tries to set the value of max alone by calling setLimits. If that fails, it adjusts all other values in order to set max to the requested value by calling setLimits again with different arguments.

Parameters:

max - The maximum total number of threads in the pool

See Also:

max, setLimits(int, int, int, int, int)

ensureMinFree

public final void ensureMinFree(int minFree)

First this method tries to set the value of minFree alone by calling setLimits. If that fails, it adjusts all other values in order to set minFree to the requested value by calling setLimits again with different arguments.

Parameters:

minFree - The minimum number of free threads in the pool

See Also:

minFree, setLimits(int, int, int, int, int)

ensureMaxFree

public final void ensureMaxFree(int maxFree)

First this method tries to set the value of maxFree alone by calling setLimits. If that fails, it adjusts all other values in order to set maxFree to the requested value by calling setLimits again with different arguments.

Parameters:

maxFree - The maximum number of free threads in the pool

See Also:

maxFree, setLimits(int, int, int, int, int)

ensureIncrement

public final void ensureIncrement(int increment)

First this method tries to set the value of increment alone by calling setLimits. If that fails, it adjusts all other values in order to set increment to the requested value by calling setLimits again with different arguments.

Parameters:

increment - The number of threads to add when needed

See Also:

increment, setLimits(int, int, int, int, int)

getRunnableWithParams

public RunnableWithParams getRunnableWithParams()

This method returns the RunnableWithParams instance passed to the constructor of this class. The returned instance is the one used by every thread in the pool.

Returns:

The RunnableWithParams instance

See Also:

RunnableWithParams