DebuggableThreadPoolExecutor (apache-cassandra API)
Date: 2018-02-12

org.apache.cassandra.concurrent

## Class DebuggableThreadPoolExecutor

- java.lang.Object
- - java.util.concurrent.AbstractExecutorService
  - - java.util.concurrent.ThreadPoolExecutor
    - - org.apache.cassandra.concurrent.DebuggableThreadPoolExecutor

- All Implemented Interfaces:
    java.util.concurrent.Executor, java.util.concurrent.ExecutorService, LocalAwareExecutorService
  Direct Known Subclasses:
    JMXEnabledThreadPoolExecutor

      public class DebuggableThreadPoolExecutor
      extends java.util.concurrent.ThreadPoolExecutor
      implements LocalAwareExecutorService

  This class encorporates some Executor best practices for Cassandra. Most of the executors in the system should use or extend this. There are two main improvements over a vanilla TPE: - If a task throws an exception, the default uncaught exception handler will be invoked; if there is no such handler, the exception will be logged. - MaximumPoolSize is not supported. Here is what that means (quoting TPE javadoc): If fewer than corePoolSize threads are running, the Executor always prefers adding a new thread rather than queuing. If corePoolSize or more threads are running, the Executor always prefers queuing a request rather than adding a new thread. If a request cannot be queued, a new thread is created unless this would exceed maximumPoolSize, in which case, the task will be rejected. We don't want this last stage of creating new threads if the queue is full; it makes it needlessly difficult to reason about the system's behavior. In other words, if DebuggableTPE has allocated our maximum number of (core) threads and the queue is full, we want the enqueuer to block. But to allow the number of threads to drop if a stage is less busy, core thread timeout is enabled.

- - ### Nested Class Summary

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

      `java.util.concurrent.ThreadPoolExecutor.AbortPolicy, java.util.concurrent.ThreadPoolExecutor.CallerRunsPolicy, java.util.concurrent.ThreadPoolExecutor.DiscardOldestPolicy, java.util.concurrent.ThreadPoolExecutor.DiscardPolicy`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.util.concurrent.RejectedExecutionHandler` | `blockingExecutionHandler`
    `protected static org.slf4j.Logger` | `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DebuggableThreadPoolExecutor(int corePoolSize, int maximumPoolSize, long keepAliveTime, java.util.concurrent.TimeUnit unit, java.util.concurrent.BlockingQueue<java.lang.Runnable> workQueue, java.util.concurrent.ThreadFactory threadFactory)`
    `DebuggableThreadPoolExecutor(int corePoolSize, long keepAliveTime, java.util.concurrent.TimeUnit unit, java.util.concurrent.BlockingQueue<java.lang.Runnable> queue, java.util.concurrent.ThreadFactory factory)`
    `DebuggableThreadPoolExecutor(java.lang.String threadPoolName, int priority)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `afterExecute(java.lang.Runnable r, java.lang.Throwable t)`
    `protected void` | `beforeExecute(java.lang.Thread t, java.lang.Runnable r)`
    `static DebuggableThreadPoolExecutor` | `createCachedThreadpoolWithMaxSize(java.lang.String threadPoolName)` Creates a thread pool that creates new threads as needed, but will reuse previously constructed threads when they are available.
    `static DebuggableThreadPoolExecutor` | `createWithFixedPoolSize(java.lang.String threadPoolName, int size)` Returns a ThreadPoolExecutor with a fixed number of threads.
    `static DebuggableThreadPoolExecutor` | `createWithMaximumPoolSize(java.lang.String threadPoolName, int size, int keepAliveTime, java.util.concurrent.TimeUnit unit)` Returns a ThreadPoolExecutor with a fixed maximum number of threads, but whose threads are terminated when idle for too long.
    `void` | `execute(java.lang.Runnable command)`
    `void` | `execute(java.lang.Runnable command, ExecutorLocals locals)`
    `static java.lang.Throwable` | `extractThrowable(java.lang.Runnable runnable)`
    `static void` | `handleOrLog(java.lang.Throwable t)` Send @param t to the default uncaught exception handler, or log it if none such is set up
    `static void` | `logExceptionsAfterExecute(java.lang.Runnable r, java.lang.Throwable t)` Send @param t and any exception wrapped by @param r to the default uncaught exception handler, or log them if none such is set up
    `void` | `maybeExecuteImmediately(java.lang.Runnable command)`
    `protected static void` | `maybeResetTraceSessionWrapper(java.lang.Runnable r)`
    `protected <T> java.util.concurrent.RunnableFuture<T>` | `newTaskFor(java.util.concurrent.Callable<T> callable)`
    `protected <T> java.util.concurrent.RunnableFuture<T>` | `newTaskFor(java.lang.Runnable runnable, T result)`
    `protected void` | `onFinalAccept(java.lang.Runnable task)`
    `protected void` | `onFinalRejection(java.lang.Runnable task)`
    `protected void` | `onInitialRejection(java.lang.Runnable task)`

    - ### Methods inherited from class java.util.concurrent.ThreadPoolExecutor

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

    - ### Methods inherited from class java.util.concurrent.AbstractExecutorService

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

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface java.util.concurrent.ExecutorService

      `awaitTermination, invokeAll, invokeAll, invokeAny, invokeAny, isShutdown, isTerminated, shutdown, shutdownNow, submit, submit, submit`

- - ### Field Detail

    - #### logger

          protected static final org.slf4j.Logger logger

    - #### blockingExecutionHandler

          public static final java.util.concurrent.RejectedExecutionHandler blockingExecutionHandler

  - ### Constructor Detail

    - #### DebuggableThreadPoolExecutor

          public DebuggableThreadPoolExecutor(java.lang.String threadPoolName,
                                              int priority)

    - #### DebuggableThreadPoolExecutor

          public DebuggableThreadPoolExecutor(int corePoolSize,
                                              long keepAliveTime,
                                              java.util.concurrent.TimeUnit unit,
                                              java.util.concurrent.BlockingQueue<java.lang.Runnable> queue,
                                              java.util.concurrent.ThreadFactory factory)

    - #### DebuggableThreadPoolExecutor

          public DebuggableThreadPoolExecutor(int corePoolSize,
                                              int maximumPoolSize,
                                              long keepAliveTime,
                                              java.util.concurrent.TimeUnit unit,
                                              java.util.concurrent.BlockingQueue<java.lang.Runnable> workQueue,
                                              java.util.concurrent.ThreadFactory threadFactory)

  - ### Method Detail

    - #### createCachedThreadpoolWithMaxSize

          public static DebuggableThreadPoolExecutor createCachedThreadpoolWithMaxSize(java.lang.String threadPoolName)

      Creates a thread pool that creates new threads as needed, but will reuse previously constructed threads when they are available.
      Parameters:
        `threadPoolName` - the name of the threads created by this executor
      Returns:
        The new DebuggableThreadPoolExecutor

    - #### createWithFixedPoolSize

          public static DebuggableThreadPoolExecutor createWithFixedPoolSize(java.lang.String threadPoolName,
                                                                             int size)

      Returns a ThreadPoolExecutor with a fixed number of threads. When all threads are actively executing tasks, new tasks are queued. If (most) threads are expected to be idle most of the time, prefer createWithMaxSize() instead.
      Parameters:
        `threadPoolName` - the name of the threads created by this executor
        `size` - the fixed number of threads for this executor
      Returns:
        the new DebuggableThreadPoolExecutor

    - #### createWithMaximumPoolSize

          public static DebuggableThreadPoolExecutor createWithMaximumPoolSize(java.lang.String threadPoolName,
                                                                               int size,
                                                                               int keepAliveTime,
                                                                               java.util.concurrent.TimeUnit unit)

      Returns a ThreadPoolExecutor with a fixed maximum number of threads, but whose threads are terminated when idle for too long. When all threads are actively executing tasks, new tasks are queued.
      Parameters:
        `threadPoolName` - the name of the threads created by this executor
        `size` - the maximum number of threads for this executor
        `keepAliveTime` - the time an idle thread is kept alive before being terminated
        `unit` - tht time unit for `keepAliveTime`
      Returns:
        the new DebuggableThreadPoolExecutor

    - #### onInitialRejection

          protected void onInitialRejection(java.lang.Runnable task)

    - #### onFinalAccept

          protected void onFinalAccept(java.lang.Runnable task)

    - #### onFinalRejection

          protected void onFinalRejection(java.lang.Runnable task)

    - #### execute

          public void execute(java.lang.Runnable command,
                              ExecutorLocals locals)

      Specified by:
        `execute` in interface `LocalAwareExecutorService`

    - #### maybeExecuteImmediately

          public void maybeExecuteImmediately(java.lang.Runnable command)

      Specified by:
        `maybeExecuteImmediately` in interface `LocalAwareExecutorService`

    - #### execute

          public void execute(java.lang.Runnable command)

      Specified by:
        `execute` in interface `java.util.concurrent.Executor`
      Overrides:
        `execute` in class `java.util.concurrent.ThreadPoolExecutor`

    - #### newTaskFor

          protected <T> java.util.concurrent.RunnableFuture<T> newTaskFor(java.lang.Runnable runnable,
                                                                          T result)

      Overrides:
        `newTaskFor` in class `java.util.concurrent.AbstractExecutorService`

    - #### newTaskFor

          protected <T> java.util.concurrent.RunnableFuture<T> newTaskFor(java.util.concurrent.Callable<T> callable)

      Overrides:
        `newTaskFor` in class `java.util.concurrent.AbstractExecutorService`

    - #### afterExecute

          protected void afterExecute(java.lang.Runnable r,
                                      java.lang.Throwable t)

      Overrides:
        `afterExecute` in class `java.util.concurrent.ThreadPoolExecutor`

    - #### maybeResetTraceSessionWrapper

          protected static void maybeResetTraceSessionWrapper(java.lang.Runnable r)

    - #### beforeExecute

          protected void beforeExecute(java.lang.Thread t,
                                       java.lang.Runnable r)

      Overrides:
        `beforeExecute` in class `java.util.concurrent.ThreadPoolExecutor`

    - #### logExceptionsAfterExecute

          public static void logExceptionsAfterExecute(java.lang.Runnable r,
                                                       java.lang.Throwable t)

      Send @param t and any exception wrapped by @param r to the default uncaught exception handler, or log them if none such is set up

    - #### handleOrLog

          public static void handleOrLog(java.lang.Throwable t)

      Send @param t to the default uncaught exception handler, or log it if none such is set up

    - #### extractThrowable

          public static java.lang.Throwable extractThrowable(java.lang.Runnable runnable)

      Returns:
        any exception wrapped by @param runnable, i.e., if it is a FutureTask

Copyright © 2018 The Apache Software Foundation