Класс CyclicBarrier

java.lang.Object

java.util.concurrent.CyclicBarrier

public class CyclicBarrier extends Object

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

CyclicBarrier поддерживает необязательное Runnable действие, которое выполняется один раз на каждую точку барьера после того, как последний поток в группе достигнет её, но перед тем, как любые потоки будут освобождены. Это действие барьера полезно для обновления совместного состояния перед продолжением работы потоков.

Пример использования: Вот пример использования барьера в параллельном дизайне разбиения:

 
 class Solver {
   final int N;
   final float[][] data;
   final CyclicBarrier barrier;

   class Worker implements Runnable {
     int myRow;
     Worker(int row) { myRow = row; }
     public void run() {
       while (!done()) {
         processRow(myRow);

         try {
           barrier.await();
         } catch (InterruptedException ex) {
           return;
         } catch (BrokenBarrierException ex) {
           return;
         }
       }
     }
   }

   public Solver(float[][] matrix) {
     data = matrix;
     N = matrix.length;
     Runnable barrierAction = () -> mergeRows(...);
     barrier = new CyclicBarrier(N, barrierAction);

     List<Thread> threads = new ArrayList<>(N);
     for (int i = 0; i < N; i++) {
       Thread thread = new Thread(new Worker(i));
       threads.add(thread);
       thread.start();
     }

     // wait until done
     for (Thread thread : threads)
       try {
         thread.join();
       } catch (InterruptedException ex) { }
   }
 }

Здесь каждый рабочий поток обрабатывает строку матрицы, затем ожидает в барьере, пока все строки не будут обработаны. Когда все строки обработаны, предоставленное Runnable действие барьера выполняется и строки объединяются. Если объединение определяет, что решение найдено, то done() вернёт true, и каждый рабочий поток завершит свою работу.

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

 
 if (barrier.await() == 0) {
   // log the completion of this iteration
 }

CyclicBarrier использует модель "все или ничего" для неудачных попыток синхронизации: если поток оставляет точку барьера преждевременно из-за прерывания, ошибки или истечения времени ожидания, все другие потоки, ожидающие в этой точке барьера, также покинут её аномально через BrokenBarrierException (или InterruptedException, если они тоже были прерваны примерно в то же время).

Эффекты согласованности памяти: действия в потоке до вызова await() предшествуют действиям, которые являются частью действия барьера, которые, в свою очередь, предшествуют действиям, следуя успешному возврату из соответствующего await() в других потоках.

Since:

1.5

См. также:

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

Конструктор Описание

Конструктор	Описание
`CyclicBarrier(int parties)`	Создает новый `CyclicBarrier`, который срабатывает, когда заданное число участников (потоков) ожидают его, и не выполняет предопределенное действие, когда барьер срабатывает.
`CyclicBarrier(int parties, Runnable barrierAction)`	Создает новый `CyclicBarrier`, который срабатывает, когда заданное число участников (потоков) ожидают его, и который выполнит заданное действие барьера, когда барьер срабатывает, выполняясь последним вошедшим в барьер потоком.

CyclicBarrier(int parties)

Создает новый CyclicBarrier, который срабатывает, когда заданное число участников (потоков) ожидают его, и не выполняет предопределенное действие, когда барьер срабатывает.

CyclicBarrier(int parties,
 Runnable barrierAction)

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

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

Модификатор и тип	Метод	Описание
`int`	`await()`	Ожидает, пока все участники не вызовут `await` в этом барьере.
`int`	`await(long timeout, TimeUnit unit)`	Ожидает, пока все участники не вызовут `await` в этом барьере, или не истечет указанное время ожидания.
`int`	`getNumberWaiting()`	Возвращает количество участников, которые в данный момент ожидают в барьере.
`int`	`getParties()`	Возвращает количество участников, необходимых для срабатывания этого барьера.
`boolean`	`isBroken()`	Определяет, находится ли этот барьер в состоянии разрыва.
`void`	`reset()`	Сбрасывает барьер в начальное состояние.

Методы, унаследованные от класса java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

CyclicBarrier

public CyclicBarrier(int parties, Runnable barrierAction)

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

Параметры:: parties - количество потоков, которые должны вызвать await(), прежде чем барьер сработает; barrierAction - команда для выполнения, когда барьер срабатывает, или null, если нет действия
Исключения:: IllegalArgumentException - если parties меньше 1

CyclicBarrier

public CyclicBarrier(int parties)

Создает новую CyclicBarrier, которая будет срабатывать, когда заданное количество участников (потоков) будут ожидать её, и не выполняет предварительно определённого действия, когда барьер срабатывает.

Параметры:: parties - количество потоков, которые должны вызвать await(), прежде чем барьер сработает
Исключения:: IllegalArgumentException - если parties меньше 1

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

getParties

public int getParties()

Возвращает количество участников, необходимое для срабатывания барьера.

Возвращает:: количество участников, необходимых для срабатывания барьера

await

public int await() throws InterruptedException, BrokenBarrierException

Ожидает, пока все участники не вызовут await для этого барьера.

Если текущий поток не является последним, пришедшим, то он отключается для целей планирования потоков и находится в спящем состоянии до тех пор, пока не произойдёт одно из следующих событий:

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

Если текущий поток:

имеет установленный статус прерывания при входе в этот метод; или
прерывается во время ожидания

то InterruptedException выбрасывается, и статус прерывания текущего потока сбрасывается.

Если барьер reset() в то время, когда любой поток ожидает, или если барьер сломан при вызове await, или во время ожидания любого потока, то BrokenBarrierException выбрасывается.

Если какой-либо поток прерывается во время ожидания, то все остальные ожидающие потоки выбросят BrokenBarrierException, и барьер переведётся в состояние разрыва.

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

Возвращает:: индекс прибытия текущего потока, где индекс getParties() - 1 указывает на первого пришедшего, а ноль указывает на последнего, пришедшего
Исключения:: InterruptedException - если текущий поток был прерван во время ожидания; BrokenBarrierException - если другой поток был прерван или превысил время ожидания во время ожидания текущего потока, или барьер был сброшен, или барьер был сломан при вызове await, или действие барьера (если присутствует) завершилось с ошибкой

await

public int await(long timeout, TimeUnit unit) throws InterruptedException, BrokenBarrierException, TimeoutException

Ожидает, пока все участники не вызовут await для этого барьера, или заданное время ожидания истечёт.

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

Если текущий поток:

имеет установленный статус прерывания при входе в этот метод; или
прерывается во время ожидания

то InterruptedException выбрасывается, и статус прерывания текущего потока сбрасывается.

Если заданное время ожидания истекло, то TimeoutException выбрасывается. Если время равно или меньше нуля, то метод не будет ждать вовсе.

Параметры:: timeout - время ожидания барьера; unit - единица измерения времени параметра таймаута
Возвращает:: индекс прибытия текущего потока, где индекс getParties() - 1 указывает на первого пришедшего, а ноль указывает на последнего, пришедшего
Исключения:: InterruptedException - если текущий поток был прерван во время ожидания; TimeoutException - если заданное время ожидания истекло. В этом случае барьер будет сломан.; BrokenBarrierException - если другой поток был прерван или превысил время ожидания во время ожидания текущего потока, или барьер был сброшен, или барьер был сломан при вызове await, или действие барьера (если присутствует) завершилось с ошибкой

isBroken

public boolean isBroken()

Запрашивает, находится ли этот барьер в состоянии разрыва.

Возвращает:: true, если один или несколько участников вышли из этого барьера из-за прерывания или истечения времени ожидания со времени создания или последнего сброса, или действие барьера завершилось ошибкой; false в противном случае.

reset

public void reset()

Сбрасывает барьер в его начальное состояние. Если какие-либо участники в настоящее время ожидают у барьера, они вернутся с BrokenBarrierException. Обратите внимание, что сбросы после того, как произошел сбой по другим причинам, могут быть сложными для выполнения; потоки должны повторно синхронизироваться каким-то другим способом и выбрать один для выполнения сброса. Возможно, предпочтительнее создать новый барьер для последующего использования.

getNumberWaiting

public int getNumberWaiting()

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

Возвращает:: количество участников, которые в настоящее время заблокированы в await()

© 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/CyclicBarrier.html