org.jboss.threads

Class EnhancedQueueExecutor

java.lang.Object

java.util.concurrent.AbstractExecutorService

org.jboss.threads.EnhancedQueueExecutor

All Implemented Interfaces:

Executor, ExecutorService, ManageableThreadPoolExecutorService

public final class EnhancedQueueExecutor
extends AbstractExecutorService
implements ManageableThreadPoolExecutorService

A task-or-thread queue backed thread pool executor service. Tasks are added in a FIFO manner, and consumers in a LIFO manner. Threads are only ever created in the event that there are no idle threads available to service a task, which, when combined with the LIFO-based consumer behavior, means that the thread pool will generally trend towards the minimum necessary size. In addition, the optional growth resistance feature can be used to further govern the thread pool size.

New instances of this thread pool are created by constructing and configuring a EnhancedQueueExecutor.Builder instance, and calling its build() method.

Author:

David M. Lloyd

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	EnhancedQueueExecutor.Builder The builder class for an EnhancedQueueExecutor.

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	DISABLE_HINT A global hint which establishes whether it is recommended to disable uses of EnhancedQueueExecutor.

Method Summary

Modifier and Type	Method and Description
void	allowCoreThreadTimeOut(boolean value) Establish whether core threads are allowed to time out.
boolean	allowsCoreThreadTimeOut() Determine whether core threads are allowed to time out.
boolean	awaitTermination(long timeout, TimeUnit unit) Wait for the thread pool to complete termination.
void	execute(Runnable runnable) Execute a task.
int	getActiveCount() Get an estimate of the number of threads which are currently doing work on behalf of the thread pool.
long	getCompletedTaskCount() Get an estimate of the number of tasks completed by this thread pool.
int	getCorePoolSize() Get the core pool size.
Thread.UncaughtExceptionHandler	getExceptionHandler() Get the exception handler to use for uncaught exceptions.
float	getGrowthResistance() Get the thread pool growth resistance.
Executor	getHandoffExecutor() Get the executor to delegate to in the event of task rejection.
long	getKeepAliveTime(TimeUnit keepAliveUnits) Get the thread keep-alive time.
int	getLargestPoolSize() Get an estimate of the peak number of threads that the pool has ever held.
int	getLargestQueueSize() Get an estimate of the peak size of the queue.
int	getMaximumPoolSize() Get the maximum pool size.
int	getMaximumQueueSize() Get the maximum queue size.
int	getPoolSize() Get an estimate of the current number of active threads in the pool.
int	getQueueSize() Get an estimate of the current queue size.
long	getRejectedTaskCount() Get an estimate of the total number of tasks ever rejected by this thread pool for any reason.
long	getSubmittedTaskCount() Get an estimate of the total number of tasks ever submitted to this thread pool.
StandardThreadPoolMXBean	getThreadPoolMXBean() Create or acquire an MXBean instance for this thread pool.
boolean	isShutdown() Determine whether shutdown was requested on this thread pool.
boolean	isTerminated() Determine whether shutdown has completed on this thread pool.
boolean	isTerminating() Determine if this thread pool is in the process of terminating but has not yet completed.
int	prestartAllCoreThreads() Start all core threads.
boolean	prestartCoreThread() Start an idle core thread.
void	setCorePoolSize(int corePoolSize) Set the core pool size.
void	setExceptionHandler(Thread.UncaughtExceptionHandler exceptionHandler) Set the exception handler to use for uncaught exceptions.
void	setGrowthResistance(float growthResistance) Set the growth resistance factor.
void	setHandoffExecutor(Executor handoffExecutor) Set the executor to delegate to in the event of task rejection.
void	setKeepAliveTime(long keepAliveTime, TimeUnit keepAliveUnits) Set the thread keep-alive time.
void	setMaximumPoolSize(int maxPoolSize) Set the maximum pool size.
void	setMaximumQueueSize(int maxQueueSize) Set the maximum queue size.
void	setTerminationTask(Runnable terminationTask) Set the termination task, overwriting any previous setting.
void	shutdown() Request that shutdown be initiated for this thread pool.
void	shutdown(boolean interrupt) Initiate shutdown of this thread pool.
List<Runnable>	shutdownNow() Attempt to stop the thread pool immediately by interrupting all running threads and de-queueing all pending tasks.

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, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.concurrent.ExecutorService

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

Field Detail

DISABLE_HINT

public static final boolean DISABLE_HINT

A global hint which establishes whether it is recommended to disable uses of EnhancedQueueExecutor. This hint defaults to false but can be changed to true by setting the jboss.threads.eqe.disable property to true before this class is initialized.

Method Detail

execute

public void execute(Runnable runnable)

Execute a task.

Specified by:

execute in interface Executor

Parameters:

runnable - the task to execute (must not be null)

shutdown

public void shutdown()

Request that shutdown be initiated for this thread pool. This is equivalent to calling shutdown(false); see that method for more information.

Specified by:

shutdown in interface ExecutorService

shutdownNow

public List<Runnable> shutdownNow()

Attempt to stop the thread pool immediately by interrupting all running threads and de-queueing all pending tasks. The thread pool might not be fully stopped when this method returns, if a currently running task does not respect interruption.

Specified by:

shutdownNow in interface ExecutorService

Returns:

a list of pending tasks (not null)

isShutdown

public boolean isShutdown()

Determine whether shutdown was requested on this thread pool.

Specified by:

isShutdown in interface ExecutorService

Returns:

true if shutdown was requested, false otherwise

isTerminated

public boolean isTerminated()

Determine whether shutdown has completed on this thread pool.

Specified by:

isTerminated in interface ExecutorService

Returns:

true if shutdown has completed, false otherwise

awaitTermination

public boolean awaitTermination(long timeout,
                                TimeUnit unit)
                         throws InterruptedException

Wait for the thread pool to complete termination. If the timeout expires before the thread pool is terminated, false is returned. If the calling thread is interrupted before the thread pool is terminated, then an InterruptedException is thrown.

Specified by:

awaitTermination in interface ExecutorService

Parameters:

timeout - the amount of time to wait (must be ≥ 0)

unit - the unit of time to use for waiting (must not be null)

Returns:

true if the thread pool terminated within the given timeout, false otherwise

Throws:

InterruptedException - if the calling thread was interrupted before either the time period elapsed or the pool terminated successfully

getThreadPoolMXBean

public StandardThreadPoolMXBean getThreadPoolMXBean()

Description copied from interface: ManageableThreadPoolExecutorService

Create or acquire an MXBean instance for this thread pool. Note that the thread pool itself will not do anything in particular to register (or unregister) the MXBean with a JMX server; that is the caller's responsibility.

Specified by:

getThreadPoolMXBean in interface ManageableThreadPoolExecutorService

Returns:

the MXBean instance (must not be null)

shutdown

public void shutdown(boolean interrupt)

Initiate shutdown of this thread pool. After this method is called, no new tasks will be accepted. Once the last task is complete, the thread pool will be terminated and its termination task will be called. Calling this method more than once has no additional effect, unless all previous calls had the interrupt parameter set to false and the subsequent call sets it to true, in which case all threads in the pool will be interrupted.

Parameters:

interrupt - true to request that currently-running tasks be interrupted; false otherwise

isTerminating

public boolean isTerminating()

Determine if this thread pool is in the process of terminating but has not yet completed.

Returns:

true if the thread pool is terminating, or false if the thread pool is not terminating or has completed termination

prestartCoreThread

public boolean prestartCoreThread()

Start an idle core thread. Normally core threads are only begun when a task was submitted to the executor but no thread is immediately available to handle the task.

Returns:

true if a core thread was started, or false if all core threads were already running or if the thread failed to be created for some other reason

prestartAllCoreThreads

public int prestartAllCoreThreads()

Start all core threads. Calls prestartCoreThread() in a loop until it returns false.

Returns:

the number of core threads created

getGrowthResistance

public float getGrowthResistance()

Get the thread pool growth resistance. This is the average fraction of submitted tasks that will be enqueued (instead of causing a new thread to start) when there are no idle threads and the pool size is equal to or greater than the core size (but still less than the maximum size). A value of 0.0 indicates that tasks should not be enqueued until the pool is completely full; a value of 1.0 indicates that tasks should always be enqueued until the queue is completely full.

Returns:

the configured growth resistance factor

See Also:

Builder.getGrowthResistance()

setGrowthResistance

public void setGrowthResistance(float growthResistance)

Set the growth resistance factor.

Parameters:

growthResistance - the thread pool growth resistance (must be in the range 0.0f ≤ n ≤ 1.0f)

See Also:

Builder.setGrowthResistance()

getCorePoolSize

public int getCorePoolSize()

Get the core pool size. This is the size below which new threads will always be created if no idle threads are available. If the pool size reaches the core size but has not yet reached the maximum size, a resistance factor will be applied to each task submission which determines whether the task should be queued or a new thread started.

Returns:

the core pool size

See Also:

Builder.getCorePoolSize()

setCorePoolSize

public void setCorePoolSize(int corePoolSize)

Set the core pool size. If the configured maximum pool size is less than the configured core size, the core size will be reduced to match the maximum size when the thread pool is constructed.

Parameters:

corePoolSize - the core pool size (must be greater than or equal to 0, and less than 2^20)

See Also:

Builder.setCorePoolSize()

getMaximumPoolSize

public int getMaximumPoolSize()

Get the maximum pool size. This is the absolute upper limit to the size of the thread pool.

Returns:

the maximum pool size

See Also:

Builder.getMaximumPoolSize()

setMaximumPoolSize

public void setMaximumPoolSize(int maxPoolSize)

Set the maximum pool size. If the configured maximum pool size is less than the configured core size, the core size will be reduced to match the maximum size when the thread pool is constructed.

Parameters:

maxPoolSize - the maximum pool size (must be greater than or equal to 0, and less than 2^20)

See Also:

Builder.setMaximumPoolSize()

allowsCoreThreadTimeOut

public boolean allowsCoreThreadTimeOut()

Determine whether core threads are allowed to time out. A "core thread" is defined as any thread in the pool when the pool size is below the pool's core pool size.

Returns:

true if core threads are allowed to time out, false otherwise

See Also:

Builder.allowsCoreThreadTimeOut()

allowCoreThreadTimeOut

public void allowCoreThreadTimeOut(boolean value)

Establish whether core threads are allowed to time out. A "core thread" is defined as any thread in the pool when the pool size is below the pool's core pool size.

Parameters:

value - true if core threads are allowed to time out, false otherwise

See Also:

Builder.allowCoreThreadTimeOut()

getKeepAliveTime

public long getKeepAliveTime(TimeUnit keepAliveUnits)

Get the thread keep-alive time. This is the minimum length of time that idle threads should remain until they exit. Unless core threads are allowed to time out, threads will only exit if the current thread count exceeds the core limit.

Parameters:

keepAliveUnits - the unit in which the result should be expressed (must not be null)

Returns:

the amount of time (will be greater than zero)

See Also:

Builder.getKeepAliveTime()

setKeepAliveTime

public void setKeepAliveTime(long keepAliveTime,
                             TimeUnit keepAliveUnits)

Set the thread keep-alive time. This is the minimum length of time that idle threads should remain until they exit. Unless core threads are allowed to time out, threads will only exit if the current thread count exceeds the core limit.

Parameters:

keepAliveTime - the thread keep-alive time (must be > 0)

keepAliveUnits - the unit in which the value is expressed (must not be null)

See Also:

Builder.setKeepAliveTime()

getMaximumQueueSize

public int getMaximumQueueSize()

Get the maximum queue size. If the queue is full and a task cannot be immediately accepted, rejection will result.

Returns:

the maximum queue size

See Also:

Builder.getMaximumQueueSize()

setMaximumQueueSize

public void setMaximumQueueSize(int maxQueueSize)

Set the maximum queue size. If the new maximum queue size is smaller than the current queue size, there is no effect other than preventing tasks from being enqueued until the size decreases below the maximum again.

Parameters:

maxQueueSize - the maximum queue size (must be ≥ 0)

See Also:

Builder.setMaximumQueueSize()

getHandoffExecutor

public Executor getHandoffExecutor()

Get the executor to delegate to in the event of task rejection.

Returns:

the executor to delegate to in the event of task rejection (not null)

setHandoffExecutor

public void setHandoffExecutor(Executor handoffExecutor)

Set the executor to delegate to in the event of task rejection.

Parameters:

handoffExecutor - the executor to delegate to in the event of task rejection (must not be null)

getExceptionHandler

public Thread.UncaughtExceptionHandler getExceptionHandler()

Get the exception handler to use for uncaught exceptions.

Returns:

the exception handler to use for uncaught exceptions (not null)

setExceptionHandler

public void setExceptionHandler(Thread.UncaughtExceptionHandler exceptionHandler)

Set the exception handler to use for uncaught exceptions.

Parameters:

exceptionHandler - the exception handler to use for uncaught exceptions (must not be null)

setTerminationTask

public void setTerminationTask(Runnable terminationTask)

Set the termination task, overwriting any previous setting.

Parameters:

terminationTask - the termination task, or null to perform no termination task

getQueueSize

public int getQueueSize()

Get an estimate of the current queue size.

Returns:

an estimate of the current queue size

getLargestPoolSize

public int getLargestPoolSize()

Get an estimate of the peak number of threads that the pool has ever held.

Returns:

an estimate of the peak number of threads that the pool has ever held

getActiveCount

public int getActiveCount()

Get an estimate of the number of threads which are currently doing work on behalf of the thread pool.

Returns:

the active count estimate

getLargestQueueSize

public int getLargestQueueSize()

Get an estimate of the peak size of the queue.

Returns:

an estimate of the peak size of the queue

getSubmittedTaskCount

public long getSubmittedTaskCount()

Get an estimate of the total number of tasks ever submitted to this thread pool.

Returns:

an estimate of the total number of tasks ever submitted to this thread pool

getRejectedTaskCount

public long getRejectedTaskCount()

Get an estimate of the total number of tasks ever rejected by this thread pool for any reason.

Returns:

an estimate of the total number of tasks ever rejected by this thread pool

getCompletedTaskCount

public long getCompletedTaskCount()

Get an estimate of the number of tasks completed by this thread pool.

Returns:

an estimate of the number of tasks completed by this thread pool

getPoolSize

public int getPoolSize()

Get an estimate of the current number of active threads in the pool.

Returns:

an estimate of the current number of active threads in the pool