Функция ReleaseSemaphore (synchapi.h)

Статья
03/08/2023

Увеличивает количество указанного объекта семафора на указанную величину.

Синтаксис

BOOL ReleaseSemaphore(
  [in]            HANDLE hSemaphore,
  [in]            LONG   lReleaseCount,
  [out, optional] LPLONG lpPreviousCount
);

Параметры

[in] hSemaphore

Дескриптор объекта семафора. Функция CreateSemaphore или OpenSemaphore возвращает этот дескриптор.

Этот дескриптор должен иметь право доступа SEMAPHORE_MODIFY_STATE . Дополнительные сведения см. в разделе Синхронизация безопасности объектов и прав доступа.

[in] lReleaseCount

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

[out, optional] lpPreviousCount

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

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

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

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

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

Невозможно уменьшить число объектов семафора с помощью ReleaseSemaphore, так как lReleaseCount не может быть отрицательным числом. Чтобы временно ограничить или уменьшить доступ, создайте цикл, в котором вызывается функция WaitForSingleObject с интервалом времени ожидания, равным нулю, пока число семафоров не будет достаточно сокращено. (Обратите внимание, что другие потоки могут уменьшить количество во время выполнения этого цикла.) Чтобы восстановить доступ, вызовите ReleaseSemaphore с числом выпусков, равным количеству вызовов WaitForSingleObject в цикле.

Примеры

Пример использования ReleaseSemaphore см. в разделе Использование объектов семафора.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	synchapi.h (включает Windows.h в Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Библиотека	Kernel32.lib
DLL	Kernel32.dll