KeWaitForSingleObject 函式 (wdm.h)

發行項
02/27/2024

KeWaitForSingleObject 例程會將目前的線程放入等候狀態，直到指定的發送器物件設定為訊號狀態，或 (選擇性地) 直到等候逾時為止。

語法

NTSTATUS
KeWaitForSingleObject (
    PVOID Object,
    KWAIT_REASON WaitReason,
    KPROCESSOR_MODE WaitMode,
    BOOLEAN Alertable,
    PLARGE_INTEGER Timeout
    );

參數

[in] Object

初始化發送器物件的指標， (事件、mutex、號誌、線程或定時器) ，呼叫端會為其提供記憶體。發送器對象必須位於非分頁的系統記憶體中。如需詳細資訊，請參閱＜備註＞。

[in] WaitReason

指定等候的原因。驅動程式應該將此值設定為 Executive，除非它代表使用者執行工作，並在使用者線程的內容中執行，在此情況下，它應該將此值設定為 UserRequest。

[in] WaitMode

指定呼叫端是否在 KernelMode 或 UserMode 中等候。最低層級和中繼驅動程序應該指定 KernelMode。如果指定的 Object 是 mutex，則呼叫端必須指定 KernelMode。

[in] Alertable

指定布爾值，如果等候為可警示，則為 TRUE ，否則為 FALSE 。

[in, optional] Timeout

以 100 奈秒為單位指定絕對或相對時間的逾時值指標，等候完成。

正值指定相對於 1601 年 1 月 1 日的絕對時間。負值會指定相對於目前時間的間隔。絕對到期時間會追蹤系統時間中的任何變更;相對到期時間不會受到系統時間變更的影響。

如果 Timeout = 0，則例程會傳回而不等待。如果呼叫端提供 NULL 指標，則例程會無限期等候，直到發送器物件設定為已發出訊號的狀態為止。如需詳細資訊，請參閱接下來的＜備註＞一節。

傳回值

KeWaitForSingleObject 可以傳回下列其中一項。

NT_SUCCESS宏會將所有這些狀態值辨識為「成功」值。

傳回碼	Description
STATUS_SUCCESS	Object 參數指定的發送器對象滿足等候。
STATUS_ALERTED	等候已中斷，以將警示傳遞至呼叫線程。
STATUS_USER_APC	等候已中斷，將APC (異步過程調用傳遞至呼叫線程) 。
STATUS_TIMEOUT	物件設定為訊號狀態之前發生逾時。當指定的等候條件集無法立即符合且 Timeout 設定為零時，可以傳回此值。

備註

系統會檢查所指定 物件的 目前狀態，以判斷是否可以立即滿足等候。如果是，則會對對對象執行必要的副作用。否則，目前的線程會進入等候狀態，並選取新的線程以在目前的處理器上執行。

Alertable 參數會判斷線程何時可以發出警示，以及其等候狀態因而中止。如需詳細資訊，請參閱等候和 APC。

當傳遞至 KeWaitForSingleObject的 Object 參數是 mutex 時，適用特殊考慮。如果等候的發送器對像是 mutex，則 APC 傳遞與等候期間所有其他發送器物件相同。不過， 在 KeWaitForSingleObject 傳回STATUS_SUCCESS，而線程實際上會保存 mutex 之後，只會傳遞特殊的內核模式 APC。已停用核心模式和使用者模式的所有其他 APC 傳遞。在釋放 mutex 之前，傳遞 APC 的限制會持續存在。

Object 參數指向的發送器對象必須位於非分頁系統記憶體中。

如果 WaitMode 參數是 UserMode，則可以在等候期間交換核心堆疊。因此，呼叫端絕對不能嘗試在使用UserMode自變數呼叫KeWaitForSingleObject時，在堆疊上傳遞參數。如果您在堆疊上配置事件，則必須將 WaitMode 參數設定為 KernelMode。

當 WaitMode 參數為 UserMode 或 Alertable 為 TRUE 時，請務必檢查 KeWaitForSingleObject 的傳回值，因為 KeWaitForSingleObject 可能會提早傳回狀態為 STATUS_USER_APC 或 STATUS_ALERTED。

用戶可中止的所有長期等候應該是 UserMode 等候，而且 Alertable 應設定為 FALSE。

可能的話， Alertable 應該設定為 FALSE ，而且 WaitMode 應設定為 KernelMode，以減少驅動程式的複雜度。此作業的主要例外狀況是等候是長期等候的時間。

如果為 Timeout 提供 NULL 指標，則呼叫線程會維持等候狀態，直到發出物件訊號為止。

零的逾時值允許測試一組等候條件，以及在可立即滿足等候時的任何副作用的條件效能，如同取得 Mutex 一樣。

逾時間隔會相對於系統時鐘進行測量，而且操作系統可以偵測超時時間間隔結束的精確度受限於系統時鐘的數據粒度。如需詳細資訊，請參閱定時器精確度。

Mutex 只能以遞歸方式取得MINLONG時間。如果超過此限制，例程會引發STATUS_MUTANT_LIMIT_EXCEEDED例外狀況。

KeWaitForSingleObject 的呼叫端必須在 IRQL <= DISPATCH_LEVEL執行。不過，如果 Timeout = NULL 或 Timeout ！= 0，則呼叫端必須在 IRQL <= APC_LEVEL和非位線程內容中執行。如果 Timeout ！= NULL 和 Timeout = 0，則呼叫端必須在 IRQL <= DISPATCH_LEVEL執行。

KeWaitForMutexObject 是轉換成 KeWaitForSingleObject 的宏，可以改用。

為了提升效能，請使用快速 Mutex 或受防護的 mutex。如需詳細資訊，請參閱 Mutex 物件的替代方案。

如需 Mutex 物件的詳細資訊，請參閱 Mutex 物件。

規格需求

需求	值
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	請參閱一節。
DDI 合規性規則	CompleteRequestStatusCheck (wdm) 、 HwStorPortProhibitedDDIs (storport) 、 IoAllocateIrpSignalEventInCompletionTimeout (wdm) 、 IoBuildDeviceControlWait (wdm) 、 IoBuildDeviceControlWaitTimeout (wdm) ， IoBuildFsdIrpSignalEventInCompletionTimeout (wdm) ， IoBuildSynchronousFsdRequestWait (wdm) ， IoBuildSynchronousFsdRequestWaitTimeout (wdm) ， IrpProcessingComplete (wdm) 、 IrqlKeWaitForMutexObject (wdm) 、 LowerDriverReturn (wdm) 、 MarkIrpPending2 (wdm) 、 PendedCompletedRequest (wdm () 、 PendedCompletedRequest2 (wdm) 、 PendedCompletedRequest3 (wdm) 、 PendedCompletedRequestEx (wdm) 、 RemoveLockForwardDeviceControl (wdm) 、 RemoveLockForwardDeviceControlInternal (wdm) 、 RemoveLockForwardRead (wdm) 、 RemoveLockForwardWrite (wdm) 、 SpNoWait (storport) 、 StartDeviceWait (wdm) 、 StartDeviceWait2 (wdm) 、 StartDeviceWait3 (wdm) 、 StartDeviceWait4 (wdm)