jj2000.j2k.util
Class ThreadPool

java.lang.Object
  |
  +--jj2000.j2k.util.ThreadPool

public class ThreadPool

extends java.lang.Object

This class implements a thread pool. The thread pool contains a set of threads which can be given work to do.

If the Java Virtual Machine (JVM) uses native threads, then the different threads will be able to execute in different processors in parallel on multiprocessors machines. However, under some JVMs and operating systems using native threads is not sufficient to allow the JVM access to multiple processors. This is the case when native threads are implemented using POSIX threads on lightweight processes (i.e. PTHREAD_SCOPE_PROCESS sopce scheduling), which is the case on most UNIX operating systems. In order to do provide access to multiple processors it is necessary to set the concurrency level to the number of processors or slightly higher. This can be achieved by setting the Java system property with the name defined by CONCURRENCY_PROP_NAME to some non-negative number. This will make use of the 'NativeServices' class and supporting native libraries. See 'NativeServices' for details. See 'CONCURRENCY_PROP_NAME' for the name of the property.

Initially the thread pool contains a user specified number of idle threads. Idle threads can be given a target which is run. While running the target the thread temporarily leaves the idle list. When the target finishes, it joins the idle list again, waiting for a new target. When a target is finished a thread can be notified on a particular object that is given as a lock.

Jobs can be submitted using Runnable interfaces, using the 'runTarget()' methods. When the job is submitted, an idle thread will be obtained, the 'run()' method of the 'Runnable' interface will be executed and when it completes the thread will be returned to the idle list. In general the 'run()' method should complete in a rather short time, so that the threds of the pool are not starved.

If using the non-asynchronous calls to 'runTarget()', it is important that any target's 'run()' method, or any method called from it, does not use non-asynchronous calls to 'runTarget()' on the same thread pool where it was started. Otherwise this could create a dead-lock when there are not enough idle threads.

The pool also has a global error and runtime exception condition (one for 'Error' and one for 'RuntimeException'). If a target's 'run()' method throws an 'Error' or 'RuntimeException' the corresponding exception condition is set and the exception object saved. In any subsequent call to 'checkTargetErrors()' the saved exception object is thrown. Likewise, if a target's 'run()' method throws any other subclass of 'Throwable' a new 'RuntimeException' is created and saved. It will be thrown on a subsequent call to 'checkTargetErrors()'. If more than one exception occurs between calls to 'checkTargetErrors()' only the last one is saved. Any 'Error' condition has precedence on all 'RuntimeException' conditions. The threads in the pool are unaffected by any exceptions thrown by targets.

The only exception to the above is the 'ThreadDeath' exception. If a target's 'run()' method throws the 'ThreadDeath' exception a warning message is printed and the exception is propagated, which will terminate the thread in which it occurs. This could lead to instabilities of the pool. The 'ThreadDeath' exception should never be thrown by the program. It is thrown by the Java(TM) Virtual Machine when Thread.stop() is called. This method is deprecated and should never be called.

All the threads in the pool are "daemon" threads and will automatically terminate when no daemon threads are running.

See Also:

NativeServices, CONCURRENCY_PROP_NAME, Runnable, ThreadPool.ThreadPoolThread, Error, RuntimeException

Nested Class Summary

(package private) class

ThreadPool.ThreadPoolThread The threads that are managed by the pool.

Field Summary

static java.lang.String	CONCURRENCY_PROP_NAME The name of the property that sets the concurrency level: jj2000.j2k.util.ThreadPool.concurrency
private ThreadPool.ThreadPoolThread[]	idle The array of idle threads and the lock for the manipulation of the idle thread list.
private int	nidle The number of idle threads
private java.lang.String	poolName The name of the pool
private int	poolPriority The priority for the pool
private java.lang.Error	targetE The last error thrown by a target.
private java.lang.RuntimeException	targetRE The last runtime exception thrown by a target.

Constructor Summary

ThreadPool(int size, int priority, java.lang.String name)
Creates a new thread pool of the given size, thread priority and pool name.

Method Summary

void	checkTargetErrors() Checks that no error or runtime exception in any target have occurred so far.
void	clearTargetErrors() Clears the current target error conditions, if any.
private ThreadPool.ThreadPoolThread	getIdle(boolean async) Returns and idle thread and removes it from the list of idle threads.
int	getSize() Returns the size of the pool.
private void	putInIdleList(ThreadPool.ThreadPoolThread t) Puts the thread 't' in the idle list.
boolean	runTarget(java.lang.Runnable t, java.lang.Object l) Runs the run method of the specified target in an idle thread of this pool.
boolean	runTarget(java.lang.Runnable t, java.lang.Object l, boolean async) Runs the run method of the specified target in an idle thread of this pool.
boolean	runTarget(java.lang.Runnable t, java.lang.Object l, boolean async, boolean notifyAll) Runs the run method of the specified target in an idle thread of this pool.

Methods inherited from class java.lang.Object

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

Field Detail

CONCURRENCY_PROP_NAME

public static final java.lang.String CONCURRENCY_PROP_NAME

The name of the property that sets the concurrency level: jj2000.j2k.util.ThreadPool.concurrency

See Also:

Constant Field Values

idle

private ThreadPool.ThreadPoolThread[] idle

The array of idle threads and the lock for the manipulation of the idle thread list.

nidle

private int nidle

The number of idle threads

poolName

private java.lang.String poolName

The name of the pool

poolPriority

private int poolPriority

The priority for the pool

targetE

private volatile java.lang.Error targetE

The last error thrown by a target. Null if none

targetRE

private volatile java.lang.RuntimeException targetRE

The last runtime exception thrown by a target. Null if none

Constructor Detail

ThreadPool

public ThreadPool(int size,
                  int priority,
                  java.lang.String name)

Creates a new thread pool of the given size, thread priority and pool name.

If the Java system property of the name defined by 'CONCURRENCY_PROP_NAME' is set, then an attempt will be made to load the library that supports concurrency setting (see 'NativeServices'). If that succeds the concurrency level will be set to the specified value. Otherwise a warning is printed.

Parameters:

size - The size of the pool (number of threads to create in the pool).

priority - The priority to give to the threads in the pool. If less than 'Thread.MIN_PRIORITY' it will be the same as the priority of the calling thread.

name - The name of the pool. If null a default generic name is chosen.

See Also:

NativeServices, CONCURRENCY_PROP_NAME

Method Detail

getSize

public int getSize()

Returns the size of the pool. That is the number of threads in this pool (idle + busy).

Returns:

The pool's size.

runTarget

public boolean runTarget(java.lang.Runnable t,
                         java.lang.Object l)

Runs the run method of the specified target in an idle thread of this pool. When the target's run method completes, the thread waiting on the lock object is notified, if any. If there is currently no idle thread the method will block until a thread of the pool becomes idle or the calling thread is interrupted.

This method is the same as runTarget(t,l,true,false).

Parameters:

t - The target. The 'run()' method of this object will be run in an idle thread of the pool.

l - The lock object. A thread waiting on the lock of the 'l' object will be notified, through the 'notify()' call, when the target's run method completes. If null no thread is notified.

Returns:

True if the target was submitted to some thread. False if no idle thread could be found and the target was not submitted for execution.

runTarget

public boolean runTarget(java.lang.Runnable t,
                         java.lang.Object l,
                         boolean async)

Runs the run method of the specified target in an idle thread of this pool. When the target's run method completes, the thread waiting on the lock object is notified, if any. If there is currently no idle thread and the asynchronous mode is not used the method will block until a thread of the pool becomes idle or the calling thread is interrupted. If the asynchronous mode is used then the method will not block and will return false.

This method is the same as runTarget(t,l,async,false).

Parameters:

t - The target. The 'run()' method of this object will be run in an idle thread of the pool.

l - The lock object. A thread waiting on the lock of the 'l' object will be notified, through the 'notify()' call, when the target's run method completes. If null no thread is notified.

async - If true the asynchronous mode will be used.

Returns:

True if the target was submitted to some thread. False if no idle thread could be found and the target was not submitted for execution.

runTarget

public boolean runTarget(java.lang.Runnable t,
                         java.lang.Object l,
                         boolean async,
                         boolean notifyAll)

Runs the run method of the specified target in an idle thread of this pool. When the target's run method completes, the thread waiting on the lock object is notified, if any. If there is currently no idle thread and the asynchronous mode is not used the method will block until a thread of the pool becomes idle or the calling thread is interrupted. If the asynchronous mode is used then the method will not block and will return false.

Parameters:

t - The target. The 'run()' method of this object will be run in an idle thread of the pool.

l - The lock object. A thread waiting on the lock of the 'l' object will be notified, through the 'notify()' call, when the target's run method completes. If null no thread is notified.

async - If true the asynchronous mode will be used.

notifyAll - If true, threads waiting on the lock of the 'l' object will be notified trough the 'notifyAll()' instead of the normal 'notify()' call. This is not normally needed.

Returns:

True if the target was submitted to some thread. False if no idle thread could be found and the target was not submitted for execution.

checkTargetErrors

public void checkTargetErrors()

Checks that no error or runtime exception in any target have occurred so far. If an error or runtime exception has occurred in a target's run method they are thrown by this method.

Throws:

java.lang.Error - If an error condition has been thrown by a target 'run()' method.

java.lang.RuntimeException - If a runtime exception has been thrown by a target 'run()' method.

clearTargetErrors

public void clearTargetErrors()

Clears the current target error conditions, if any. Note that a thread in the pool might have set the error conditions since the last check and that those error conditions will be lost. Likewise, before returning from this method another thread might set the error conditions. There is no guarantee that no error conditions exist when returning from this method.

In order to ensure that no error conditions exist when returning from this method cooperation from the targets and the thread using this pool is necessary (i.e. currently no targets running or waiting to run).

putInIdleList

private void putInIdleList(ThreadPool.ThreadPoolThread t)

Puts the thread 't' in the idle list. The thread 't' should be in fact idle and ready to accept a new target when it joins the idle list.

An idle thread that is already in the list should never add itself to the list before it is removed. For efficiency reasons there is no check to see if the thread is already in the list of idle threads.

If the idle list was empty 'notify()' will be called on the 'idle' array, to wake up a thread that might be waiting (within the 'getIdle()' method) on an idle thread to become available.

Parameters:

t - The thread to put in the idle list.

getIdle

private ThreadPool.ThreadPoolThread getIdle(boolean async)

Returns and idle thread and removes it from the list of idle threads. In asynchronous mode it will immediately return an idle thread, or null if none is available. In non-asynchronous mode it will block until a thread of the pool becomes idle or the calling thread is interrupted.

If in non-asynchronous mode and there are currently no idle threads available the calling thread will wait on the 'idle' array lock, until notified by 'putInIdleList()' that an idle thread might have become available.

Parameters:

async - If true asynchronous mode is used.

Returns:

An idle thread of the pool, that has been removed from the idle list, or null if none is available.