ThreadPoolExecutor

public class ThreadPoolExecutor
extends AbstractExecutorService

Known Direct Subclasses ScheduledThreadPoolExecutor ScheduledThreadPoolExecutor 一个 ThreadPoolExecutor ，可以额外安排命令在给定的延迟后运行，或定期执行。

ExecutorService使用 Executors工厂方法使用可能的几个池线程中的一个来执行每个提交的任务。

线程池解决了两个不同的问题：由于减少了每个任务的调用开销，它们通常在执行大量异步任务时提供改进的性能，并且它们提供了一种限制和管理资源（包括线程）的方法，在执行任务。 每个ThreadPoolExecutor还保留一些基本的统计数据，例如完成的任务数量。

为了在广泛的上下文中有用，此类提供了许多可调参数和可扩展性钩子。 但是，我们建议程序员使用更方便的Executors工厂方法newCachedThreadPool() （无界线程池，自动线程回收）， newFixedThreadPool(int) （固定大小的线程池）和newSingleThreadExecutor() （单个后台线程），它们为最常见的使用场景预配置设置。 否则，请在手动配置和调整此类时使用以下指南：

Core and maximum pool sizes

A ThreadPoolExecutor will automatically adjust the pool size (see getPoolSize()) according to the bounds set by corePoolSize (see getCorePoolSize()) and maximumPoolSize (see getMaximumPoolSize()). When a new task is submitted in method execute(Runnable), and fewer than corePoolSize threads are running, a new thread is created to handle the request, even if other worker threads are idle. If there are more than corePoolSize but less than maximumPoolSize threads running, a new thread will be created only if the queue is full. By setting corePoolSize and maximumPoolSize the same, you create a fixed-size thread pool. By setting maximumPoolSize to an essentially unbounded value such as Integer.MAX_VALUE, you allow the pool to accommodate an arbitrary number of concurrent tasks. Most typically, core and maximum pool sizes are set only upon construction, but they may also be changed dynamically using setCorePoolSize(int) and setMaximumPoolSize(int).

On-demand construction

By default, even core threads are initially created and started only when new tasks arrive, but this can be overridden dynamically using method prestartCoreThread() or prestartAllCoreThreads(). You probably want to prestart threads if you construct the pool with a non-empty queue.

Creating new threads

New threads are created using a ThreadFactory. If not otherwise specified, a defaultThreadFactory() is used, that creates threads to all be in the same ThreadGroup and with the same NORM_PRIORITY priority and non-daemon status. By supplying a different ThreadFactory, you can alter the thread's name, thread group, priority, daemon status, etc. If a ThreadFactory fails to create a thread when asked by returning null from newThread, the executor will continue, but might not be able to execute any tasks. Threads should possess the "modifyThread" RuntimePermission. If worker threads or other threads using the pool do not possess this permission, service may be degraded: configuration changes may not take effect in a timely manner, and a shutdown pool may remain in a state in which termination is possible but not completed.

Keep-alive times

If the pool currently has more than corePoolSize threads, excess threads will be terminated if they have been idle for more than the keepAliveTime (see getKeepAliveTime(TimeUnit)). This provides a means of reducing resource consumption when the pool is not being actively used. If the pool becomes more active later, new threads will be constructed. This parameter can also be changed dynamically using method setKeepAliveTime(long, TimeUnit). Using a value of Long.MAX_VALUE NANOSECONDS effectively disables idle threads from ever terminating prior to shut down. By default, the keep-alive policy applies only when there are more than corePoolSize threads, but method allowCoreThreadTimeOut(boolean) can be used to apply this time-out policy to core threads as well, so long as the keepAliveTime value is non-zero.

Queuing

Any BlockingQueue may be used to transfer and hold submitted tasks. The use of this queue interacts with pool sizing:

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

There are three general strategies for queuing:

1. Direct handoffs. A good default choice for a work queue is a SynchronousQueue that hands off tasks to threads without otherwise holding them. Here, an attempt to queue a task will fail if no threads are immediately available to run it, so a new thread will be constructed. This policy avoids lockups when handling sets of requests that might have internal dependencies. Direct handoffs generally require unbounded maximumPoolSizes to avoid rejection of new submitted tasks. This in turn admits the possibility of unbounded thread growth when commands continue to arrive on average faster than they can be processed.
2. Unbounded queues. Using an unbounded queue (for example a LinkedBlockingQueue without a predefined capacity) will cause new tasks to wait in the queue when all corePoolSize threads are busy. Thus, no more than corePoolSize threads will ever be created. (And the value of the maximumPoolSize therefore doesn't have any effect.) This may be appropriate when each task is completely independent of others, so tasks cannot affect each others execution; for example, in a web page server. While this style of queuing can be useful in smoothing out transient bursts of requests, it admits the possibility of unbounded work queue growth when commands continue to arrive on average faster than they can be processed.
3. Bounded queues. A bounded queue (for example, an ArrayBlockingQueue) helps prevent resource exhaustion when used with finite maximumPoolSizes, but can be more difficult to tune and control. Queue sizes and maximum pool sizes may be traded off for each other: Using large queues and small pools minimizes CPU usage, OS resources, and context-switching overhead, but can lead to artificially low throughput. If tasks frequently block (for example if they are I/O bound), a system may be able to schedule time for more threads than you otherwise allow. Use of small queues generally requires larger pool sizes, which keeps CPUs busier but may encounter unacceptable scheduling overhead, which also decreases throughput.

Rejected tasks

New tasks submitted in method execute(Runnable) will be rejected when the Executor has been shut down, and also when the Executor uses finite bounds for both maximum threads and work queue capacity, and is saturated. In either case, the execute method invokes the rejectedExecution(Runnable, ThreadPoolExecutor) method of its RejectedExecutionHandler. Four predefined handler policies are provided:

1. In the default ThreadPoolExecutor.AbortPolicy, the handler throws a runtime RejectedExecutionException upon rejection.
2. In ThreadPoolExecutor.CallerRunsPolicy, the thread that invokes execute itself runs the task. This provides a simple feedback control mechanism that will slow down the rate that new tasks are submitted.
3. In ThreadPoolExecutor.DiscardPolicy, a task that cannot be executed is simply dropped.
4. In ThreadPoolExecutor.DiscardOldestPolicy, if the executor is not shut down, the task at the head of the work queue is dropped, and then execution is retried (which can fail again, causing this to be repeated.)

It is possible to define and use other kinds of RejectedExecutionHandler classes. Doing so requires some care especially when policies are designed to work only under particular capacity or queuing policies.

Hook methods

This class provides protected overridable beforeExecute(Thread, Runnable) and afterExecute(Runnable, Throwable) methods that are called before and after execution of each task. These can be used to manipulate the execution environment; for example, reinitializing ThreadLocals, gathering statistics, or adding log entries. Additionally, method terminated() can be overridden to perform any special processing that needs to be done once the Executor has fully terminated.

如果hook，callback或BlockingQueue方法抛出异常，则内部工作线程可能会失败，突然终止并可能被替换。

Queue maintenance

Method getQueue() allows access to the work queue for purposes of monitoring and debugging. Use of this method for any other purpose is strongly discouraged. Two supplied methods, remove(Runnable) and purge() are available to assist in storage reclamation when large numbers of queued tasks become cancelled.

Finalization

A pool that is no longer referenced in a program AND has no remaining threads will be shutdown automatically. If you would like to ensure that unreferenced pools are reclaimed even if users forget to call shutdown(), then you must arrange that unused threads eventually die, by setting appropriate keep-alive times, using a lower bound of zero core threads and/or setting allowCoreThreadTimeOut(boolean).

扩展示例 。 该类的大多数扩展都会覆盖一个或多个受保护的挂钩方法。 例如，以下是添加简单暂停/恢复功能的子类：

 class PausableThreadPoolExecutor extends ThreadPoolExecutor {
   private boolean isPaused;
   private ReentrantLock pauseLock = new ReentrantLock();
   private Condition unpaused = pauseLock.newCondition();

   public PausableThreadPoolExecutor(...) { super(...); }

   protected void beforeExecute(Thread t, Runnable r) {
     super.beforeExecute(t, r);
     pauseLock.lock();
     try {
       while (isPaused) unpaused.await();
     } catch (InterruptedException ie) {
       t.interrupt();
     } finally {
       pauseLock.unlock();
     }
   }

   public void pause() {
     pauseLock.lock();
     try {
       isPaused = true;
     } finally {
       pauseLock.unlock();
     }
   }

   public void resume() {
     pauseLock.lock();
     try {
       isPaused = false;
       unpaused.signalAll();
     } finally {
       pauseLock.unlock();
     }
   }
 }

Summary

Inherited methods
From class java.util.concurrent.AbstractExecutorService <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks) 执行给定的任务，返回一份持有其状态和结果的期货清单，当全部完成时。 <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit) 执行给定的任务，当所有完成或超时到期时返回一份持有其状态和结果的期货清单，以先发生者为准。 <T> T invokeAny(Collection<? extends Callable<T>> tasks) 执行给定的任务，返回已成功完成的任务（即，没有抛出异常）的结果，如果有的话。 <T> T invokeAny(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit) 执行给定的任务，返回已成功完成的任务（即，没有抛出异常）的结果，如果在给定超时过去之前执行了任务。 <T> RunnableFuture<T> newTaskFor(Runnable runnable, T value) 针对给定的可运行和默认值返回 RunnableFuture 。 <T> RunnableFuture<T> newTaskFor(Callable<T> callable) 为给定的可调用任务返回一个 RunnableFuture 。 <T> Future<T> submit(Callable<T> task) 提交执行的返回值任务，并返回表示未完成任务结果的Future。 <T> Future<T> submit(Runnable task, T result) 提交可执行的任务并返回表示该任务的Future。 Future<?> submit(Runnable task) 提交可执行的任务并返回表示该任务的Future。
From class java.lang.Object Object clone() 创建并返回此对象的副本。 boolean equals(Object obj) 指示其他某个对象是否“等于”这一个。 void finalize() 当垃圾收集确定没有更多对该对象的引用时，由对象上的垃圾回收器调用。 final Class<?> getClass() 返回此 Object的运行时类。 int hashCode() 返回对象的哈希码值。 final void notify() 唤醒正在等待该对象监视器的单个线程。 final void notifyAll() 唤醒在该对象监视器上等待的所有线程。 String toString() 返回对象的字符串表示形式。 final void wait(long millis, int nanos) 导致当前线程等待，直到另一个线程为此对象调用 notify()方法或 notifyAll()方法，或者某个其他线程中断当前线程，或经过一定的实时时间。 final void wait(long millis) 导致当前线程等待，直到另一个线程调用此对象的 notify()方法或 notifyAll()方法或经过指定的时间量。 final void wait() 使当前线程等待，直到另一个线程调用此对象的 notify()方法或 notifyAll()方法。
From interface java.util.concurrent.ExecutorService abstract boolean awaitTermination(long timeout, TimeUnit unit) 阻塞，直到所有任务在关闭请求之后所有任务都已完成执行，或发生超时，或当前线程中断，以先发生者为准。 abstract <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks) 执行给定的任务，返回一份持有其状态和结果的期货清单，当全部完成时。 abstract <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit) 执行给定的任务，当所有完成或超时到期时返回一份持有其状态和结果的期货清单，以先发生者为准。 abstract <T> T invokeAny(Collection<? extends Callable<T>> tasks) 执行给定的任务，返回已成功完成的任务（即，没有抛出异常）的结果，如果有的话。 abstract <T> T invokeAny(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit) 执行给定的任务，返回已成功完成的任务（即，没有抛出异常）的结果，如果在给定超时过去之前执行了任务。 abstract boolean isShutdown() 如果此执行者已被关闭，则返回 true 。 abstract boolean isTerminated() 如果所有任务都在关闭后完成，则返回 true 。 abstract void shutdown() 启动先前提交的任务执行的有序关闭，但不会接受新任务。 abstract List<Runnable> shutdownNow() 尝试停止所有正在执行的任务，暂停等待任务的处理，并返回正在等待执行的任务列表。 abstract <T> Future<T> submit(Callable<T> task) 提交执行的返回值任务，并返回表示未完成任务结果的Future。 abstract <T> Future<T> submit(Runnable task, T result) 提交可执行的任务并返回表示该任务的Future。 abstract Future<?> submit(Runnable task) 提交可执行的任务并返回表示该任务的Future。
From interface java.util.concurrent.Executor abstract void execute(Runnable command) 将来在某个时间执行给定的命令。

Public constructors

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

ThreadPoolExecutor (int corePoolSize, 
                int maximumPoolSize, 
                long keepAliveTime, 
                TimeUnit unit, 
                BlockingQueue<Runnable> workQueue, 
                ThreadFactory threadFactory)

ThreadPoolExecutor (int corePoolSize, 
                int maximumPoolSize, 
                long keepAliveTime, 
                TimeUnit unit, 
                BlockingQueue<Runnable> workQueue, 
                RejectedExecutionHandler handler)

ThreadPoolExecutor (int corePoolSize, 
                int maximumPoolSize, 
                long keepAliveTime, 
                TimeUnit unit, 
                BlockingQueue<Runnable> workQueue, 
                ThreadFactory threadFactory, 
                RejectedExecutionHandler handler)

Public methods

void allowCoreThreadTimeOut (boolean value)

boolean allowsCoreThreadTimeOut ()

boolean awaitTermination (long timeout, 
                TimeUnit unit)

void execute (Runnable command)

int getActiveCount ()

long getCompletedTaskCount ()

int getCorePoolSize ()

long getKeepAliveTime (TimeUnit unit)

int getLargestPoolSize ()

int getMaximumPoolSize ()

int getPoolSize ()

BlockingQueue<Runnable> getQueue ()

RejectedExecutionHandler getRejectedExecutionHandler ()

long getTaskCount ()

ThreadFactory getThreadFactory ()

boolean isShutdown ()

boolean isTerminated ()

boolean isTerminating ()

int prestartAllCoreThreads ()

boolean prestartCoreThread ()

void purge ()

boolean remove (Runnable task)

void setCorePoolSize (int corePoolSize)

void setKeepAliveTime (long time, 
                TimeUnit unit)

void setMaximumPoolSize (int maximumPoolSize)

void setRejectedExecutionHandler (RejectedExecutionHandler handler)

void setThreadFactory (ThreadFactory threadFactory)

void shutdown ()

List<Runnable> shutdownNow ()

String toString ()

Protected methods

void afterExecute (Runnable r, 
                Throwable t)

 class ExtendedExecutor extends ThreadPoolExecutor {
   // ...
   protected void afterExecute(Runnable r, Throwable t) {
     super.afterExecute(r, t);
     if (t == null
         && r instanceof Future<?>
         && ((Future<?>)r).isDone()) {
       try {
         Object result = ((Future<?>) r).get();
       } catch (CancellationException ce) {
         t = ce;
       } catch (ExecutionException ee) {
         t = ee.getCause();
       } catch (InterruptedException ie) {
         // ignore/reset
         Thread.currentThread().interrupt();
       }
     }
     if (t != null)
       System.out.println(t);
   }
 }

void beforeExecute (Thread t, 
                Runnable r)

void finalize ()

void terminated ()