Package org.jboss.threads

Class EnhancedQueueExecutor

java.lang.Object
java.util.concurrent.AbstractExecutorService
org.jboss.threads.EnhancedQueueExecutor
All Implemented Interfaces:
Executor, ExecutorService, ScheduledExecutorService, ManageableThreadPoolExecutorService
public final class EnhancedQueueExecutor extends AbstractExecutorService implements ManageableThreadPoolExecutorService, ScheduledExecutorService
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.

Additionally, this thread pool implementation supports scheduling of tasks. The scheduled tasks will execute on the main pool.

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

  • Field Details

    • 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 Details

    • 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

    • schedule

      public ScheduledFuture<?> schedule(Runnable command, long delay, TimeUnit unit)
      Specified by:
      schedule in interface ScheduledExecutorService

    • schedule

      public <V> ScheduledFuture<V> schedule(Callable<V> callable, long delay, TimeUnit unit)
      Specified by:
      schedule in interface ScheduledExecutorService

    • scheduleAtFixedRate

      public ScheduledFuture<?> scheduleAtFixedRate(Runnable command, long initialDelay, long period, TimeUnit unit)
      Specified by:
      scheduleAtFixedRate in interface ScheduledExecutorService

    • scheduleWithFixedDelay

      public ScheduledFuture<?> scheduleWithFixedDelay(Runnable command, long initialDelay, long delay, TimeUnit unit)
      Specified by:
      scheduleWithFixedDelay in interface ScheduledExecutorService

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • getKeepAliveTime

      @Deprecated public long getKeepAliveTime(TimeUnit keepAliveUnits)
      Deprecated.
      Use getKeepAliveTime() instead.
      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:

    • getKeepAliveTime

      public Duration getKeepAliveTime()
      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.
      Returns:
      the amount of time (will be greater than zero)
      See Also:

    • setKeepAliveTime

      @Deprecated public void setKeepAliveTime(long keepAliveTime, TimeUnit keepAliveUnits)
      Deprecated.
      Use setKeepAliveTime(Duration) instead.
      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:

    • setKeepAliveTime

      public void setKeepAliveTime(Duration keepAliveTime)
      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 not be null)
      See Also:

    • 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:

    • 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:

    • 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 or -1 when jboss.threads.eqe.unlimited-queue is enabled

    • 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 or -1 when jboss.threads.eqe.statistics.active-count is disabled

    • getLargestQueueSize

      public int getLargestQueueSize()
      Get an estimate of the peak size of the queue. return an estimate of the peak size of the queue or -1 when jboss.threads.eqe.statistics is disabled or jboss.threads.eqe.unlimited-queue is enabled

    • 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 or -1 when jboss.threads.eqe.statistics is disabled

    • 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 or -1 when jboss.threads.eqe.statistics is disabled

    • 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 or -1 when jboss.threads.eqe.statistics is disabled

    • 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

    • getRunningThreads

      public Thread[] getRunningThreads()
      Get an array containing an approximate snapshot of the currently running threads in this executor.
      Returns:
      an array of running (unterminated) threads (not null)