KeReleaseSemaphore 函式 (wdm.h)

  • 發行項

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 提供等候線程的運行時間優先順序提升。 如果這個呼叫會將旗號設定為訊號狀態，則旗號計數會以指定的值來增強。 呼叫端也可以指定當 KeReleaseSemaphore 傳回控件時，它是否會立即呼叫其中一個 KeWaitXxx 例程。

釋放旗號物件會導致旗號計數由 Adjustment 參數的值來增強。 如果產生的值大於旗號物件的限制，則不會調整計數，並引發例外狀況STATUS_SEMAPHORE_LIMIT_EXCEEDED。

擴增旗號物件計數會導致旗號達到訊號狀態，並嘗試滿足號號對象上盡可能多的等候。

KeReleaseSemaphore 例程可能會暫時引發 IRQL。 如果 Wait 參數為 FALSE，則例程在傳回之前，會將 IRQL 還原至它在呼叫開始時所擁有的原始值。

如果 為 Wait = TRUE，則例程會傳回而不降低 IRQL。 在此情況下， KeReleaseSemaphore 呼叫必須緊接在 KeWaitXxx 呼叫之後。 藉由設定 Wait = TRUE，呼叫端可以防止 在 KeReleaseSemaphore 呼叫與 KeWaitXxx 呼叫之間發生不必要的內容切換。 KeWaitXxx 例程在傳回之前，會在 KeReleaseSemaphore 呼叫開始時將 IRQL 還原為其原始值。 雖然 IRQL 會停用兩個呼叫之間的內容切換，但這些呼叫無法可靠地當做不可部分完成作業的開始和結束使用。 例如，在這兩個呼叫之間，在另一個處理器上同時執行的線程可能會變更旗號對象的狀態或等候的目標。

警告

在 IRQL = PASSIVE_LEVEL執行的可分頁線程或可分頁驅動程式例程，不應該呼叫 KeReleaseSemaphore，並將 Wait 參數設定為 TRUE。 如果呼叫函式在 對KeReleaseSemaphore 和 KeWaitXxx的呼叫之間分頁，這類呼叫會造成嚴重頁面錯誤。

如需旗號對象的詳細資訊，請參閱 旗號物件。

KeReleaseSemaphore 的呼叫端必須在 IRQL <= DISPATCH_LEVEL前提是 Wait 設定為 FALSE。 否則，呼叫端必須在 IRQL = PASSIVE_LEVEL上執行。

規格需求

需求 值
最低支援的用戶端 從 Windows 2000 開始提供。
目標平台 Universal
標頭 wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫 NtosKrnl.lib
Dll NtosKrnl.exe
IRQL 請參閱一節。
DDI 合規性規則 HwStorPortProhibitedDIS (storport)

另請參閱

KeInitializeSemaphore

KeReadStateSemaphore

KeWaitForMultipleObjects

KeWaitForSingleObject