org.icij.concurrent

Class BlockingThreadPoolExecutor

java.lang.Object

java.util.concurrent.AbstractExecutorService

java.util.concurrent.ThreadPoolExecutor

org.icij.concurrent.BlockingThreadPoolExecutor

All Implemented Interfaces:

Executor, ExecutorService

public class BlockingThreadPoolExecutor
extends ThreadPoolExecutor

This class is a specialized extension of the ThreadPoolExecutor class. It is based on a version originally written by Yaneeve Shekel and Amir Kirsh with the difference that a counting Semaphore is used instead of a RejectedExecutionHandler, which makes for a simpler implementation. Two functions had been added to this subclass. 1) The execute method of the ThreadPoolExecutor will block in case the queue is full and only unblock when the queue is de-queued - that is a task that is currently in the queue is removed and handled by the ThreadPoolExecutor. 2) Client code can await for the event of all tasks being run to conclusion. Client code which actively chooses to wait for this occurrence should call await() on the instance of this ThreadPoolExecutor. This differs from ThreadPoolExecutor.awaitTermination(long, java.util.concurrent.TimeUnit) as it does not require any call to ThreadPoolExecutor.shutdown() and may be used repeatedly. Code example: BlockingThreadPoolExecutor threadPoolExecutor = new BlockingThreadPoolExecutor(5); for (int i = 0; i < 5000; i++) { threadPoolExecutor.execute(...) } try { threadPoolExecutor.await(); } catch (InterruptedException e) { // Handle error. } System.out.println("Done!"); The example above shows how 5000 tasks are run within five threads. The line with System.out.println ("Done!"); will not run until such a time when all the tasks given to the thread pool have concluded their run.

See Also:

Creating a NotifyingBlockingThreadPoolExecutor Blog

Nested Class Summary

Nested classes/interfaces inherited from class java.util.concurrent.ThreadPoolExecutor

ThreadPoolExecutor.AbortPolicy, ThreadPoolExecutor.CallerRunsPolicy, ThreadPoolExecutor.DiscardOldestPolicy, ThreadPoolExecutor.DiscardPolicy

Constructor Summary

Constructors

Constructor and Description
BlockingThreadPoolExecutor(int poolSize)
BlockingThreadPoolExecutor(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit)
BlockingThreadPoolExecutor(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, BlockingQueue<Runnable> workQueue)
BlockingThreadPoolExecutor(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, BlockingQueue<Runnable> workQueue, ThreadFactory threadFactory, RejectedExecutionHandler handler, long maximumBlockingTime, TimeUnit maximumBlockingUnit) This constructor is used in order to maintain the first functionality specified above.

Method Summary

Modifier and Type	Method and Description
protected void	afterExecute(Runnable r, Throwable t) After calling super's implementation of this method, the number of acquired permits is decremented.
void	await() A blocking wait for this ThreadPoolExecutor to be in idle state, which means that there are no more tasks in the Queue or currently executed by one of the threads.
boolean	await(long timeout, TimeUnit timeUnit) A blocking wait for this ThreadPool to be in idle state or a certain timeout to elapse.
void	execute(Runnable task) Before calling super's version of this method, a permit is acquired in order to queue the task for execution.
void	setMaximumPoolSize(int maximumPoolSize) Increase or decreases the maximum pool size by adjusting the number of permits accordingly.

Methods inherited from class java.util.concurrent.ThreadPoolExecutor

allowCoreThreadTimeOut, allowsCoreThreadTimeOut, awaitTermination, beforeExecute, finalize, getActiveCount, getCompletedTaskCount, getCorePoolSize, getKeepAliveTime, getLargestPoolSize, getMaximumPoolSize, getPoolSize, getQueue, getRejectedExecutionHandler, getTaskCount, getThreadFactory, isShutdown, isTerminated, isTerminating, prestartAllCoreThreads, prestartCoreThread, purge, remove, setCorePoolSize, setKeepAliveTime, setRejectedExecutionHandler, setThreadFactory, shutdown, shutdownNow, terminated, toString

Methods inherited from class java.util.concurrent.AbstractExecutorService

invokeAll, invokeAll, invokeAny, invokeAny, newTaskFor, newTaskFor, submit, submit, submit

Methods inherited from class java.lang.Object

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

Constructor Detail

BlockingThreadPoolExecutor

public BlockingThreadPoolExecutor(int corePoolSize,
                                  int maximumPoolSize,
                                  long keepAliveTime,
                                  TimeUnit unit,
                                  BlockingQueue<Runnable> workQueue,
                                  ThreadFactory threadFactory,
                                  RejectedExecutionHandler handler,
                                  long maximumBlockingTime,
                                  TimeUnit maximumBlockingUnit)

This constructor is used in order to maintain the first functionality specified above. It does so by using an ArrayBlockingQueue and the BlockThenRunPolicy that is defined in this class. This constructor allows to give a timeout for the wait on new task insertion and to react upon such a timeout if occurs.

Parameters:

corePoolSize - corePoolSize the number of threads to keep in the pool, even if they are idle, unless allowCoreThreadTimeOut is set

maximumPoolSize - the maximum number of threads to allow in the pool

keepAliveTime - when the number of threads is greater than the core, this is the maximum time that excess idle threads will wait for new tasks before terminating.

unit - the time unit for the keepAliveTime argument

handler - the handler to use when execution is blocked because the thread bounds and queue capacities are reached

threadFactory - the factory to use when the executor creates a new thread

maximumBlockingTime - is the maximum time to wait on the queue of tasks before throwing a RejectedExecutionException, or 0 to wait indefinitely

maximumBlockingUnit - is the unit of time to use with the previous parameter

BlockingThreadPoolExecutor

public BlockingThreadPoolExecutor(int corePoolSize,
                                  int maximumPoolSize,
                                  long keepAliveTime,
                                  TimeUnit unit,
                                  BlockingQueue<Runnable> workQueue)

BlockingThreadPoolExecutor

public BlockingThreadPoolExecutor(int corePoolSize,
                                  int maximumPoolSize,
                                  long keepAliveTime,
                                  TimeUnit unit)

BlockingThreadPoolExecutor

public BlockingThreadPoolExecutor(int poolSize)

Method Detail

execute

public void execute(Runnable task)

Before calling super's version of this method, a permit is acquired in order to queue the task for execution. This prevents the queue from being flooded with more tasks than the pool can execute at one go.

Specified by:

execute in interface Executor

Overrides:

execute in class ThreadPoolExecutor

Throws:

RejectedExecutionException - if the thread is interrupted while waiting for a slot to become available to execute a task.

See Also:

ThreadPoolExecutor.execute(Runnable)

afterExecute

protected void afterExecute(Runnable r,
                            Throwable t)

After calling super's implementation of this method, the number of acquired permits is decremented. Finally, if the amount of tasks currently running is zero the synchronizer's signalAll() method is invoked, thus anyone awaiting on this instance of ThreadPoolExecutor is released.

Overrides:

afterExecute in class ThreadPoolExecutor

See Also:

ThreadPoolExecutor.afterExecute(Runnable, Throwable)

setMaximumPoolSize

public void setMaximumPoolSize(int maximumPoolSize)

Increase or decreases the maximum pool size by adjusting the number of permits accordingly. This method will block (up till the maximum blocking time, if specified) when decreasing the pool size, until the number of threads is reduced to the desired size, but may be interrupted.

Overrides:

setMaximumPoolSize in class ThreadPoolExecutor

Throws:

RuntimeException - if the pool size could not be decreased within the maximum blocking time.

See Also:

ThreadPoolExecutor.setMaximumPoolSize(int)

await

public void await()
           throws InterruptedException

A blocking wait for this ThreadPoolExecutor to be in idle state, which means that there are no more tasks in the Queue or currently executed by one of the threads. BE AWARE that this method may get out from blocking state when a task is currently sent to the ThreadPoolExecutor not from this thread context. Thus it is not safe to call this method in case there are several threads feeding the ThreadPoolExecutor with tasks (calling execute). The safe way to call this method is from the thread that is calling execute and when there is only one such thread. Note that this method differs from awaitTermination, as it can be called without shutting down the ThreadPoolExecutor.

Throws:

InterruptedException - when the internal condition throws it.

await

public boolean await(long timeout,
                     TimeUnit timeUnit)
              throws InterruptedException

A blocking wait for this ThreadPool to be in idle state or a certain timeout to elapse. Works the same as the await() method, except for adding the timeout condition.

Returns:

false if the timeout elapsed, true if the synchronous event we are waiting for had happened

Throws:

InterruptedException - when the internal condition throws it.

See Also:

for more details.