Funzione FsRtlCancellableWaitForMultipleObjects (ntifs.h)

Articolo
08/07/2023

La routine FsRtlCancellableWaitForMultipleObjects esegue un'operazione di attesa annullabile (un'attesa che può essere terminata) su uno o più oggetti dispatcher.

Sintassi

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
);

Parametri

[in] Count

Numero di oggetti da attendere.

[in] ObjectArray

Puntatore a una matrice di puntatori a oggetti dispatcher (eventi, mutex, semafori, thread e timer) per cui il chiamante fornisce la risorsa di archiviazione.

[in] WaitType

WaitAll, che indica che tutti gli oggetti specificati devono raggiungere uno stato segnalato prima che l'attesa venga soddisfatta; o WaitAny, che indica che uno degli oggetti deve raggiungere uno stato segnalato prima che l'attesa venga soddisfatta.

[in, optional] Timeout

Puntatore a un valore di timeout facoltativo. Questo parametro specifica il tempo assoluto o relativo, in unità di 100 nanosecondi, in cui l'attesa deve essere completata.

Se Timeout punta a un valore zero (ovvero *Timeout == 0), la routine restituisce senza attendere. Se il chiamante fornisce un puntatore NULL (ovvero Timeout == NULL), la routine attende per un periodo illimitato fino a quando uno o tutti gli oggetti dispatcher non vengono impostati sullo stato segnalato.

Un valore positivo specifica un'ora assoluta, rispetto al 1° gennaio 1601. Un valore negativo specifica un intervallo relativo all'ora corrente. I tempi di scadenza assoluti tengono traccia delle modifiche apportate all'ora di sistema; le ore di scadenza relative non sono interessate dalle modifiche apportate all'ora di sistema.

Se si specifica Timeout , l'attesa verrà soddisfatta automaticamente se nessuna delle condizioni di attesa specificate viene soddisfatta alla scadenza dell'intervallo specificato.

Un valore di timeout pari a zero (ovvero *Timeout == 0) consente di testare un set di condizioni di attesa e di eseguire in modo condizionale eventuali azioni aggiuntive se l'attesa può essere soddisfatta immediatamente, come nell'acquisizione di un mutex.

[in, optional] WaitBlockArray

Se Count<= THREAD_WAIT_OBJECTS, WaitBlockArray può essere NULL. In caso contrario, questo parametro deve puntare a un buffer di memoria di sizeof(KWAIT_BLOCK * Count) byte. La routine usa questo buffer per mantenere i record durante l'esecuzione dell'operazione di attesa.

[in, optional] Irp

Puntatore all'IRP originale che corrisponde all'operazione di I/O rilasciata dall'utente e che può essere annullata dall'utente. Il chiamante deve assicurarsi che L'IRP rimanga valido per la durata di questa routine e che l'IRP non abbia un set di routine di annullamento( ad esempio, IoSetCancelRoutine non deve essere stato chiamato su IRP). Si noti che l'IRP deve essere mantenuto dal chiamante, non può essere passato a un driver di livello inferiore.

Valore restituito

FsRtlCancellableWaitForMultipleObjects può restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	Il chiamante ha specificato WaitAll per il parametro WaitType e tutti gli oggetti dispatcher nella matrice ObjectArray sono stati impostati sullo stato segnalato.
STATUS_TIMEOUT	Si è verificato un timeout prima che sia stato soddisfatto il set specificato di condizioni di attesa. Questo valore può essere restituito quando non è possibile soddisfare immediatamente il set specificato di condizioni di attesa e Timeout è impostato su zero.
STATUS_WAIT_0 tramite STATUS_WAIT_63	Il chiamante specificato WaitAny for WaitType e uno degli oggetti dispatcher nella matrice ObjectArray è stato impostato sullo stato segnalato. I sei bit inferiori del valore restituito codificano l'indice in base zero dell'oggetto che ha soddisfatto l'attesa.
STATUS_ABANDONED_WAIT_0 tramite STATUS_ABANDONED_WAIT_63	Il chiamante ha tentato di attendere un mutex abbandonato. I sei bit inferiori del valore restituito codificano l'indice in base zero del mutex nella matrice ObjectArray .
STATUS_CANCELLED	L'attesa è stata interrotta da una richiesta di annullamento in sospeso sul provider di risorse IRP specificato. Si noti che questo valore viene restituito solo se un IRP valido viene passato a FsRtlCancellableWaitForMultipleObjects e l'IRP è stato annullato da CancelSynchronousIo.
STATUS_THREAD_IS_TERMINATING	L'attesa è stata interrotta perché il thread è stato terminato da un'applicazione o dall'utente.

Il valore restituito indica solo lo stato dell'attesa. Se applicabile, lo stato effettivo della richiesta di I/O deve essere ottenuto direttamente da un altro IRP generato nel processo di gestione dell'IRP in modalità utente originale.

Si noti che la macro NT_SUCCESS restituisce FALSE ("errore") per i valori di stato STATUS_CANCELLED e STATUS_THREAD_IS_TERMINATING e TRUE ("operazione riuscita") per tutti gli altri valori di stato.

Commenti

La routine FsRtlCancellableWaitForMultipleObjects esegue un'operazione di attesa annullabile sugli oggetti dispatcher. Se il thread viene terminato dall'utente o dall'applicazione o se CancelSynchronousIo invia una richiesta di annullamento su un IRP (IRP sincrono) threaded associato al thread, l'attesa viene annullata.

La routine FsRtlCancellableWaitForMultipleObjects è stata progettata per supportare le linee guida per il completamento/annullamento di I/O a partire da Windows Vista. L'obiettivo di queste linee guida è consentire agli utenti (o alle applicazioni) di terminare rapidamente le applicazioni. A sua volta, richiede che le applicazioni abbiano la possibilità di terminare rapidamente i thread che eseguono operazioni di I/O e qualsiasi operazione di I/O corrente. Questa routine consente ai thread utente di bloccare (ovvero attendere) nel kernel per il completamento di I/O, oggetti dispatcher o variabili di sincronizzazione in modo da consentire l'annullamento dell'attesa. Questa routine consente inoltre di terminare l'attesa del thread se il thread viene terminato da un utente o da un'applicazione.

Ad esempio, un redirector potrebbe dover creare uno o più provider di integrazione secondari per elaborare un IRP in modalità utente e attendere in modo sincrono il completamento dei runtime di integrazione secondari. Un modo per eseguire questa operazione consiste nel configurare un evento che verrà segnalato dalla routine di completamento dell'IRP secondario e quindi attendere che l'evento venga segnalato. Quindi, per eseguire un'operazione di attesa annullabile, FsRtl DisabilitableWaitForMultipleObjects viene chiamato passando l'evento associato all'IRP secondario, nonché l'IRP in modalità utente originale. L'attesa del thread per la segnalazione dell'evento viene annullata se si verifica un evento di terminazione in sospeso o se l'IRP in modalità utente originale viene annullato.

Si noti che l'interruzione dell'attesa non annulla automaticamente tutte le operazioni di I/O rilasciate dal chiamante, che devono essere gestite separatamente dal chiamante.

Ogni oggetto thread ha una matrice predefinita di blocchi di attesa che possono essere usati per attendere più oggetti contemporaneamente. Quando possibile, la matrice predefinita di blocchi di attesa deve essere usata in un'operazione di attesa multipla perché non è necessario allocare e deallocare in seguito l'archiviazione dei blocchi di attesa aggiuntivi. Tuttavia, se il numero di oggetti da attendere simultaneamente è maggiore del numero di blocchi di attesa predefiniti, utilizzare il parametro WaitBlockArray per specificare un set alternativo di blocchi di attesa da utilizzare nell'operazione di attesa. I driver devono allocare solo un buffer di memoria sufficientemente grande per WaitBlockArray. Non è necessario inizializzare il buffer e i driver possono considerarlo come una struttura opaca. Il buffer può essere liberato una volta restituita la routine.

Se Count è maggiore di MAXIMUM_WAIT_OBJECTS o se WaitBlockArray è NULL e Count è maggiore di THREAD_WAIT_OBJECTS, il sistema genera bug Check 0xC: MAXIMUM_WAIT_OBJECTS_EXCEEDED.

Una considerazione speciale si applica quando il parametro ObjectArray passato a FsRtlCancellableWaitForMultipleObjects è un mutex. Se l'oggetto dispatcher in attesa è un mutex, il recapito APC corrisponde a quello di tutti gli altri oggetti dispatcher durante l'attesa. Tuttavia, dopo che FsRtlCancellableWaitForMultipleObjects restituisce con STATUS_SUCCESS e il thread contiene effettivamente il mutex, vengono recapitate solo API speciali in modalità kernel. Il recapito di tutti gli altri APN, sia in modalità kernel che in modalità utente, è disabilitato. Questa restrizione per il recapito delle API persiste fino al rilascio del mutex.

Un mutex può essere acquisito in modo ricorsivo solo volte MINLONG. Se questo limite viene superato, la routine genera un'eccezione STATUS_MUTANT_LIMIT_EXCEEDED.

FsRtlCancellableWaitForMultipleObjects deve essere chiamato in IRQL PASSIVE_LEVEL se il parametro Irp facoltativo punta a un IRP valido. Se il parametro Irp non viene usato, la routine può essere chiamata in IRQL minore o uguale a APC_LEVEL. Le API del kernel normali possono essere disabilitate dal chiamante, se necessario, chiamando le routine KeEnterCriticalRegion o FsRtlEnterFileSystem . Tuttavia, le API speciali del kernel non devono essere disabilitate.

FsRtlCancellableWaitForMultipleObjects eseguirà l'asserzione nelle build di debug se IRQL è maggiore o uguale a APC_LEVEL e il parametro Irp punta a un IRP valido.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista
Piattaforma di destinazione	Universale
Intestazione	ntifs.h (include Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Vedere la sezione Osservazioni.
Regole di conformità DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm), SpNoWait(storport)