Класс QSystemSemaphore

Класс QSystemSemaphore предоставляет общий счётный системный семафор. Подробнее...

• Список всех членов, включая унаследованные

Типы общедоступного доступа

Общедоступные функции

Подробное описание

Класс QSystemSemaphore предоставляет общий счётный системный семафор.

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

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

Семафоры поддерживают две основные операции, acquire() и release():

acquire() пытается захватить один ресурс. Если ресурс недоступен, вызов блокируется, пока ресурс не станет доступным. Затем ресурс захватывается, и вызов возвращает значение.

release() освобождает один ресурс, чтобы к нему мог обратиться другой процесс. Функцию также можно вызвать с параметром n > 1, который освобождает n ресурсов.

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

Пример: Создание системного семафора

QSystemSemaphore sem("market", 3, QSystemSemaphore::Create);
                             // resources available == 3
sem.acquire();               // resources available == 2
sem.acquire();               // resources available == 1
sem.acquire();               // resources available == 0
sem.release();               // resources available == 1
sem.release(2);              // resources available == 3

Типичным применением системных семафоров является управление доступом к кольцевому буферу, который совместно используется процессом-производителем и процессом-потребителем.

Платформенно-специфическое поведение

При использовании этого класса следует учитывать следующие различия между платформами:

Windows: QSystemSemaphore не владеет своим системным семафором. Им владеет Windows. Это означает, что когда все экземпляры QSystemSemaphore для определённого ключа были уничтожены, либо путём вызова их деструкторов, либо потому что один или несколько процессов зависли, Windows удаляет системный семафор.

Unix:

• QSystemSemaphore владеет системным семафором в системах Unix. Это означает, что последний процесс, имеющий экземпляр QSystemSemaphore для определённого ключа, должен удалить системный семафор в своём деструкторе. Если последний процесс зависает, не выполнив деструктор QSystemSemaphore, Unix не удаляет системный семафор автоматически, и семафор остаётся после зависания. Следующий процесс, который создаёт QSystemSemaphore с тем же ключом, получит существующий системный семафор. В этом случае, если конструктор QSystemSemaphore указал режим доступа как Open, его начальное число ресурсов не будет сброшено до указанного, а останется установленным на значение, полученное в зависшем процессе. Для защиты от этого первый процесс, создающий семафор для конкретного ключа (обычно сервер), должен передать режим доступа как Create, что заставит Unix сбросить счётчик ресурсов в системном семафоре.
• Когда процесс, использующий QSystemSemaphore, завершается по любой причине, Unix автоматически отменяет действие всех операций захвата, которые не были освобождены. Таким образом, если процесс захватывает ресурс, а затем завершается, не освобождая его, Unix освободит этот ресурс.

См. также QSharedMemory и QSemaphore.

Документация по типам членов

перечисление QSystemSemaphore::AccessMode

Это перечисление используется конструктором и setKey(). Его цель состоит в том, чтобы разрешить обработку проблемы в реализациях семафоров на Unix, которые сохраняются после сбоя. В Unix, когда семафор сохраняется после сбоя, нам нужен способ принудительно сбросить его счётчик ресурсов, когда система повторно использует семафор. В Windows, где семафоры не могут сохраняться после сбоя, это перечисление не имеет эффекта.

перечисление QSystemSemaphore::SystemSemaphoreError

Документация по функциям-членам

QSystemSemaphore::QSystemSemaphore(const QString &key, int initialValue = 0, QSystemSemaphore::AccessMode mode = Open)

Запрашивает системный семафор для указанного key. Параметры initialValue и mode используются в соответствии со следующими правилами, которые зависят от системы.

В Unix, если mode равен Open и системный семафор уже идентифицируется по key, используется этот семафор, и счётчик ресурсов семафора не изменяется, т.е., initialValue игнорируется. Но если системный семафор по key ещё не существует, создаётся новый семафор для этого ключа и устанавливается его счётчик ресурсов на initialValue.

В Unix, если режим равен Создать и в системе уже есть семафор, идентифицированный по ключу, используется этот семафор, а его счетчик ресурсов устанавливается в значение initialValue. Если в системе ещё нет семафора с заданным ключом, создаётся новый семафор для этого ключа, и его счетчик ресурсов устанавливается в initialValue.

В Windows параметр режим игнорируется, и система всегда пытается создать семафор для указанного ключа. Если в системе ещё нет семафора с заданным ключом, создаётся семафор, и его счетчик ресурсов устанавливается в initialValue. Но если в системе уже есть семафор с заданным ключом, используется этот семафор, а initialValue игнорируется.

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

См. также acquire() и key().

QSystemSemaphore::~QSystemSemaphore()

Деструктор уничтожает объект QSystemSemaphore, но системный семафор не удаляется из системы, пока этот экземпляр QSystemSemaphore является последним для этого системного семафора.

Два важных побочных эффекта деструктора зависят от системы. В Windows, если для этого семафора был вызван acquire(), но не release(), release() не будет вызван деструктором, и ресурс не будет освобождён при нормальном завершении процесса. Это будет ошибка программы, которая может привести к тупиковой ситуации в другом процессе, пытающемся получить тот же ресурс. В Unix, полученные ресурсы, которые не были освобождены до вызова деструктора, автоматически освобождаются при завершении процесса.

bool QSystemSemaphore::acquire()

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

Если возвращается false, произошла системная ошибка. Вызовите error(), чтобы получить значение QSystemSemaphore::SystemSemaphoreError, которое указывает, какая ошибка произошла.

См. также release().

QSystemSemaphore::SystemSemaphoreError QSystemSemaphore::error() const

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

См. также errorString().

QString QSystemSemaphore::errorString() const

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

См. также error().

QString QSystemSemaphore::key() const

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

См. также setKey().

bool QSystemSemaphore::release(int n = 1)

Освобождает n ресурсов, защищаемых семафором. Возвращает true, если нет системной ошибки.

Пример: Создайте системный семафор с пятью ресурсами; получите все из них, а затем освободите все.

QSystemSemaphore sem("market", 5, QSystemSemaphore::Create);
for (int i = 0; i < 5; ++i)  // acquire all 5 resources
    sem.acquire();
sem.release(5);              // release the 5 resources

Эта функция также может «создавать» ресурсы. Например, сразу после последовательности операторов выше, предположим, что мы добавили оператор:

sem.release(10);          // "create" 10 new resources

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

См. также acquire().

void QSystemSemaphore::setKey(const QString &key, int initialValue = 0, QSystemSemaphore::AccessMode mode = Open)

Эта функция работает так же, как конструктор. Она перестраивает этот объект QSystemSemaphore. Если новый ключ отличается от старого, вызов этой функции аналогичен вызову деструктора семафора со старым ключом, а затем вызову конструктора для создания нового семафора с новым ключом. Параметры initialValue и mode определены так же, как и для конструктора.

См. также QSystemSemaphore() и key().