Интерфейс ExecutorService

Все суперинтерфейсы:: AutoCloseable, Executor

Все известные подинтерфейсы:: ScheduledExecutorService

Все известные реализующие классы:: AbstractExecutorService, ForkJoinPool, ScheduledThreadPoolExecutor, ThreadPoolExecutor

public interface ExecutorService extends Executor, AutoCloseable

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

Объект ExecutorService может быть остановлен, что приведет к отклонению новых задач. Для остановки объекта ExecutorService предоставляются два разных метода. Метод shutdown() позволит ранее отправленным задачам завершиться, прежде чем произойдёт завершение, а метод shutdownNow() предотвратит запуск ожидающих задач и попытается остановить выполняющиеся в данный момент. После завершения работы исполнителя нет активных задач, нет ожидающих задач и новые задачи не могут быть отправлены. Неиспользуемый ExecutorService должен быть остановлен для освобождения ресурсов.

Метод submit расширяет базовый метод Executor.execute(Runnable), создавая и возвращая Future, который может быть использован для отмены выполнения и/или ожидания завершения. Методы invokeAny и invokeAll выполняют наиболее полезные формы массового выполнения, выполняя коллекцию задач и ожидая завершения по крайней мере одной или всех задач. (Класс ExecutorCompletionService может быть использован для написания настраиваемых вариантов этих методов.)

Класс Executors предоставляет фабричные методы для служб исполнителей, предоставляемых в этом пакете.

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

Вот набросок сетевой службы, в которой потоки в пуле потоков обслуживают входящие запросы. Используется предварительно настроенный метод фабрики 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, проиллюстрировав это другим методом фабрики Executors:

 
 try (ExecutorService e =  Executors.newWorkStealingPool()) {
   // submit or execute many tasks with e ...
 }

Также возможна дальнейшая настройка. Например, следующий метод останавливает объект 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 ex) {
     // (Re-)Cancel if current thread also interrupted
     pool.shutdownNow();
     // Preserve interrupt status
     Thread.currentThread().interrupt();
   }
 }

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

С момента:: 1.5

Краткое описание методов

Модификатор и тип	Метод	Описание
`boolean`	`awaitTermination(long timeout, TimeUnit unit)`	Блокирует до завершения всех задач после запроса на остановку, или истечения таймаута, или прерывания текущего потока, что произойдет первым.
`default void`	`close()`	Инициирует упорядоченную остановку, в которой ранее отправленные задачи выполняются, но новые задачи не принимаются.
`<T> List<Future<T>>`	`invokeAll(Collection<? extends Callable<T>> tasks)`	Выполняет заданные задачи, возвращая список Future, содержащий их статус и результаты, когда все завершены.
`<T> List<Future<T>>`	`invokeAll(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)`	Выполняет заданные задачи, возвращая список Future, содержащий их статус и результаты, когда все завершены или истекает таймаут, что произойдет первым.
`<T> T`	`invokeAny(Collection<? extends Callable<T>> tasks)`	Выполняет заданные задачи, возвращая результат одной, которая завершилась успешно (т. е. без исключений), если таковые имеются.
`<T> T`	`invokeAny(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)`	Выполняет заданные задачи, возвращая результат одной, которая завершилась успешно (т. е. без исключений), если таковые имеются, прежде чем истечет заданный таймаут.
`boolean`	`isShutdown()`	Возвращает `true`, если этот исполнитель был остановлен.
`boolean`	`isTerminated()`	Возвращает `true`, если все задачи завершились после остановки.
`void`	`shutdown()`	Инициирует упорядоченную остановку, в которой ранее отправленные задачи выполняются, но новые задачи не принимаются.
`List<Runnable>`	`shutdownNow()`	Пытается остановить все активно выполняющиеся задачи, приостанавливает обработку ожидающих задач и возвращает список задач, которые ожидали выполнения.
`Future<?>`	`submit(Runnable task)`	Отправляет задачу Runnable для выполнения и возвращает Future, представляющую эту задачу.
`<T> Future<T>`	`submit(Runnable task, T result)`	Отправляет задачу Runnable для выполнения и возвращает Future, представляющую эту задачу.
`<T> Future<T>`	`submit(Callable<T> task)`	Отправляет задачу, возвращающую значение, для выполнения и возвращает Future, представляющую ожидаемые результаты задачи.

Методы, объявленные в интерфейсе java.util.concurrent.Executor

execute

Подробное описание методов

shutdown

void shutdown()

Инициализирует упорядоченное завершение, в котором ранее отправленные задачи выполняются, но новые задачи не принимаются. Вызов не имеет дополнительного эффекта, если завершение уже выполнено.

Этот метод не ждет завершения выполнения ранее отправленных задач. Используйте awaitTermination для этого.

shutdownNow

List<Runnable> shutdownNow()

Попытка остановить все активно выполняющиеся задачи, приостановить обработку ожидающих задач и вернуть список задач, которые ожидали выполнения.

Этот метод не ждет завершения активно выполняющихся задач. Используйте awaitTermination для этого.

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

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

isShutdown

boolean isShutdown()

Возвращает true, если данный исполняющий поток был остановлен.

Возвращает:: true, если данный исполняющий поток был остановлен

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)

Отправляет возвращающую значение задачу для выполнения и возвращает Future, представляющую ожидаемые результаты задачи. Метод Future's get вернёт результат задачи при успешном завершении.

Если вы хотите немедленно заблокировать ожидание задачи, вы можете использовать конструкции вида result = exec.submit(aCallable).get();

Примечание: класс Executors содержит набор методов, которые могут преобразовать некоторые другие общие объекты типа closure, например, PrivilegedAction в форму Callable, чтобы их можно было отправить.

Типы параметров:: T - тип результата задачи
Параметры:: task - отправляемая задача
Возвращает:: Future, представляющее ожидаемое завершение задачи
Исключения:: RejectedExecutionException - если задача не может быть запланирована для выполнения; NullPointerException - если задача равна null

submit

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

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

Типы параметров:: T - тип результата
Параметры:: task - отправляемая задача; result - возвращаемый результат
Возвращает:: Future, представляющее ожидаемое завершение задачи
Исключения:: RejectedExecutionException - если задача не может быть запланирована для выполнения; NullPointerException - если задача равна null

submit

Future<?> submit(Runnable task)

Отправляет задачу Runnable для выполнения и возвращает Future, представляющую эту задачу. Метод Future's get вернёт 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 - если задачи, любой из её элементов или единица измерения времени равны null; RejectedExecutionException - если любая задача не может быть запланирована для выполнения

invokeAny

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

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

Типы параметров:: T - тип значений, возвращаемых задачами
Параметры:: tasks - коллекция задач
Возвращает:: результат, возвращённый одной из задач
Исключения:: InterruptedException - если поток прерван во время ожидания; NullPointerException - если задачи или любая из задач, подлежащих выполнению, равны null; IllegalArgumentException - если задачи пуста; ExecutionException - если ни одна задача не завершилась успешно; RejectedExecutionException - если задачи не могут быть запланированы для выполнения

invokeAny

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

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

Type Parameters:: T - тип значений, возвращаемых задачами
Parameters:: tasks - коллекция задач; timeout - максимальное время ожидания; unit - единица измерения времени таймаута
Returns:: результат, возвращённый одной из задач
Throws:: InterruptedException - если произошёл сбой во время ожидания; NullPointerException - если задачи, или единица, или любая задача, подлежащая выполнению, null; TimeoutException - если заданный таймаут истекает, прежде чем какая-либо задача успешно завершится; ExecutionException - если ни одна задача не завершилась успешно; RejectedExecutionException - если задачи не могут быть запланированы для выполнения

close

default void close()

Инициализирует упорядоченное завершение, в котором ранее отправленные задачи выполняются, но новые задачи не принимаются. Этот метод ждёт, пока все задачи завершат выполнение, и исполняемый блок завершится.

Если во время ожидания произошёл сбой, этот метод останавливает все выполняющиеся задачи так, как если бы был вызван shutdownNow(). Затем он продолжает ожидать, пока все активно выполняющиеся задачи не завершатся. Задачи, которые ожидали выполнения, не выполняются. Статус прерывания будет повторно установлен перед возвратом из этого метода.

Если блок уже завершён, вызов этого метода не оказывает никакого эффекта.

Specified by:: close в интерфейсе AutoCloseable
Implementation Requirements:: Реализация по умолчанию вызывает shutdown() и ожидает завершения задач с помощью awaitTermination.
Since:: 19

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://download.java.net/java/early_access/jdk24/docs/api/java.base/java/util/concurrent/ExecutorService.html