Класс CyclicBarrier

java.lang.Object

java.util.concurrent.CyclicBarrier

public class CyclicBarrier extends Object

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

Объект 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() в других потоках.

Начиная с:

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()`	Сбрасывает барьер в исходное состояние.

Методы, объявленные в классе Object

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

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создаёт и возвращает копию этого объекта.
`boolean`	`equals(Object obj)`	Указывает, равен ли этот объект какому-либо другому объекту.
`protected void`	`finalize()`	Устарело, планируется удаление: этот элемент API может быть удалён в будущей версии. Финализация считается устаревшей и может быть удалена в одном из будущих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`int`	`hashCode()`	Возвращает хеш-код этого объекта.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`String`	`toString()`	Возвращает строковое представление объекта.
`final void`	`wait()`	Заставляет текущий поток ожидать пробуждения, обычно посредством уведомления или прерывания.
`final void`	`wait(long timeoutMillis)`	Заставляет текущий поток ожидать пробуждения, обычно посредством уведомления или прерывания, либо до истечения определённого промежутка реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Заставляет текущий поток ожидать пробуждения, обычно посредством уведомления или прерывания, либо до истечения определённого промежутка реального времени.

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

CyclicBarrier

public CyclicBarrier(int parties, Runnable barrierAction)

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

CyclicBarrier

public CyclicBarrier(int parties)

Параметры:: 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.