Функция KeReleaseSemaphore (wdm.h)

Статья
06/02/2023

Подпрограмма KeReleaseSemaphore освобождает указанный объект семафора.

Синтаксис

LONG KeReleaseSemaphore(
  [in, out] PRKSEMAPHORE Semaphore,
  [in]      KPRIORITY    Increment,
  [in]      LONG         Adjustment,
  [in]      BOOLEAN      Wait
);

Параметры

[in, out] Semaphore

Указатель на инициализированный объект семафора, для которого вызывающий объект предоставляет хранилище.

[in] Increment

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

[in] Adjustment

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

[in] Wait

Указывает, должен ли за вызовом KeReleaseSemaphore немедленно следовать вызов одной из подпрограмм KeWaitXxx . Если задано значение TRUE, за вызовом KeReleaseSemaphore должен следовать вызов KeWaitForMultipleObjects, KeWaitForMutexObject или KeWaitForSingleObject. Дополнительные сведения см. в разделе "Примечания".

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

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

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

Освобождение объекта семафора приводит к тому, что число семафоров будет дополнено значением параметра Adjustment . Если полученное значение превышает предел объекта семафора, счетчик не корректируется и возникает исключение, STATUS_SEMAPHORE_LIMIT_EXCEEDED.

Увеличение числа объектов семафора приводит к тому, что семафор достигает сигнального состояния, и предпринимается попытка удовлетворить как можно больше ожиданий объекта семафора.

Подпрограмма KeReleaseSemaphore может временно вызвать IRQL. Если параметр Wait имеет значение FALSE, подпрограмма перед возвратом восстанавливает irQL до исходного значения, которое было в начале вызова.

Если значение Wait = TRUE, подпрограмма возвращает без понижения значения IRQL. В этом случае за вызовом KeReleaseSemaphore должен следовать вызов KeWaitXxx . Задав значение Wait = TRUE, вызывающий объект может предотвратить ненужное переключение контекста между вызовом KeReleaseSemaphore и вызовом KeWaitXxx. Подпрограмма KeWaitXxx перед возвратом восстанавливает исходное значение IRQL в начале вызова KeReleaseSemaphore . Хотя IRQL отключает переключения контекста между двумя вызовами, эти вызовы нельзя надежно использовать в качестве начала и окончания атомарной операции. Например, между этими двумя вызовами поток, выполняющийся одновременно на другом процессоре, может изменить состояние объекта семафора или целевого объекта ожидания.

Предупреждение

Для страничного потока или подпрограммы драйвера, которая выполняется в irQL = PASSIVE_LEVEL никогда не следует вызывать KeReleaseSemaphore с параметром Wait , равным TRUE. Такой вызов приводит к неустранимой ошибке страницы, если вызывающая функция выходит на страницу между вызовами KeReleaseSemaphore и KeWaitXxx.

Дополнительные сведения об объектах семафора см. в разделе Объекты семафора.

Вызывающие методы KeReleaseSemaphore должны выполняться со значением IRQL <= DISPATCH_LEVEL при условии, что параметр Wait имеет значение FALSE. В противном случае вызывающий объект должен выполняться в irQL = PASSIVE_LEVEL.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 2000.
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	См. раздел "Примечания".
Правила соответствия DDI	HwStorPortProhibitedDIs(storport)

См. также раздел

KeInitializeSemaphore

KeReadStateSemaphore

KeWaitForMultipleObjects

KeWaitForSingleObject