FsRtlCancellableWaitForMultipleObjects-Funktion (ntifs.h)

Artikel
12/21/2024

Die FsRtlCancellableWaitForMultipleObjects Routine führt einen abbruchbaren Wartevorgang (eine Wartezeit, die beendet werden kann) für ein oder mehrere Dispatcherobjekte aus.

Syntax

NTSTATUS FsRtlCancellableWaitForMultipleObjects(
  [in]           ULONG          Count,
  [in]           PVOID []       ObjectArray,
  [in]           WAIT_TYPE      WaitType,
  [in, optional] PLARGE_INTEGER Timeout,
  [in, optional] PKWAIT_BLOCK   WaitBlockArray,
  [in, optional] PIRP           Irp
);

Parameter

[in] Count

Die Anzahl der Objekte, auf die gewartet werden soll.

[in] ObjectArray

Ein Zeiger auf ein Array von Zeigern auf Dispatcherobjekte (Ereignisse, Mutexes, Semaphore, Threads und Timer), für die der Aufrufer den Speicher bereitstellt.

[in] WaitType

Entweder WaitAll, was angibt, dass alle angegebenen Objekte einen signalisierten Zustand erreichen müssen, bevor die Wartezeit erfüllt ist; oder WaitAny, was angibt, dass eines der Objekte einen signalisierten Zustand erreichen muss, bevor die Wartezeit erfüllt ist.

[in, optional] Timeout

Ein Zeiger auf einen optionalen Timeoutwert. Dieser Parameter gibt die absolute oder relative Zeit in 100 Nanosekundeneinheiten an, bei denen die Wartezeit abgeschlossen werden soll.

Wenn Timeout auf einen Nullwert zeigt (d. h. *Timeout == 0), wird die Routine ohne Warten zurückgegeben. Wenn der Aufrufer einen NULL-Zeiger bereitstellt (d. h. Timeout == NULL), wartet die Routine unbegrenzt, bis ein oder alle Dispatcherobjekte auf den signalierten Zustand festgelegt sind.

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- angegeben ist, wird die Wartezeit automatisch erfüllt, wenn keine der angegebenen Wartezeitbedingungen erfüllt ist, wenn das angegebene Intervall abläuft.

Ein Timeoutwert von Null (d. h. *Timeout == 0) ermöglicht es Ihnen, eine Reihe von Wartezeitbedingungen zu testen und alle zusätzlichen Aktionen bedingt auszuführen, wenn die Wartezeit sofort erfüllt werden kann, wie beim Erwerb eines Mutex.

[in, optional] WaitBlockArray

Wenn Count<= THREAD_WAIT_OBJECTS, kann WaitBlockArray- NULL sein. Andernfalls muss dieser Parameter auf einen Speicherpuffer von sizeof(KWAIT_BLOCK * Count) Bytes verweisen. Die Routine verwendet diesen Puffer für die Datensatzhaltung beim Ausführen des Wartevorgangs.

[in, optional] Irp

Ein Zeiger auf das ursprüngliche IRP, das dem vom Benutzer ausgestellten E/A-Vorgang entspricht und vom Benutzer abgebrochen werden kann. Der Aufrufer muss sicherstellen, dass das IRP für die Dauer dieser Routine gültig bleibt und dass der IRP keinen Abbruchroutinsatz aufweisen darf (z. B. IoSetCancelRoutine nicht für das IRP aufgerufen worden sein darf). Beachten Sie, dass das IRP vom Aufrufer gehalten werden muss, es kann nicht an einen Treiber auf niedrigerer Ebene übergeben werden.

Rückgabewert

FsRtlCancellableWaitForMultipleObjects kann einen der folgenden Werte zurückgeben:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Der aufrufer, der WaitAll für den parameter WaitType und alle Dispatcherobjekte im ObjectArray Array auf den signalierten Zustand festgelegt wurde.
STATUS_TIMEOUT	Ein Timeout ist aufgetreten, bevor die angegebenen Wartebedingungen erfüllt wurden. Dieser Wert kann zurückgegeben werden, wenn der angegebene Satz von Wartebedingungen nicht sofort erfüllt werden kann, und Timeout- auf Null festgelegt ist.
STATUS_WAIT_0 bis STATUS_WAIT_63	Der aufrufer hat WaitAny für WaitType angegeben, und eines der Dispatcherobjekte im ObjectArray Array wurde auf den signalierten Zustand festgelegt. Die unteren sechs Bits des Rückgabewerts codieren den nullbasierten Index des Objekts, das die Wartezeit erfüllt hat.
STATUS_ABANDONED_WAIT_0 bis STATUS_ABANDONED_WAIT_63	Der Aufrufer hat versucht, auf einen Mutex zu warten, der abgebrochen wurde. Die unteren sechs Bits des Rückgabewerts codieren den nullbasierten Index des Mutex im ObjectArray Array.
STATUS_CANCELLED	Die Wartezeit wurde durch eine ausstehende Abbruchanforderung für das angegebene IRP unterbrochen. Beachten Sie, dass dieser Wert nur zurückgegeben wird, wenn ein gültiges IRP an FsRtlCancellableWaitForMultipleObjects übergeben wird und das IRP von CancelSynchronousIoabgebrochen wurde.
STATUS_THREAD_IS_TERMINATING	Die Wartezeit wurde unterbrochen, da der Thread von einer Anwendung oder dem Benutzer beendet wurde.

Der Rückgabewert gibt nur den Status der Wartezeit an. Falls zutreffend, sollte der tatsächliche Status der E/A-Anforderung direkt von einem anderen IRP abgerufen werden, das beim Verarbeiten des ursprünglichen Benutzermodus-IRP generiert wird.

Beachten Sie, dass das NT_SUCCESS Makro FALSCH ("Fehler") für die STATUS_CANCELLED und STATUS_THREAD_IS_TERMINATING Statuswerte und WAHR ("Erfolg") für alle anderen Statuswerte zurückgibt.

Bemerkungen

Die FsRtlCancellableWaitForMultipleObjects Routine führt einen abbruchbaren Wartevorgang für Dispatcherobjekte aus. Wenn der Thread vom Benutzer oder von der Anwendung beendet wird oder wenn CancelSynchronousIo eine Abbruchanforderung für einen Thread-IRP (synchrones IRP) veröffentlicht, der dem Thread zugeordnet ist, wird die Wartezeit abgebrochen.

Die FsRtlCancellableWaitForMultipleObjects Routine wurde für die Unterstützung der I/O Completion/Cancellation Guidelines beginnend mit Windows Vista entwickelt. Ziel dieser Richtlinien ist es, Benutzern (oder Anwendungen) das schnelle Beenden von Anwendungen zu ermöglichen. Dies wiederum erfordert, dass Anwendungen die Möglichkeit haben, Threads, die E/A sowie aktuelle E/A-Vorgänge ausführen, schnell zu beenden. Diese Routine bietet eine Möglichkeit, um Benutzerthreads zu blockieren (d. h. warten) im Kernel für E/A-Vervollständigung, Verteilerobjekte oder Synchronisierungsvariablen so zu blockieren, dass die Wartezeit sofort abgebrochen werden kann. Diese Routine ermöglicht auch, dass die Wartezeit des Threads beendet wird, wenn der Thread von einem Benutzer oder einer Anwendung beendet wird.

Beispielsweise muss ein Umleitungsmodul einen oder mehrere sekundäre IRPs erstellen, um einen Benutzermodus-IRP zu verarbeiten und synchron zu warten, bis die sekundären IRPs abgeschlossen sind. Eine Möglichkeit hierfür ist das Einrichten eines Ereignisses, das durch die Abschlussroutine des sekundären IRP signalisiert wird und dann darauf wartet, dass das Ereignis signalisiert wird. Um dann einen abbruchbaren Wartevorgang auszuführen, wird FsRtlCancellableWaitForMultipleObjects wird aufgerufen, das dem sekundären IRP zugeordnete Ereignis sowie das ursprüngliche Benutzermodus-IRP zu übergeben. Die Wartezeit des Threads, bis das Ereignis signalisiert wird, wird abgebrochen, wenn ein ausstehendes Beendigungsereignis auftritt oder das ursprüngliche Benutzermodus-IRP abgebrochen wird.

Beachten Sie, dass das Beenden der Wartezeit keinen E/A-Vorgang, der vom Anrufer ausgegeben wird, automatisch abbricht – der vom Anrufer separat behandelt werden muss.

Jedes Threadobjekt verfügt über ein integriertes Array von Warteblöcken, die verwendet werden können, um gleichzeitig auf mehrere Objekte zu warten. Wann immer möglich, sollte das integrierte Array von Warteblöcken in einem Wait-Multiple-Vorgang verwendet werden, da kein zusätzlicher Warteblockspeicher zugewiesen und später zugeordnet werden muss. Wenn jedoch die Anzahl der Objekte, die gleichzeitig gewartet werden müssen, größer als die Anzahl der integrierten Warteblöcke ist, verwenden Sie den parameter WaitBlockArray, um einen alternativen Satz von Warteblöcken anzugeben, die im Wartevorgang verwendet werden sollen. Treiber müssen nur einen ausreichend großen Speicherpuffer für WaitBlockArray-zuweisen. Der Puffer muss nicht initialisiert werden, und die Treiber können sie als undurchsichtige Struktur behandeln. Der Puffer kann freigegeben werden, sobald die Routine zurückgegeben wird.

Wenn entweder Count größer als MAXIMUM_WAIT_OBJECTS oder wenn WaitBlockArray- NULL ist und die Anzahl größer als THREAD_WAIT_OBJECTS ist, gibt das System Fehlerüberprüfung 0xC: MAXIMUM_WAIT_OBJECTS_EXCEEDED.

Eine besondere Berücksichtigung gilt, wenn der ObjectArray Parameter, der an FsRtlCancellableWaitForMultipleObjects übergeben wird, ein Mutex ist. Wenn das dispatcher-Objekt, auf das gewartet wird, ein Mutex ist, ist die APC-Zustellung identisch mit allen anderen Dispatcherobjekten während der Wartezeit. Sobald FsRtlCancellableWaitForMultipleObjects 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 vom Kernelmodus als auch vom Benutzermodus, ist deaktiviert. Diese Einschränkung für die Bereitstellung von APCs bleibt bestehen, bis der Mutex freigegeben wird.

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.

FsRtlCancellableWaitForMultipleObjects- muss bei IRQL-PASSIVE_LEVEL aufgerufen werden, wenn der optionale Irp Parameter auf ein gültiges IRP verweist. Wenn der Irp Parameter nicht verwendet wird, kann die Routine bei IRQL kleiner oder gleich APC_LEVEL aufgerufen werden. Normale Kernel-APCs können bei Bedarf vom Aufrufer deaktiviert werden, indem die KeEnterCriticalRegion oder FsRtlEnterFileSystem Routinen aufgerufen werden. Spezielle Kernel-APCs dürfen jedoch nicht deaktiviert werden.

FsRtlCancellableWaitForMultipleObjects wird auf Debugbuilds bestätigt, wenn die IRQL größer oder gleich APC_LEVEL ist und der Irp Parameter auf ein gültiges IRP verweist.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows Vista
Zielplattform-	Universal
Header-	ntifs.h (einschließlich Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	Siehe Abschnitt "Hinweise".
DDI-Complianceregeln	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm), SpNoWait(storport)