org.knime.core.util
Class ThreadPool

java.lang.Object
  extended by org.knime.core.util.ThreadPool

public class ThreadPool
extends Object

Implements a sophisticated thread pool.

Author:
Thorsten Meinl, University of Konstanz

Constructor Summary
  ThreadPool(int maxThreads)
          Creates a new ThreadPool with a maximum number of threads.
protected ThreadPool(int maxThreads, ThreadPool parent)
          Creates a new sub pool.
 
Method Summary
 ThreadPool createSubPool()
          Creates a sub pool that shares the threads with this (parent) pool.
 ThreadPool createSubPool(int maxThreads)
          Creates a sub pool that shares the threads with this (parent) pool.
static ThreadPool currentPool()
          If the current thread is taken out of a thread pool, this method will return the thread pool.
<T> Future<T>
enqueue(Callable<T> t)
          Submits a value-returning task for execution and returns a Future representing the pending results of the task.
 Future<?> enqueue(Runnable r)
          Submits a Runnable task for execution and returns a Future representing that task.
protected  void finalize()
          
 int getMaxThreads()
          Returns the maximum number of threads in the pool.
(package private)  int getQueueSize()
          Returns the size of the future queue (needed by the unit test).
 int getRunningThreads()
          Returns the number of currently running threads in this pool and its sub pools.
<T> T
runInvisible(Callable<T> r)
          Executes the runnable in the current thread.
 void setMaxThreads(int newValue)
          Sets the maximum number of threads in the pool.
 void shutdown()
          Shuts the pool down, still running threads are not interrupted.
<T> Future<T>
submit(Callable<T> task)
          Submits a value-returning task for execution and returns a Future representing the pending results of the task.
 Future<?> submit(Runnable task)
          Submits a Runnable task for execution and returns a Future representing that task.
<T> Future<T>
trySubmit(Callable<T> t)
          Tries to submits a value-returning task for immediate execution and returns a Future representing the pending results of the task if a thread is free.
 Future<?> trySubmit(Runnable r)
          Tries to submits a Runnable task for immediate execution and returns a Future representing the task if a thread is free.
 void waitForTermination()
          Waits until all jobs in this pool and its sub pools have been finished.
protected  void workerFinished(org.knime.core.util.ThreadPool.Worker w)
          This method is called every time a worker has finished.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ThreadPool

public ThreadPool(int maxThreads)
Creates a new ThreadPool with a maximum number of threads.

Parameters:
maxThreads - the maximum number of threads

ThreadPool

protected ThreadPool(int maxThreads,
                     ThreadPool parent)
Creates a new sub pool.

Parameters:
maxThreads - the maximum number of threads in the pool
parent - the parent pool
Method Detail

createSubPool

public ThreadPool createSubPool()
Creates a sub pool that shares the threads with this (parent) pool.

Returns:
a thread pool

createSubPool

public ThreadPool createSubPool(int maxThreads)
Creates a sub pool that shares the threads with this (parent) pool. The maximum number of threads in this and all its sub pools does not exceed the maximum thread number for this pool, even if a sub pool is created with a higher thread count.

Parameters:
maxThreads - the maximum number of threads in the sub pool
Returns:
a thread pool

enqueue

public <T> Future<T> enqueue(Callable<T> t)
Submits a value-returning task for execution and returns a Future representing the pending results of the task. The method immediately returns and puts the runnable into a queue.

If you would like to immediately block waiting for a task, you can use constructions of the form result = exec.submit(aCallable).get();

Note: The Executors class includes a set of methods that can convert some other common closure-like objects, for example, PrivilegedAction to Callable form so they can be submitted.

Type Parameters:
T - any result type
Parameters:
t - the task to submit
Returns:
a Future representing pending completion of the task
Throws:
NullPointerException - if task null
See Also:
submit(Callable)

enqueue

public Future<?> enqueue(Runnable r)
Submits a Runnable task for execution and returns a Future representing that task. The method immediately returns and puts the runnable into a queue.

Parameters:
r - the task to submit
Returns:
a Future representing pending completion of the task, and whose get() method will return null upon completion.
Throws:
NullPointerException - if task null
See Also:
submit(Runnable)

trySubmit

public <T> Future<T> trySubmit(Callable<T> t)
Tries to submits a value-returning task for immediate execution and returns a Future representing the pending results of the task if a thread is free. If no thread is currently available null is returned and the task is not queued.

If you would like to immediately block waiting for a task, you can use constructions of the form result = exec.submit(aCallable).get();

Note: The Executors class includes a set of methods that can convert some other common closure-like objects, for example, PrivilegedAction to Callable form so they can be submitted.

Type Parameters:
T - any result type
Parameters:
t - the task to submit
Returns:
a Future representing pending completion of the task or null if no thread was available
Throws:
NullPointerException - if task null
See Also:
submit(Callable)

trySubmit

public Future<?> trySubmit(Runnable r)
Tries to submits a Runnable task for immediate execution and returns a Future representing the task if a thread is free. If no thread is currently available null is returned and the task is not queued.

Parameters:
r - the task to submit
Returns:
a Future representing pending completion of the task, and whose get() method will return null upon completion.
Throws:
NullPointerException - if task null
See Also:
submit(Runnable)

getMaxThreads

public int getMaxThreads()
Returns the maximum number of threads in the pool.

Returns:
the maximum thread number

getRunningThreads

public int getRunningThreads()
Returns the number of currently running threads in this pool and its sub pools.

Returns:
the number of running threads

runInvisible

public <T> T runInvisible(Callable<T> r)
               throws ExecutionException
Executes the runnable in the current thread. If the current thread is taken out of this pool or any ancestor pool the number of invisible threads is increased, so that it is not counted and one additional thread is allowed to run. This method should only be used if the Runnable does nothing more than submitting jobs.

Type Parameters:
T - Type of the argument (result type)
Parameters:
r - A callable, which will be executed by the thread invoking this method.
Returns:
T The result of the callable.
Throws:
IllegalThreadStateException - if the current thread is not taken out of a thread pool
ExecutionException - if the callable could not be executed for some reason

setMaxThreads

public void setMaxThreads(int newValue)
Sets the maximum number of threads in the pool. If the new value is smaller than the old value running surplus threads will not be interrupted. If the new value is bigger than the old one, waiting jobs will be started immediately.

Parameters:
newValue - the new maximum thread number

shutdown

public void shutdown()
Shuts the pool down, still running threads are not interrupted.


submit

public <T> Future<T> submit(Callable<T> task)
                 throws InterruptedException
Submits a value-returning task for execution and returns a Future representing the pending results of the task. The method blocks until a thread is available.

If you would like to immediately block waiting for a task, you can use constructions of the form result = exec.submit(aCallable).get();

Note: The Executors class includes a set of methods that can convert some other common closure-like objects, for example, PrivilegedAction to Callable form so they can be submitted.

Type Parameters:
T - any result type
Parameters:
task - the task to submit
Returns:
a Future representing pending completion of the task
Throws:
NullPointerException - if task null
InterruptedException - if the thread is interrupted
See Also:
enqueue(Callable)

submit

public Future<?> submit(Runnable task)
                 throws InterruptedException
Submits a Runnable task for execution and returns a Future representing that task. The method blocks until a free thread is available.

Parameters:
task - the task to submit
Returns:
a Future representing pending completion of the task, and whose get() method will return null upon completion.
Throws:
NullPointerException - if task null
InterruptedException - if the thread is interrupted
See Also:
enqueue(Runnable)

waitForTermination

public void waitForTermination()
                        throws InterruptedException
Waits until all jobs in this pool and its sub pools have been finished.

Throws:
InterruptedException - if the thread is interrupted while waiting

workerFinished

protected void workerFinished(org.knime.core.util.ThreadPool.Worker w)
This method is called every time a worker has finished.

Parameters:
w - the finished worker

finalize

protected void finalize()
                 throws Throwable

Overrides:
finalize in class Object
Throws:
Throwable

currentPool

public static ThreadPool currentPool()
If the current thread is taken out of a thread pool, this method will return the thread pool. Otherwise it will return null.

Returns:
a thread pool or null

getQueueSize

int getQueueSize()
Returns the size of the future queue (needed by the unit test).

Returns:
the queue size


Copyright, 2003 - 2010. All rights reserved.
University of Konstanz, Germany.
Chair for Bioinformatics and Information Mining, Prof. Dr. Michael R. Berthold.
You may not modify, publish, transmit, transfer or sell, reproduce, create derivative works from, distribute, perform, display, or in any way exploit any of the content, in whole or in part, except as otherwise expressly permitted in writing by the copyright owner or as specified in the license file distributed with this product.