jj2000.j2k.util

Class ThreadPool

java.lang.Object

jj2000.j2k.util.ThreadPool

public class ThreadPool
extends 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, Thread, Error, RuntimeException

Field Summary

Fields

Modifier and Type	Field and Description
static String	CONCURRENCY_PROP_NAME The name of the property that sets the concurrency level: jj2000.j2k.util.ThreadPool.concurrency

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
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.
int	getSize() Returns the size of the pool.
boolean	runTarget(Runnable t, Object l) Runs the run method of the specified target in an idle thread of this pool.
boolean	runTarget(Runnable t, Object l, boolean async) Runs the run method of the specified target in an idle thread of this pool.
boolean	runTarget(Runnable t, 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 String CONCURRENCY_PROP_NAME

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

See Also:

Constant Field Values

Constructor Detail

ThreadPool

public ThreadPool(int size,
                  int priority,
                  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(Runnable t,
                         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(Runnable t,
                         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(Runnable t,
                         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:

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

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