KeWaitForSingleObject-Funktion (wdm.h)

Die KeWaitForSingleObject-Routine versetzt den aktuellen Thread in einen Wartezustand, bis das angegebene Dispatcherobjekt auf einen signalisierten Zustand oder (optional) festgelegt ist, bis die Wartezeit überschritten wird.

Syntax

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

Die 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 seitenseitigen 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 dieser Wert auf "UserRequest" festgelegt werden.

[in] WaitMode

Gibt an, ob der Aufrufer in KernelMode oder UserMode wartet. Die Untergeordneten und Zwischentreiber sollten KernelMode angeben. Wenn das angegebene Objekt ein Mutex ist, muss der Aufrufer KernelMode angeben.

[in] Alertable

Gibt einen booleschen Wert an, der WAHR ist, wenn die Wartezeit warnbar ist und andernfalls FALSE .

[in, optional] Timeout

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

Ein positiver Wert gibt eine absolute Zeit im Verhältnis zum 1. Januar 1601 an. Ein negativer Wert gibt ein Intervall relativ zur aktuellen Uhrzeit an. Absolute Ablaufzeiten verfolgen alle Änderungen der Systemzeit; Relative Ablaufzeiten sind von Systemzeitänderungen nicht betroffen.

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

Rückgabewert

KeWaitForSingleObject kann eine der folgenden Werte zurückgeben.

Das NT_SUCCESS Makro erkennt alle diese Statuswerte als "Erfolgswerte".

Bemerkungen

Der aktuelle Zustand des angegebenen Objekts wird untersucht, um festzustellen, ob die Wartezeit sofort erfüllt werden kann. Wenn ja, werden die erforderlichen Nebenwirkungen für 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 Alertable-Parameter bestimmt, wann der Thread benachrichtigt werden kann, und der Wartezustand wird daher abgebrochen. Weitere Informationen finden Sie unter "Waits" und "APCs".

Eine besondere Berücksichtigung gilt, wenn der an KeWaitForSingleObject übergebene Object-Parameter ein Mutex ist. Wenn das dispatcher-Objekt, auf dem gewartet wurde, ein Mutex ist, ist die APC-Übermittlung identisch mit allen anderen Dispatcherobjekten während der Wartezeit. Nachdem KeWaitForSingleObject jedoch mit STATUS_SUCCESS zurückgegeben wurde und der Thread tatsächlich den Mutex enthält, werden nur spezielle Kernelmodus-APCs bereitgestellt. Die Übermittlung aller anderen APCs, sowohl vom Kernelmodus als auch vom Benutzermodus, ist deaktiviert. Diese Einschränkung für die Bereitstellung von APCs bleibt bestehen, bis der Mutex freigegeben wird.

Das Dispatcherobjekt, auf das der Parameter Object verweist, muss sich im nicht seitenseitigen Systemspeicher befinden.

Wenn der parameter WaitModeUserModeist, kann der Kernelstapel während der Wartezeit vertauscht werden. Folglich darf ein Aufrufer niemals versuchen, Parameter im Stapel zu übergeben, wenn KeWaitForSingleObject mithilfe des UserMode-Arguments aufgerufen wird. Wenn Sie das Ereignis auf dem 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-Parameter "UserMode" oder "Alertable" WAHR ist, da KeWaitForSingleObject frühzeitig mit einem 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" sein und "Alertable " auf FALSE festgelegt werden.

Soweit möglich, sollte "Alertable " auf "FALSE" festgelegt werden und "WaitMode " auf "KernelMode" festgelegt werden, um die Treiberkomplexität zu verringern. Die Hauptausnahme hierfür ist, wenn die Wartezeit eine langfristige Wartezeit ist.

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

Ein Timeoutwert von Null ermöglicht das Testen einer Reihe von Wartezeitbedingungen und für die bedingte Leistung von 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, ist durch die Granularität der Systemuhr begrenzt. Weitere Informationen finden Sie unter Timer accuracy.

Ein Mutex kann rekursiv nur MINLONG-Zeiten 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 Timeout = NULL oder *Timeout != 0 ist, muss der Aufrufer jedoch bei IRQL <= APC_LEVEL und in einem nichtarbiträren Threadkontext ausgeführt werden. Wenn Timeout != NULL und *Timeout = 0, muss der Aufrufer unter IRQL <= DISPATCH_LEVEL ausgeführt werden.

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

Um eine bessere Leistung zu erzielen, verwenden Sie schnelle Mutexe oder geschützte Mutexe. Weitere Informationen finden Sie unter Alternativen zu Mutex-Objekten.

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

Anforderungen

Siehe auch

ExInitializeFastMutex

KeBugCheckEx

KeInitializeEvent

KeInitializeMutex

KeInitializeSemaphore

KeInitializeTimer

KeWaitForMultipleObjects