org.jtrim2.executor

Class ThreadPoolTaskExecutor

java.lang.Object

org.jtrim2.executor.DelegatedTaskExecutorService

org.jtrim2.executor.ThreadPoolTaskExecutor

All Implemented Interfaces:

Executor, ContextAwareTaskExecutor, ContextAwareTaskExecutorService, MonitorableTaskExecutor, MonitorableTaskExecutorService, TaskExecutor, TaskExecutorService

public final class ThreadPoolTaskExecutor
extends DelegatedTaskExecutorService
implements MonitorableTaskExecutorService

A TaskExecutorService implementation which executes submitted tasks on a group of threads. This implementation is similar to the java.util.concurrent.ThreadPoolExecutor in Java but implements TaskExecutorService instead of ExecutorService.

Executing new tasks

Tasks can be submitted by one of the submit or execute methods.

When a new task is submitted, ThreadPoolTaskExecutor and there is an idle thread waiting for tasks to be executed, an attempt will be made to execute the submitted task on an idle thread and no new thread will be started. This attempt fails only rarely under extreme contention, in which case a new thread is started even though there was an idle thread.

In case there is no idle thread waiting and a new thread can be started without exceeding the maximum number of allowed threads, a new thread will be started to execute the submitted task.

In case there is no idle thread waiting and there are already as many threads executing tasks as allowed, the submitted task will be added to an internal queue from which the background threads will eventually remove and execute them. Note that the size of the queue can be limited and if this limit is reached, the submitting submit or execute method will block and wait until the task can be added to the queue.

Cancellation of tasks

Canceling a task which was not yet started and is still in the queue will immediately remove it from the queue and no references will be retained to the task (allowing it to be garbage collected if not referenced by external code).

Canceling a task will cause the CancellationToken passed to it, signal cancellation request. In this case the task may decide if it is to be canceled or not. If the task throws an OperationCanceledException, task execution is considered to be canceled. Note that if the task throws an OperationCanceledException it is always assumed to be canceled, even if the CancellationToken does not signal a cancellation request.

Number of referenced tasks

The maximum number of tasks referenced by a ThreadPoolTaskExecutor at any given time is the maximum size of its queue plus the maximum number of allowed threads. The ThreadPoolTaskExecutor will never reference tasks more than this. Note however, that not yet returned execute methods always reference their task specified in their argument (obviously this is unavoidable) and there is no limit on how many times the user can concurrently call these methods.

Terminating ThreadPoolTaskExecutor

The ThreadPoolTaskExecutor must always be shut down when no longer needed, so that it may shutdown its threads. If the user fails to shut down the ThreadPoolTaskExecutor (either by calling shutdown() or shutdownAndCancel()) and the garbage collector notifies the ThreadPoolTaskExecutor that it has become unreachable (through finalizers), it will be logged as an error using the logging facility of Java (in a Level.SEVERE log message).

Comparison with ThreadPoolExecutor

Table for quick feature comparison

Feature	ThreadPoolTaskExecutor	ThreadPoolExecutor
Immediate cancellation	Yes.	No, tasks remain in the queue until attempted to be executed.
Cancellation strategy of executing tasks	Relies on a CancellationToken.	Relies on thread interrupts.
Tracking the state of a submitted task	Not directly. Submitted tasks must be wrapped and CompletionStage must be used to listen for completion	Possible using the returned Future.
Waiting until the task finished executing	Possible using the returned CompletionStage.	Not possible, if task was canceled by shutdownNow.
Do cleanup even if task was canceled	Yes, using the returned CompletionStage.	No, only if the task was refused when submitting.
User defined thread factory	Yes	Yes
Automatically stop idle threads	Yes	Yes
Limit the number of threads	Yes	Yes
New thread start policy	Starts a new thread only if there are no idle threads and the maximum number of threads was not reached.	Starts a new thread always unless the maximum number of threads was reached.
Increase number of threads over the limit, if queue is full	No	Yes and configurable
User defined implementation for the internal queue	No	Yes
Throttle, when the task queue is large	Yes	Yes, with some limitations
Asynchronous notification of termination	Yes	Only to subclasses
Shut down and cancel submitted tasks	Yes	Yes

Thread safety

Methods of this class are safely accessible from multiple threads concurrently.

Synchronization transparency

Method of this class are not synchronization transparent unless otherwise noted.

Field Summary

Fields inherited from class org.jtrim2.executor.DelegatedTaskExecutorService

wrappedExecutor

Constructor Summary

Constructors

Constructor and Description
ThreadPoolTaskExecutor(String poolName) Creates a new ThreadPoolTaskExecutor initialized with specified name.
ThreadPoolTaskExecutor(String poolName, int maxThreadCount) Creates a new ThreadPoolTaskExecutor initialized with the given properties.
ThreadPoolTaskExecutor(String poolName, int maxThreadCount, int maxQueueSize) Creates a new ThreadPoolTaskExecutor initialized with the given properties.
ThreadPoolTaskExecutor(String poolName, int maxThreadCount, int maxQueueSize, long idleTimeout, TimeUnit timeUnit) Creates a new ThreadPoolTaskExecutor initialized with the given properties.

Method Summary

Modifier and Type	Method and Description
void	dontNeedShutdown() Specifies that this ThreadPoolTaskExecutor does not need to be shut down.
long	getIdleTimeout(TimeUnit timeUnit) Returns the currently set timeout value after idle threads should stop.
int	getMaxQueueSize() Returns the currently set maximum size for the queue of tasks scheduled to be executed.
int	getMaxThreadCount() Returns the currently set maximum thread to be used by this executor.
long	getNumberOfExecutingTasks() Returns the approximate number of tasks currently being executed.
long	getNumberOfQueuedTasks() Returns the approximate number of tasks currently queued to this executor.
String	getPoolName() Returns the name of this ThreadPoolTaskExecutor as specified at construction time.
boolean	isExecutingInThis() Returns true if the calling code is executing in the context of this executor.
void	setIdleTimeout(long idleTimeout, TimeUnit timeUnit) Sets the timeout value after idle threads should terminate.
void	setMaxQueueSize(int maxQueueSize) Sets the maximum number of tasks allowed to be stored in the internal queue.
void	setMaxThreadCount(int maxThreadCount) Sets the maximum number of threads allowed to execute submitted tasks concurrently.
void	setThreadFactory(ThreadFactory threadFactory) Sets the ThreadFactory which is used to create worker threads for this executor.
void	shutdown() Shuts down this TaskExecutorService, so that it will not execute tasks submitted to it after this method call returns.
void	shutdownAndCancel() Shuts down this TaskExecutorService and cancels already submitted tasks, so that it will not execute tasks submitted to it after this method call returns.
String	toString() Returns the string representation of this executor in no particular format.

Methods inherited from class org.jtrim2.executor.DelegatedTaskExecutorService

addTerminateListener, awaitTermination, execute, execute, executeFunction, executeStaged, isShutdown, isTerminated, tryAwaitTermination

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.jtrim2.executor.TaskExecutorService

addTerminateListener, awaitTermination, isShutdown, isTerminated, tryAwaitTermination

Methods inherited from interface org.jtrim2.executor.TaskExecutor

execute, execute, executeFunction, executeStaged

Constructor Detail

ThreadPoolTaskExecutor

public ThreadPoolTaskExecutor(String poolName)

Creates a new ThreadPoolTaskExecutor initialized with specified name.

The default maximum number of threads is Runtime.getRuntime().availableProcessors().

The default maximum queue size is Integer.MAX_VALUE making it effectively unbounded.

The default timeout value after idle threads stop is 5 seconds.

The newly created ThreadPoolTaskExecutor will not have any thread started. Threads will only be started when submitting tasks (as required).

Parameters:

poolName - the name of this ThreadPoolTaskExecutor for logging and debugging purposes. Setting a descriptive name might help when debugging or reading logs. This argument cannot be null.

Throws:

IllegalArgumentException - thrown if an illegal value was specified for any of the int arguments

NullPointerException - thrown if the specified name for this ThreadPoolTaskExecutor is null

ThreadPoolTaskExecutor

public ThreadPoolTaskExecutor(String poolName,
                              int maxThreadCount)

Creates a new ThreadPoolTaskExecutor initialized with the given properties.

The default maximum queue size is Integer.MAX_VALUE making it effectively unbounded.

The default timeout value after idle threads stop is 5 seconds.

The newly created ThreadPoolTaskExecutor will not have any thread started. Threads will only be started when submitting tasks (as required).

Parameters:

poolName - the name of this ThreadPoolTaskExecutor for logging and debugging purposes. Setting a descriptive name might help when debugging or reading logs. This argument cannot be null.

maxThreadCount - the maximum number of threads to be executing submitted tasks concurrently. The ThreadPoolTaskExecutor will never execute more tasks concurrently as this number. This argument must be greater than or equal to 1.

Throws:

IllegalArgumentException - thrown if an illegal value was specified for any of the int arguments

NullPointerException - thrown if the specified name for this ThreadPoolTaskExecutor is null

ThreadPoolTaskExecutor

public ThreadPoolTaskExecutor(String poolName,
                              int maxThreadCount,
                              int maxQueueSize)

Creates a new ThreadPoolTaskExecutor initialized with the given properties.

The default timeout value after idle threads stop is 5 seconds.

The newly created ThreadPoolTaskExecutor will not have any thread started. Threads will only be started when submitting tasks (as required).

Parameters:

poolName - the name of this ThreadPoolTaskExecutor for logging and debugging purposes. Setting a descriptive name might help when debugging or reading logs. This argument cannot be null.

maxThreadCount - the maximum number of threads to be executing submitted tasks concurrently. The ThreadPoolTaskExecutor will never execute more tasks concurrently as this number. This argument must be greater than or equal to 1.

maxQueueSize - the maximum size of the internal queue to store tasks not yet executed due to all threads being busy executing tasks. This argument must be greater than or equal to 1 and is recommended to be (but not required) greater than or equal to maxThreadCount.

Throws:

IllegalArgumentException - thrown if an illegal value was specified for any of the int arguments

NullPointerException - thrown if the specified name for this ThreadPoolTaskExecutor is null

ThreadPoolTaskExecutor

public ThreadPoolTaskExecutor(String poolName,
                              int maxThreadCount,
                              int maxQueueSize,
                              long idleTimeout,
                              TimeUnit timeUnit)

Creates a new ThreadPoolTaskExecutor initialized with the given properties.

The newly created ThreadPoolTaskExecutor will not have any thread started. Threads will only be started when submitting tasks (as required).

Parameters:

poolName - the name of this ThreadPoolTaskExecutor for logging and debugging purposes. Setting a descriptive name might help when debugging or reading logs. This argument cannot be null.

maxThreadCount - the maximum number of threads to be executing submitted tasks concurrently. The ThreadPoolTaskExecutor will never execute more tasks concurrently as this number. This argument must be greater than or equal to 1.

maxQueueSize - the maximum size of the internal queue to store tasks not yet executed due to all threads being busy executing tasks. This argument must be greater than or equal to 1 and is recommended to be (but not required) greater than or equal to maxThreadCount.

idleTimeout - the time in the given time unit after idle threads should stop. That is if a thread goes idle (i.e.: there are no submitted tasks), it will wait this amount of time before giving up waiting for submitted tasks. The thread may be restarted if needed later. It is recommended to use a reasonably low value for this argument (but not too low), so even if this ThreadPoolTaskExecutor has not been shut down (due to a bug), threads will still terminate allowing the JVM to terminate as well (if there are no more non-daemon threads). This argument must be greater than or equal to zero.

timeUnit - the time unit of the idleTimeout argument. This argument cannot be null.

Throws:

IllegalArgumentException - thrown if an illegal value was specified for any of the int arguments

NullPointerException - thrown if any of the arguments is null

Method Detail

dontNeedShutdown

public void dontNeedShutdown()

Specifies that this ThreadPoolTaskExecutor does not need to be shut down. Calling this method prevents this executor to be shut down automatically when there is no more reference to this executor, which also prevents logging a message if this executor has not been shut down. This method might be called if you do not plan to shutdown this executor but instead want to rely on the threads of this executor to automatically shutdown after a small timeout.

setThreadFactory

public void setThreadFactory(ThreadFactory threadFactory)

Sets the ThreadFactory which is used to create worker threads for this executor. Already started workers are not affected by this method call but workers created after this method call will use the currently set ThreadFactory.

It is recommended to call this method before submitting any task to this executor. Doing so guarantees that all worker threads of this executor will be created by the specified ThreadFactory.

The default ThreadFactory used by this executor is a ExecutorsEx.NamedThreadFactory creating non-daemon threads.

Parameters:

threadFactory - the ThreadFactory which is used to create worker threads for this executor. This argument cannot be null.

Throws:

NullPointerException - thrown if the specified thread factory is null

shutdown

public void shutdown()

Shuts down this TaskExecutorService, so that it will not execute tasks submitted to it after this method call returns.

Already submitted tasks will execute normally but tasks submitted after this method returns will immediately be completed exceptionally with an OperationCanceledException.

Note that it is possible, that some tasks are submitted concurrently with this call. Those tasks can be either canceled or executed normally, depending on the circumstances.

If currently executing tasks should be canceled as well, use the TaskExecutorService.shutdownAndCancel() method to shutdown this TaskExecutorService.

This method call is idempotent. That is, calling it multiple times must have no further effect.

Specified by:

shutdown in interface TaskExecutorService

Overrides:

shutdown in class DelegatedTaskExecutorService

See Also:

TaskExecutorService.shutdownAndCancel()

shutdownAndCancel

public void shutdownAndCancel()

Shuts down this TaskExecutorService and cancels already submitted tasks, so that it will not execute tasks submitted to it after this method call returns.

Already submitted tasks will be canceled and the tasks may detect this cancellation request by inspecting their CancellationToken but tasks submitted after this method returns will immediately be completed exceptionally with an OperationCanceledException.

Note that it is possible, that some tasks are submitted concurrently with this call. Those tasks may be treated as if they were submitted before this method call or as if they were submitted after.

If currently executing tasks should be left executing, use the TaskExecutorService.shutdown() method instead to shutdown this TaskExecutorService.

This method call is idempotent. That is, calling it multiple times must have no further effect. Note however, that calling this method after the shutdown() method is meaningful because this method will cancel ongoing tasks.

Specified by:

shutdownAndCancel in interface TaskExecutorService

Overrides:

shutdownAndCancel in class DelegatedTaskExecutorService

See Also:

TaskExecutorService.shutdown()

getNumberOfQueuedTasks

public long getNumberOfQueuedTasks()

Returns the approximate number of tasks currently queued to this executor. The queued tasks are not currently executing but are scheduled to be executed in the future.

Note that the value returned by this method should be considered unreliable and cannot be used for synchronization purposes.

Specified by:

getNumberOfQueuedTasks in interface MonitorableTaskExecutor

Returns:

the approximate number of tasks currently queued to this executor. This method always returns a value greater than or equal to zero.

getNumberOfExecutingTasks

public long getNumberOfExecutingTasks()

Returns the approximate number of tasks currently being executed.

Note that the value returned by this method should be considered unreliable and cannot be used for synchronization purposes.

Specified by:

getNumberOfExecutingTasks in interface MonitorableTaskExecutor

Returns:

the approximate number of tasks currently being executed. This method always returns a value greater than or equal to zero.

isExecutingInThis

public boolean isExecutingInThis()

Returns true if the calling code is executing in the context of this executor. That is, it is executed by a task submitted to this executor.

This method can be used to check that a method call is executing in the context it was designed for.

Specified by:

isExecutingInThis in interface ContextAwareTaskExecutor

Returns:

true if the calling code is executing in the context of this executor, false otherwise

setMaxThreadCount

public void setMaxThreadCount(int maxThreadCount)

Sets the maximum number of threads allowed to execute submitted tasks concurrently.

Setting this property may not have an immediate effect. Setting it to a higher value as was set previously, will not cause new thread to be started if the internal queue is not empty but subsequent submit and execute methods will detect that they can start new threads. Setting this property to a lower value as was set previously, will not cause threads to stop even if they are currently idle. It just prevents new threads to be created until the number of currently running threads drops below this limit (as threads stop due to too long idle time).

Note that setting this property before a task was submitted to this ThreadPoolTaskExecutor is guaranteed to have immediate effect.

Parameters:

maxThreadCount - the maximum number of threads allowed to be executing submitted tasks concurrently. This argument must be greater than or equal to 1.

Throws:

IllegalArgumentException - if the specified maxThreadCount is less than 1

getMaxThreadCount

public int getMaxThreadCount()

Returns the currently set maximum thread to be used by this executor.

The return value of this method is for information purpose only. Due to concurrent sets and already started threads, there is no guarantee that the return value is truly being honored at the moment. See setMaxThreadCount for details on how this property works.

Returns:

the currently set maximum thread to be used by this executor. This value is always greater than or equal to one.

setMaxQueueSize

public void setMaxQueueSize(int maxQueueSize)

Sets the maximum number of tasks allowed to be stored in the internal queue.

Setting this property higher than it was set previously will have an immediate effect and currently blocking submit and execute will recheck if they can add the submitted task to the queue. Setting this property lower, however, will not remove tasks from the queue but will prevent more tasks to be added to the queue before the number of tasks in the queue drops below this limit.

Parameters:

maxQueueSize - the maximum number of tasks allowed to be stored in the internal queue. This argument must be greater than or equal to 1.

Throws:

IllegalArgumentException - if the specified maxQueueSize is less than 1

getMaxQueueSize

public int getMaxQueueSize()

Returns the currently set maximum size for the queue of tasks scheduled to be executed.

The return value of this method is for information purpose only. Due to concurrent sets and already queued tasks, there is no guarantee that the return value is truly being honored at the moment. See setMaxQueueSize for details on how this property works.

Returns:

the currently set maximum size for the queue of tasks scheduled to be executed. This value is always greater than or equal to one.

setIdleTimeout

public void setIdleTimeout(long idleTimeout,
                           TimeUnit timeUnit)

Sets the timeout value after idle threads should terminate. That is, threads will terminate if they waited for at least this much time and there was no submitted task for them to execute.

Setting this property has an immediate effect.

Parameters:

idleTimeout - the timeout value in the given time unit after idle threads should terminate. This argument must be greater than or equal to zero.

timeUnit - the time unit of the idleTimeout argument. This argument cannot be null.

Throws:

IllegalArgumentException - thrown if the specified timeout value is less than zero

NullPointerException - thrown if the specified time unit argument is null

getIdleTimeout

public long getIdleTimeout(TimeUnit timeUnit)

Returns the currently set timeout value after idle threads should stop.

The return value of this method is for information purpose only. Due to concurrent sets, there is no guarantee that the return value is truly being honored at the moment. See setIdleTimeout for details on how this property works.

Parameters:

timeUnit - the time unit in which the result is request. This argument cannot be null.

Returns:

the currently set timeout value after idle threads should stop. The return value might not be exactly what was set by the previous invocation to setIdleTimeout due to rounding errors. This method always returns a values greater than or equal to zero.

Throws:

NullPointerException - thrown if the specified time unit is null

getPoolName

public String getPoolName()

Returns the name of this ThreadPoolTaskExecutor as specified at construction time.

Returns:

the name of this ThreadPoolTaskExecutor as specified at construction time. This method never returns null.

toString

public String toString()

Returns the string representation of this executor in no particular format.

This method is intended to be used for debugging only.

Overrides:

toString in class DelegatedTaskExecutorService

Returns:

the string representation of this object in no particular format. This method never returns null.