Интерфейс ExecutorService

public interface ExecutorService
extends Executor

An Executor that provides methods to manage termination and methods that can produce a Future for tracking progress of one or more asynchronous tasks.

An ExecutorService can be shut down, which will cause it to reject new tasks. Two different methods are provided for shutting down an ExecutorService. The shutdown() method will allow previously submitted tasks to execute before terminating, while the shutdownNow() method prevents waiting tasks from starting and attempts to stop currently executing tasks. Upon termination, an executor has no tasks actively executing, no tasks awaiting execution, and no new tasks can be submitted. An unused ExecutorService should be shut down to allow reclamation of its resources.

Method submit extends base method Executor.execute(Runnable) by creating and returning a Future that can be used to cancel execution and/or wait for completion. Methods invokeAny and invokeAll perform the most commonly useful forms of bulk execution, executing a collection of tasks and then waiting for at least one, or all, to complete. (Class ExecutorCompletionService can be used to write customized variants of these methods.)

The Executors class provides factory methods for the executor services provided in this package.

Примеры использования

Здесь приведён пример сетевого сервиса, в котором потоки в пуле потоков обрабатывают входящие запросы. Он использует предопределённый фабричный метод Executors.newFixedThreadPool(int):

class NetworkService implements Runnable {
   private final ServerSocket serverSocket;
   private final ExecutorService pool;

   public NetworkService(int port, int poolSize)
       throws IOException {
     serverSocket = new ServerSocket(port);
     pool = Executors.newFixedThreadPool(poolSize);
   }

   public void run() { // run the service
     try {
       for (;;) {
         pool.execute(new Handler(serverSocket.accept()));
       }
     } catch (IOException ex) {
       pool.shutdown();
     }
   }
 }

 class Handler implements Runnable {
   private final Socket socket;
   Handler(Socket socket) { this.socket = socket; }
   public void run() {
     // read and service request on socket
   }
 }

Следующий метод закрывает ExecutorService в двух фазах: сначала вызывая shutdown для отклонения новых задач, а затем вызывая shutdownNow, если необходимо, для отмены ожидающих задач:

void shutdownAndAwaitTermination(ExecutorService pool) {
   pool.shutdown(); // Disable new tasks from being submitted
   try {
     // Wait a while for existing tasks to terminate
     if (!pool.awaitTermination(60, TimeUnit.SECONDS)) {
       pool.shutdownNow(); // Cancel currently executing tasks
       // Wait a while for tasks to respond to being cancelled
       if (!pool.awaitTermination(60, TimeUnit.SECONDS))
           System.err.println("Pool did not terminate");
     }
   } catch (InterruptedException ie) {
     // (Re-)Cancel if current thread also interrupted
     pool.shutdownNow();
     // Preserve interrupt status
     Thread.currentThread().interrupt();
   }
 }

Эффекты согласованности памяти: Действия в потоке до отправки задачи Runnable или Callable в ExecutorService предшествуют любым действиям, выполняемым этой задачей, которые в свою очередь предшествуют получению результата через Future.get().

Методы

shutdown

void shutdown()

Исключения:

SecurityException - если существует менеджер безопасности и завершение работы этого ExecutorService может изменять потоки, которые вызывающий объект не имеет права изменять, поскольку он не обладает RuntimePermission("modifyThread"), или метод checkAccess менеджера безопасности запрещает доступ.

shutdownNow

List<Runnable> shutdownNow()

Возвращает:

список задач, которые никогда не начинали выполнение

Исключения:

SecurityException - если существует менеджер безопасности и завершение работы этого ExecutorService может изменять потоки, которые вызывающий объект не имеет права изменять, поскольку он не обладает RuntimePermission("modifyThread"), или метод checkAccess менеджера безопасности запрещает доступ.

isShutdown

boolean isShutdown()

Возвращает true, если этот executor был завершен.

Возвращает:

true если этот executor был завершен

isTerminated

boolean isTerminated()

Возвращает true, если все задачи завершены после завершения работы. Обратите внимание, что isTerminated никогда не true, если не был вызван сначала shutdown или shutdownNow.

Возвращает:

true если все задачи завершены после завершения работы

awaitTermination

boolean awaitTermination(long timeout,
                         TimeUnit unit)
                  throws InterruptedException

Блокирует, пока все задачи не завершат выполнение после запроса на завершение работы, или пока не истечет время ожидания, или пока не будет прерван текущий поток, в зависимости от того, что произойдет раньше.

Параметры:

timeout - максимальное время ожидания

unit - единица времени аргумента времени ожидания

Возвращает:

true если этот executor завершен и false если время ожидания истекло до завершения

Исключения:

InterruptedException - если прервано во время ожидания

submit

<T> Future<T> submit(Callable<T> task)

Параметры типа:

T - тип результата задачи

Параметры:

task - задача для отправки

Возвращает:

Future, представляющий ожидающее завершение задачи

Исключения:

RejectedExecutionException - если задачу невозможно запланировать на выполнение

NullPointerException - если задача равна null

submit

<T> Future<T> submit(Runnable task,
                     T result)

Отправляет задачу Runnable для выполнения и возвращает Future, представляющий эту задачу. Метод get Future вернет данный результат после успешного завершения.

Параметры типа:

T - тип результата

Параметры:

task - задача для отправки

result - результат для возврата

Возвращает:

Future, представляющий ожидающее завершение задачи

Исключения:

RejectedExecutionException - если задачу невозможно запланировать на выполнение

NullPointerException - если задача равна null

submit

Future<?> submit(Runnable task)

Отправляет задачу Runnable для выполнения и возвращает Future, представляющий эту задачу. Метод get Future вернет null при успешном завершении.

Параметры:

task - задача для отправки

Возвращает:

Future, представляющий ожидающее завершение задачи

Исключения:

RejectedExecutionException - если задачу невозможно запланировать на выполнение

NullPointerException - если задача равна null

invokeAll

<T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks)
                       throws InterruptedException

Выполняет заданные задачи, возвращая список Futures, содержащих их статус и результаты, когда все завершены. Future.isDone() является true для каждого элемента возвращаемого списка. Обратите внимание, что завершённая задача может быть завершена либо нормально, либо путем выброса исключения. Результаты этого метода неопределены, если заданная коллекция изменяется во время выполнения этой операции.

Параметры типа:

T - тип значений, возвращаемых из задач

Параметры:

tasks - коллекция задач

Возвращает:

список Futures, представляющих задачи, в том же последовательном порядке, что и итератор для заданного списка задач, каждый из которых завершен

Исключения:

InterruptedException - если прервано во время ожидания, в этом случае незавершенные задачи отменяются

NullPointerException - если задачи или любой из его элементов являются null

RejectedExecutionException - если любую задачу нельзя запланировать на выполнение

invokeAll

<T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks,
                              long timeout,
                              TimeUnit unit)
                       throws InterruptedException

Выполняет заданные задачи, возвращая список Futures, содержащих их статус и результаты, когда все завершены или истекает время ожидания, в зависимости от того, что произойдет раньше. Future.isDone() является true для каждого элемента возвращаемого списка. После возврата задачи, которые не завершены, отменяются. Обратите внимание, что завершённая задача может быть завершена либо нормально, либо путем выброса исключения. Результаты этого метода неопределены, если заданная коллекция изменяется во время выполнения этой операции.

Параметры типа:

T - тип значений, возвращаемых из задач

Параметры:

tasks - коллекция задач

timeout - максимальное время ожидания

unit - единица времени аргумента времени ожидания

Возвращает:

список Futures, представляющих задачи, в том же последовательном порядке, что и итератор для заданного списка задач. Если операция не завершилась по времени, каждая задача будет завершена. Если время ожидания истекло, некоторые из этих задач не будут завершены.

Исключения:

InterruptedException - если прервано во время ожидания, в этом случае незавершенные задачи отменяются

NullPointerException - если задачи, любой из его элементов или unit являются null

RejectedExecutionException - если любую задачу нельзя запланировать на выполнение

invokeAny

<T> T invokeAny(Collection<? extends Callable<T>> tasks)
         throws InterruptedException,
                ExecutionException

Выполняет заданные задачи, возвращая результат одной из успешно завершенных (т. е. без выброса исключения), если таковые имеются. После нормального или исключительного возврата задачи, которые не завершены, отменяются. Результаты этого метода неопределены, если заданная коллекция изменяется во время выполнения этой операции.

Параметры типа:

T - тип значений, возвращаемых из задач

Параметры:

tasks - коллекция задач

Возвращает:

результат, возвращенный одной из задач

Исключения:

InterruptedException - если прервано во время ожидания

NullPointerException - если задачи или любая задача элемента, подлежащая выполнению, является null

IllegalArgumentException - если tasks пуст

ExecutionException - если ни одна задача не завершается успешно

RejectedExecutionException - если задачи невозможно запланировать на выполнение

invokeAny

<T> T invokeAny(Collection<? extends Callable<T>> tasks,
                long timeout,
                TimeUnit unit)
         throws InterruptedException,
                ExecutionException,
                TimeoutException

Выполняет заданные задачи, возвращая результат одной из успешно завершенных (т. е. без выброса исключения), если таковые имеются до истечения заданного времени ожидания. После нормального или исключительного возврата задачи, которые не завершены, отменяются. Результаты этого метода неопределены, если заданная коллекция изменяется во время выполнения этой операции.

Параметры типа:

T - тип значений, возвращаемых из задач

Параметры:

tasks - коллекция задач

timeout - максимальное время ожидания

unit - единица времени аргумента времени ожидания

Возвращает:

результат, возвращенный одной из задач

Исключения:

InterruptedException - если прервано во время ожидания

NullPointerException - если задачи, или unit, или любая задача элемента, подлежащая выполнению, является null

TimeoutException - если заданное время ожидания истекает до успешного завершения любой задачи

ExecutionException - если ни одна задача не завершается успешно

RejectedExecutionException - если задачи невозможно запланировать на выполнение