ThreadPoolExecutor | Java In A Nutshell, 5th Edition

ThreadPoolExecutor

java.util.concurrent

Java 5.0

This class implements the ExecutorService interface to execute tasks using a highly configurable thread pool. The easiest way to instantiate this class is through the static factory methods of the Executors class. If you want a more highly configured thread pool, you can instantiate it directly.

Four configuration parameters must be passed to every THReadPoolExecutor( ) constructor; two others are optional. Many of these parameters may also be queried and adjusted after the executor has been created through various ThreadPoolExecutor accessor methods. The most important configuration parameters specify the size of the thread pool, and the queue that the executor uses to hold tasks that it cannot currently run. corePoolSize is the number of threads that the pool should hold under normal usage. As tasks are submitted to the ThreadPoolExecutor , a new thread is created for each task until the total number of threads reaches this size.

If corePoolSize tHReads have already been created, newly submitted tasks are placed on the work queue. As these core threads finish the tasks they are executing, they take( ) a new task from the work queue. You must specify the workQueue when you call the ThreadPoolExecutor( ) constructor. It may be any BlockingQueue object and the behavior of the thread pool depends strongly on the behavior of the queue you specify. Options include an unbounded LinkedBlockingQueue , a bounded ArrayBlockingQueue with a capacity of your choosing, or even a SynchronousQueue which has a capacity of zero and cannot actually accept a task unless a thread is already waiting to execute it.

If the work queue becomes empty, it is inefficient to leave all the core threads sitting idly waiting for work. Threads are terminated if they are idle for more than the "keep alive " time. You specify this time with the keepAliveTime parameter and a TimeUnit constant.

If the work queue fills up, the maximumPoolSize parameter comes into play. ThreadPoolExecutor prefers to maintain corePoolSize threads but allows this number to grow up to maximumPoolSize . A new thread is created only when the workQueue is full. If you specify an unbounded work queue, maximumPoolSize is irrelevant because the queue never fills up. If on the other hand you specify a SynchronousQueue (which is always full), if none of the existing threads are waiting for a new task, a new thread is always created (up to the maximumPoolSize limit).

If a THReadPoolExecutor has already created the maximum number of threads and its work queue is full, it must reject any newly submitted tasks. The default behavior is to throw a RejectedExecutionException . You can alter this behavior by specifying a RejectedExecutionHandler object to the ThreadPoolExecutor( ) constructor or with the setRejectedExecutionHandler( ) method. The four inner classes of this class are implementations of four handlers that address this case. See their individual entries for details.

The final way that you can customize a ThreadPoolExecutor is to pass THReadFactory to the constructor or to the setThreadFactory( ) method. If you do not specify a factory, the THReadPoolExecutor obtains one with Executors.defaultThreadFactory( ) .

Figure 16-94. java.util.concurrent.ThreadPoolExecutor

 public class  ThreadPoolExecutor  extends AbstractExecutorService {  // Public Constructors  public  ThreadPoolExecutor  (int  corePoolSize  , int  maximumPoolSize  ,          long  keepAliveTime  , TimeUnit  unit  , BlockingQueue<Runnable>  workQueue  );        public  ThreadPoolExecutor  (int  corePoolSize  , int  maximumPoolSize  ,          long  keepAliveTime  , TimeUnit  unit  , BlockingQueue<Runnable>  workQueue  ,          ThreadFactory  threadFactory  );        public  ThreadPoolExecutor  (int  corePoolSize  , int  maximumPoolSize  ,          long  keepAliveTime  , TimeUnit  unit  , BlockingQueue<Runnable>  workQueue  ,          RejectedExecutionHandler  handler  );        public  ThreadPoolExecutor  (int  corePoolSize  , int  maximumPoolSize  ,          long  keepAliveTime  , TimeUnit  unit  , BlockingQueue<Runnable>  workQueue  ,          ThreadFactory  threadFactory  ,  RejectedExecutionHandler  handler  );  // Nested Types  public static class  AbortPolicy  implements RejectedExecutionHandler;       public static class  CallerRunsPolicy  implements RejectedExecutionHandler;       public static class  DiscardOldestPolicy  implements RejectedExecutionHandler;       public static class  DiscardPolicy  implements RejectedExecutionHandler;  // Public Instance Methods  public int  getActiveCount  ( );        public long  getCompletedTaskCount  ( );        public int  getCorePoolSize  ( );        public long  getKeepAliveTime  (TimeUnit  unit  );        public int  getLargestPoolSize  ( );        public int  getMaximumPoolSize  ( );        public int  getPoolSize  ( );        public BlockingQueue<Runnable>  getQueue  ( );        public RejectedExecutionHandler  getRejectedExecutionHandler  ( );        public long  getTaskCount  ( );        public ThreadFactory  getThreadFactory  ( );        public boolean  isTerminating  ( );        public int  prestartAllCoreThreads  ( );        public boolean  prestartCoreThread  ( );        public void  purge  ( );        public boolean  remove  (Runnable  task  );        public void  setCorePoolSize  (int  corePoolSize  );        public void  setKeepAliveTime  (long  time  , TimeUnit  unit  );        public void  setMaximumPoolSize  (int  maximumPoolSize  );        public void  setRejectedExecutionHandler  (RejectedExecutionHandler  handler  );        public void  setThreadFactory  (ThreadFactory  threadFactory  );  // Methods Implementing Executor  public void  execute  (Runnable  command  );  // Methods Implementing ExecutorService  public boolean  awaitTermination  (long  timeout  , TimeUnit  unit  )          throws InterruptedException;        public boolean  isShutdown  ( );        public boolean  isTerminated  ( );        public void  shutdown  ( );        public java.util.List<Runnable>  shutdownNow  ( );  // Protected Methods Overriding Object  protected void  finalize  ( );  // Protected Instance Methods  protected void  afterExecute  (Runnable  r  , Throwable  t  );  empty  protected void  beforeExecute  (Thread  t  , Runnable  r  );  empty  protected void  terminated  ( );  empty  }

Subclasses

ScheduledThreadPoolExecutor

Passed To

RejectedExecutionHandler.rejectedExecution( ) , ThreadPoolExecutor.AbortPolicy.rejectedExecution( ) , ThreadPoolExecutor.CallerRunsPolicy.rejectedExecution( ) , ThreadPoolExecutor.DiscardOldestPolicy.rejectedExecution( ) , THReadPoolExecutor.DiscardPolicy.rejectedExecution( )