KeWaitForSingleObject-Funktion (wdm.h)

Artikel
08/08/2023

Die KeWaitForSingleObject-Routine versetzt den aktuellen Thread in einen Wartezustand, bis das angegebene Dispatcherobjekt auf einen signalierten Zustand festgelegt ist, oder (optional), bis das Wartezeitüberschreitungsüberschreitung eintritt.

Syntax

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

Parameter

[in] Object

Zeiger auf ein initialisiertes Dispatcherobjekt (Ereignis, Mutex, Semaphor, Thread oder Timer), für das der Aufrufer den Speicher bereitstellt. Das Dispatcherobjekt muss sich im nicht auslagerten Systemspeicher befinden. Weitere Informationen finden Sie in den Hinweisen.

[in] WaitReason

Gibt den Grund für die Wartezeit an. Ein Treiber sollte diesen Wert auf Executive festlegen, es sei denn, er arbeitet im Auftrag eines Benutzers und wird im Kontext eines Benutzerthreads ausgeführt. In diesem Fall sollte er diesen Wert auf UserRequest festlegen.

[in] WaitMode

Gibt an, ob der Aufrufer in KernelMode oder UserMode wartet. Treiber der niedrigsten und mittleren Ebene sollten KernelMode angeben. Wenn das angegebene Objekt ein Mutex ist, muss der Aufrufer KernelMode angeben.

[in] Alertable

Gibt einen booleschen Wert an, der TRUE ist, wenn die Wartezeit warnungsfähig ist, andernfalls FALSE .

[in, optional] Timeout

Zeiger auf einen Timeoutwert, der die absolute oder relative Zeit in 100 Nanosekundeneinheiten angibt, bei der die Wartezeit abgeschlossen werden soll.

Ein positiver Wert gibt eine absolute Zeit relativ zum 1. Januar 1601 an. Ein negativer Wert gibt ein Intervall relativ zur aktuellen Zeit an. Absolute Ablaufzeiten nachverfolgen alle Änderungen der Systemzeit; relative Ablaufzeiten werden von Systemzeitänderungen nicht beeinflusst.

Wenn Timeout = 0 ist, wird die Routine ohne Wartezeit zurückgegeben. Wenn der Aufrufer einen NULL-Zeiger bereitstellt, wartet die Routine unbegrenzt, bis das Dispatcherobjekt auf den signalierten Zustand festgelegt ist. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Rückgabewert

KeWaitForSingleObject kann eine der folgenden Elemente zurückgeben.

Das NT_SUCCESS Makro erkennt alle diese status Werte als "Erfolgswerte".

Rückgabecode	Beschreibung
STATUS_SUCCESS	Das vom Object-Parameter angegebene Dispatcherobjekt hat die Wartezeit erfüllt.
STATUS_ALERTED	Die Wartezeit wurde unterbrochen, um eine Warnung an den aufrufenden Thread zu übermitteln.
STATUS_USER_APC	Die Wartezeit wurde unterbrochen, um einen Asynchronen Prozeduraufruf (User Asynchronous Procedure Call, APC) an den aufrufenden Thread zu übermitteln.
STATUS_TIMEOUT	Ein Timeout ist aufgetreten, bevor das Objekt auf einen Signalzustand festgelegt wurde. Dieser Wert kann zurückgegeben werden, wenn der angegebene Satz von Wartebedingungen nicht sofort erfüllt werden kann und timeout auf 0 festgelegt ist.

Hinweise

Der aktuelle Zustand des angegebenen Objekts wird untersucht, um festzustellen, ob die Wartezeit sofort erfüllt werden kann. Wenn ja, werden die erforderlichen Nebenwirkungen auf das Objekt ausgeführt. Andernfalls wird der aktuelle Thread in einen Wartezustand versetzt, und ein neuer Thread wird für die Ausführung auf dem aktuellen Prozessor ausgewählt.

Der Warnungsparameter bestimmt, wann der Thread benachrichtigt werden kann und dessen Wartezustand daher abgebrochen wird. Weitere Informationen finden Sie unter Wartezeiten und APCs.

Ein besonderer Aspekt gilt, wenn der anKeWaitForSingleObject übergebene Object-Parameter ein Mutex ist. Wenn das Verteilerobjekt, auf das gewartet wurde, ein Mutex ist, ist die APC-Übermittlung die gleiche wie für alle anderen Dispatcherobjekte während der Wartezeit. Nachdem KeWaitForSingleObject jedoch mit STATUS_SUCCESS zurückgegeben wird und der Thread tatsächlich den Mutex enthält, werden nur spezielle Kernelmodus-APCs bereitgestellt. Die Übermittlung aller anderen APCs, sowohl im Kernelmodus als auch im Benutzermodus, ist deaktiviert. Diese Einschränkung für die Übermittlung von APCs bleibt bestehen, bis der Mutex freigegeben wird.

Das Dispatcherobjekt, auf das vom Object-Parameter verwiesen wird, muss sich im nicht ausgestellten Systemspeicher befinden.

Wenn der WaitMode-ParameterUserMode ist, kann der Kernelstapel während der Wartezeit ausgetauscht werden. Folglich darf ein Aufrufer niemals versuchen, Parameter auf dem Stapel zu übergeben, wenn KeWaitForSingleObject mithilfe des UserMode-Arguments aufgerufen wird. Wenn Sie das Ereignis im Stapel zuordnen, müssen Sie den WaitMode-Parameter auf KernelMode festlegen.

Es ist besonders wichtig, den Rückgabewert von KeWaitForSingleObject zu überprüfen, wenn der WaitMode-ParameterUserMode oder AlertableTRUE ist, da KeWaitForSingleObject möglicherweise frühzeitig mit einer status von STATUS_USER_APC oder STATUS_ALERTED zurückgegeben wird.

Alle langfristigen Wartezeiten, die von einem Benutzer abgebrochen werden können, sollten UserMode waits und Alertable auf FALSE festgelegt werden.

Warnungsfähig sollte nach Möglichkeit auf FALSE und WaitMode auf KernelMode festgelegt werden, um die Treiberkomplexität zu verringern. Die Prinzipalausnahme hierfür ist, wenn es sich bei der Wartezeit um eine langfristige Wartezeit handelt.

Wenn ein NULL-Zeiger für Timeout bereitgestellt wird, bleibt der aufrufende Thread im Wartezustand, bis das Objekt signalisiert wird.

Ein Timeoutwert von 0 ermöglicht das Testen einer Reihe von Wartebedingungen und für die bedingte Leistung etwaiger Nebenwirkungen, wenn die Wartezeit sofort erfüllt werden kann, wie beim Erwerb eines Mutex.

Timeoutintervalle werden relativ zur Systemuhr gemessen, und die Genauigkeit, mit der das Betriebssystem das Ende eines Timeoutintervalls erkennen kann, wird durch die Granularität der Systemuhr begrenzt. Weitere Informationen finden Sie unter Timergenauigkeit.

Ein Mutex kann nur minlong-mal rekursiv erworben werden. Wenn dieser Grenzwert überschritten wird, löst die Routine eine STATUS_MUTANT_LIMIT_EXCEEDED Ausnahme aus.

Aufrufer von KeWaitForSingleObject müssen unter IRQL <= DISPATCH_LEVEL ausgeführt werden. Wenn jedoch Timeout = NULL oder Timeout != 0 ausgeführt wird, muss der Aufrufer unter IRQL <= APC_LEVEL und in einem nichtarbiträren Threadkontext ausgeführt werden. Wenn Timeout != NULL und Timeout = 0 sind, muss der Aufrufer bei IRQL <= DISPATCH_LEVEL ausgeführt werden.

KeWaitForMutexObject ist ein Makro, das in KeWaitForSingleObject konvertiert wird, das stattdessen verwendet werden kann.

Verwenden Sie schnelle Mutexes oder bewachte Mutexes, um eine bessere Leistung zu erzielen. Weitere Informationen finden Sie unter Alternativen zu Mutex-Objekten.

Weitere Informationen zu Mutex-Objekten finden Sie unter Mutex-Objekte.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Weitere Informationen finden Sie im Abschnitt mit den Hinweisen.
DDI-Complianceregeln	CompleteRequestStatusCheck(wdm), HwStorPortProhibitedDIs(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)