Класс Semaphore

Счетный семафор. По концепции, семафор поддерживает набор разрешений. Каждый acquire() блокируется, если необходимо, до тех пор, пока разрешение не станет доступным, а затем берет его. Каждый release() добавляет разрешение, потенциально разблокируя заблокированный запрос. Однако фактические объекты разрешений не используются; семафор просто хранит счетчик доступного количества и действует соответственно.

Семафоры часто используются для ограничения количества потоков, которые могут получить доступ к некоторому (физическому или логическому) ресурсу. Например, вот класс, который использует семафор для управления доступом к пулу элементов:

class Pool {
   private static final int MAX_AVAILABLE = 100;
   private final Semaphore available = new Semaphore(MAX_AVAILABLE, true);

   public Object getItem() throws InterruptedException {
     available.acquire();
     return getNextAvailableItem();
   }

   public void putItem(Object x) {
     if (markAsUnused(x))
       available.release();
   }

   // Not a particularly efficient data structure; just for demo

   protected Object[] items = ... whatever kinds of items being managed
   protected boolean[] used = new boolean[MAX_AVAILABLE];

   protected synchronized Object getNextAvailableItem() {
     for (int i = 0; i < MAX_AVAILABLE; ++i) {
       if (!used[i]) {
          used[i] = true;
          return items[i];
       }
     }
     return null; // not reached
   }

   protected synchronized boolean markAsUnused(Object item) {
     for (int i = 0; i < MAX_AVAILABLE; ++i) {
       if (item == items[i]) {
          if (used[i]) {
            used[i] = false;
            return true;
          } else
            return false;
       }
     }
     return false;
   }
 }

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

Семафор, инициализированный единицей и используемый таким образом, что у него доступно не более одного разрешения, может служить блокировкой взаимного исключения. Это более известно как двоичный семафор, потому что он имеет только два состояния: одно разрешение доступно или ноль разрешений доступно. При использовании таким образом двоичный семафор обладает свойством (в отличие от многих Lock реализаций), что «блокировка» может быть освобождена потоком, отличным от владельца (поскольку семафоры не имеют понятия о владении). Это может быть полезно в некоторых специализированных контекстах, таких как восстановление тупика.

Конструктор этого класса необязательно принимает параметр справедливости. Если он установлен в false, этот класс не дает никаких гарантий относительно порядка, в котором потоки получают разрешения. В частности, разрешается вторжение, то есть потоку, вызывающему acquire(), может быть выделено разрешение раньше потока, который ожидал - логически новый поток помещает себя в начало очереди ожидающих потоков. Когда справедливость установлена в true, семафор гарантирует, что потоки, вызывающие любой из acquire методов, выбираются для получения разрешений в том порядке, в котором их вызов этих методов был обработан (первый вошел, первый вышел; FIFO). Обратите внимание, что упорядочение FIFO обязательно применяется к определенным внутренним точкам выполнения в этих методах. Таким образом, один поток может вызвать acquire перед другим, но достичь точки упорядочения после другого, и аналогично при возвращении из метода. Также обратите внимание, что методы tryAcquire без учета времени не учитывают настройку справедливости, а будут брать любые доступные разрешения.

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

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

Эффекты согласованности памяти: Действия в потоке перед вызовом метода «release», например, release() предшествуют действиям, следующим за успешным методом «acquire», например, acquire() в другом потоке.

Конструкторы

Semaphore

public Semaphore(int permits)

Создаёт Semaphore с заданным количеством разрешений и настройкой справедливости nonfair.

Параметры:

permits - начальное количество доступных разрешений. Это значение может быть отрицательным, в этом случае, прежде чем какие-либо разрешения будут предоставлены, должны произойти освобождения.

Semaphore

public Semaphore(int permits,
                 boolean fair)

Создаёт Semaphore с заданным количеством разрешений и заданной настройкой справедливости.

Параметры:

permits - начальное количество доступных разрешений. Это значение может быть отрицательным, в этом случае, прежде чем какие-либо разрешения будут предоставлены, должны произойти освобождения.

fair - true если этот семафор гарантирует предоставление разрешений в порядке очереди при конкуренции, иначе false

Методы

acquire

public void acquire()
             throws InterruptedException

Выбрасывает:

InterruptedException - если текущий поток прерван

acquireUninterruptibly

public void acquireUninterruptibly()

tryAcquire

public boolean tryAcquire()

Возвращает:

true если разрешение было приобретено и false в противном случае

tryAcquire

public boolean tryAcquire(long timeout,
                          TimeUnit unit)
                   throws InterruptedException

Параметры:

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

unit - единица измерения времени для аргумента timeout

Возвращает:

true если разрешение было приобретено и false если время ожидания истекло, прежде чем разрешение было приобретено

Выбрасывает:

InterruptedException - если текущий поток прерван

release

public void release()

acquire

public void acquire(int permits)
             throws InterruptedException

Параметры:

permits - количество разрешений для приобретения

Выбрасывает:

InterruptedException - если текущий поток прерван

IllegalArgumentException - если permits отрицательно

acquireUninterruptibly

public void acquireUninterruptibly(int permits)

Параметры:

permits - количество разрешений для приобретения

Выбрасывает:

IllegalArgumentException - если permits отрицательно

tryAcquire

public boolean tryAcquire(int permits)

Параметры:

permits - количество разрешений для приобретения

Возвращает:

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

Выбрасывает:

IllegalArgumentException - если permits отрицательно

tryAcquire

public boolean tryAcquire(int permits,
                          long timeout,
                          TimeUnit unit)
                   throws InterruptedException

Параметры:

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

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

unit - единица измерения времени для аргумента timeout

Возвращает:

true если все разрешения были получены и false если время ожидания истекло до получения всех разрешений

Исключения:

InterruptedException - если текущий поток прерван

IllegalArgumentException - если permits отрицательное

release

public void release(int permits)

Параметры:

permits - количество разрешений для освобождения

Исключения:

IllegalArgumentException - если permits отрицательное

availablePermits

public int availablePermits()

Возвращает:

количество разрешений, доступных в этом семафоре

drainPermits

public int drainPermits()

Получает и возвращает все разрешения, которые немедленно доступны.

Возвращает:

количество полученных разрешений

reducePermits

protected void reducePermits(int reduction)

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

Параметры:

reduction - количество разрешений для удаления

Исключения:

IllegalArgumentException - если reduction отрицательное

isFair

public boolean isFair()

Возвращает true если для этого семафора установлена справедливость.

Возвращает:

true если для этого семафора установлена справедливость

hasQueuedThreads

public final boolean hasQueuedThreads()

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

Возвращает:

true если могут быть другие потоки, ждущие получения

getQueueLength

public final int getQueueLength()

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

Возвращает:

оцененное количество потоков, ожидающих этого замка

getQueuedThreads

protected Collection<Thread> getQueuedThreads()

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

Возвращает:

коллекцию потоков

toString

public String toString()

Возвращает строку, идентифицирующую этот семафор, а также его состояние. Состояние, в скобках, включает строку "Permits =", за которой следует количество разрешений.

Переопределяет:

toString в классе Object

Возвращает:

строку, идентифицирующую этот семафор, а также его состояние