Класс QSemaphore

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

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

Примечание: Все функции в этом классе являются потокобезопасными.

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

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

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

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

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

• acquire(n) пытается приобрести n ресурсов. Если таких ресурсов недостаточно, вызов будет заблокирован, пока это не станет возможным.
• release(n) освобождает n ресурсов.

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

Пример:

QSemaphore sem(5);      // sem.available() == 5

sem.acquire(3);         // sem.available() == 2
sem.acquire(2);         // sem.available() == 0
sem.release(5);         // sem.available() == 5
sem.release(5);         // sem.available() == 10

sem.tryAcquire(1);      // sem.available() == 9, returns true
sem.tryAcquire(250);    // sem.available() == 9, returns false

Типичное применение семафоров — управление доступом к кольцевому буферу, совместно используемому потоком-производителем и потоком-потребителем. Пример с семафорами (Semaphores Example) демонстрирует, как использовать QSemaphore для решения этой задачи.

Невычислительный пример семафора — обед в ресторане. Семафор инициализируется количеством стульев в ресторане. По мере прибытия людей они хотят занять место. По мере заполнения мест available() уменьшается. По мере ухода людей available() увеличивается, позволяя войти большему количеству людей. Если группа из 10 человек хочет сесть, но есть только 9 мест, эти 10 человек будут ждать, но группа из 4 человек сядет (занимая доступные места до 5, что заставит группу из 10 человек ждать дольше).

См. также QSemaphoreReleaser, QMutex, QWaitCondition, QThread и Пример с семафорами.

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

QSemaphore::QSemaphore(int n = 0)

Создаёт новый семафор и инициализирует количество ресурсов, которые он защищает, до n (по умолчанию 0).

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

QSemaphore::~QSemaphore()

Удаляет семафор.

Предупреждение: Удаление используемого семафора может привести к неопределённому поведению.

void QSemaphore::acquire(int n = 1)

Пытается приобрести n ресурсов, защищённых семафором. Если n > available(), этот вызов будет заблокирован, пока не будет достаточно ресурсов.

См. также release(), available() и tryAcquire().

int QSemaphore::available() const

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

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

void QSemaphore::release(int n = 1)

Освобождает n ресурсов, защищённых семафором.

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

QSemaphore sem(5);      // a semaphore that guards 5 resources
sem.acquire(5);         // acquire all 5 resources
sem.release(5);         // release the 5 resources
sem.release(10);        // "create" 10 new resources

QSemaphoreReleaser — это RAII-обёртка вокруг этой функции.

См. также acquire(), available() и QSemaphoreReleaser.

bool QSemaphore::tryAcquire(int n = 1)

Пытается приобрести n ресурсов, защищённых семафором, и возвращает true при успехе. Если available() < n, этот вызов немедленно возвращает false без приобретения каких-либо ресурсов.

Пример:

QSemaphore sem(5);      // sem.available() == 5
sem.tryAcquire(250);    // sem.available() == 5, returns false
sem.tryAcquire(3);      // sem.available() == 2, returns true

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

bool QSemaphore::tryAcquire(int n, int timeout)

Пытается приобрести n ресурсов, защищённых семафором, и возвращает true при успехе. Если available() < n, этот вызов будет ждать не более timeout миллисекунд, пока ресурсы не станут доступными.

Примечание: Передача отрицательного значения в качестве timeout эквивалентна вызову acquire(), т.е. эта функция будет ждать вечно, пока ресурсы не станут доступными, если timeout отрицателен.

Пример:

QSemaphore sem(5);            // sem.available() == 5
sem.tryAcquire(250, 1000);    // sem.available() == 5, waits 1000 milliseconds and returns false
sem.tryAcquire(3, 30000);     // sem.available() == 2, returns true without waiting

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