Funzione KeWaitForMultipleObjects (wdm.h)

Articolo
08/08/2023

La routine KeWaitForMultipleObjects inserisce il thread corrente in uno stato di attesa attivabile o nonlerabile fino a quando uno o tutti gli oggetti dispatcher vengono impostati su uno stato segnalato o (facoltativamente) fino al timeout di attesa.

Sintassi

NTSTATUS
KeWaitForMultipleObjects (
    ULONG Count,
    PVOID Object[],
    WaitType,
    KWAIT_REASON WaitReason,
    KPROCESSOR_MODE WaitMode,
    BOOLEAN Alertable,
    PLARGE_INTEGER Timeout,
    PKWAIT_BLOCK WaitBlockArray
    );

Parametri

[in] Count

Numero di oggetti da attendere. Questo parametro specifica il numero di elementi nella matrice a cui punta il parametro Object .

[in] Object

Puntatore a una matrice di puntatori a oggetti dispatcher (eventi, mutex, semafori, thread e timer) per cui il chiamante fornisce l'archiviazione. Sia la matrice del puntatore che gli oggetti dispatcher devono risiedere nella memoria del sistema non a pagina. Per altre informazioni, vedere la sezione Osservazioni.

[in] WaitType

Tipo di operazione di attesa da eseguire. Specificare WaitAll, che indica che tutti gli oggetti specificati devono ottenere uno stato segnalato prima che venga soddisfatta l'attesa; o WaitAny, che indica che uno degli oggetti deve ottenere uno stato segnalato prima che l'attesa venga soddisfatta.

[in] WaitReason

Motivo dell'attesa. I driver devono impostare questo valore su Executive o, se il driver sta eseguendo per conto di un utente ed è in esecuzione nel contesto di un thread utente, su UserRequest.

[in] WaitMode

Se il chiamante attende in KernelMode o UserMode. I driver intermedi e di livello più basso devono specificare KernelMode. Se il set di oggetti in attesa include un mutex, il chiamante deve specificare KernelMode.

[in] Alertable

Valore booleano che indica se il thread può essere avvisato mentre si trova nello stato di attesa.

[in, optional] Timeout

Puntatore a un valore di timeout che specifica il tempo assoluto o relativo, in 100-nanosecondi, in cui deve essere completata l'attesa.

Un valore positivo specifica un tempo assoluto, 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 all'ora di sistema.

Se *Timeout = 0, la routine restituisce senza attendere. Se il chiamante fornisce un puntatore NULL , la routine attende in modo indefinito fino a quando uno o tutti gli oggetti dispatcher vengono impostati sullo stato segnalato. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[out, optional] WaitBlockArray

Puntatore a una matrice di KWAIT_BLOCK allocata dal chiamante. Se Count<= THREAD_WAIT_OBJECTS, WaitBlockArray può essere NULL. In caso contrario, questo parametro deve puntare a un buffer di memoria di dimensioniof(KWAIT_BLOCK) * Conteggio byte. La routine usa questo buffer per il mantenimento dei record durante l'esecuzione dell'operazione di attesa. Il buffer WaitBlockArray deve risiedere nella memoria di sistema non in pagina. Per altre informazioni, vedere la sezione Osservazioni.

Valore restituito

KeWaitForMultipleObjects può restituire uno dei seguenti elementi:

Codice restituito	Descrizione
STATUS_SUCCESS	Il chiamante specificato WaitAll per il parametro WaitType e tutti gli oggetti dispatcher nella matrice Object sono stati impostati sullo stato segnalato.
STATUS_ALERTED	L'attesa è stata interrotta per inviare un avviso al thread chiamante.
STATUS_USER_APC	L'attesa è stata interrotta per recapitare una chiamata asincrona dell'utente al thread chiamante.
STATUS_TIMEOUT	Si è verificato un timeout prima che il set specificato di condizioni di attesa sia stato soddisfatto. Questo valore può essere restituito quando viene specificato un valore di timeout esplicito pari a zero, ma non è possibile soddisfare immediatamente il set specificato di condizioni di attesa.
STATUS_WAIT_0 tramite STATUS_WAIT_63	Il chiamante specificato WaitAny for WaitType e uno degli oggetti dispatcher nella matrice Object è 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 che è stato abbandonato. I sei bit inferiori del valore restituito codificano l'indice in base zero del mutex nella matrice Object .

Si noti che la macro NT_SUCCESS riconosce tutti questi valori di stato come valori "riuscita".

Commenti

Ogni oggetto thread ha una matrice predefinita di blocchi di attesa che possono essere usati per attendere che diversi oggetti vengano impostati simultaneamente. Se possibile, la matrice predefinita di blocchi di attesa deve essere usata in un'operazione di attesa multipla perché non è necessario allocare e deallocare in un secondo momento l'archiviazione a blocchi di attesa aggiuntivi. Tuttavia, se il numero di oggetti che devono essere aspettati contemporaneamente è maggiore del numero di blocchi di attesa predefiniti, usare il parametro WaitBlockArray per specificare un set alternativo di blocchi di attesa da usare nell'operazione di attesa. I driver devono allocare solo un buffer di memoria sufficientemente grande per WaitBlockArray. Il buffer non deve essere inizializzato; tuttavia, deve essere allocata dalla memoria di sistema non a pagina. Se il parametro WaitMode è UserMode, il buffer WaitBlockArray non deve essere allocato nello stack locale perché lo stack potrebbe essere scambiato in memoria insufficiente. I driver possono trattare questo buffer come una struttura opaca e possono liberarlo dopo il ritorno della routine. Se Count> MAXIMUM_WAIT_OBJECTS o se WaitBlockArray è NULL e Count> THREAD_WAIT_OBJECTS, il sistema genera bug Check 0xC (MAXIMUM_WAIT_OBJECTS_EXCEEDED).

Lo stato corrente per ogni oggetto specificato viene esaminato per determinare se l'attesa può essere soddisfatta immediatamente. Se gli effetti collaterali necessari vengono eseguiti sugli oggetti, viene restituito un valore appropriato.

Se l'attesa non può essere soddisfatta immediatamente e non è stato specificato alcun valore di timeout o un valore di timeout diverso da zero, il thread corrente viene inserito in uno stato di attesa e viene selezionato un nuovo thread per l'esecuzione nel processore corrente. Se non viene fornito alcun timeout , il thread chiamante rimarrà in uno stato di attesa fino a quando non vengono soddisfatte le condizioni specificate da Object e WaitType .

Se viene specificato timeout , l'attesa verrà soddisfatta automaticamente se nessuna delle condizioni di attesa specificate viene soddisfatta quando scade l'intervallo specificato.

Un valore di timeout pari a zero consente di testare un set di condizioni di attesa, eseguendo in modo condizionale eventuali effetti collaterali se l'attesa può essere immediatamente soddisfatta, come nell'acquisizione di un mutex.

Gli intervalli di timeout vengono misurati rispetto all'orologio di sistema e l'accuratezza con cui il sistema operativo può rilevare la fine di un intervallo di timeout è limitato dalla granularità dell'orologio di sistema. Per altre informazioni, vedere Accuratezza timer.

Il parametro Alertable determina quando il thread può essere avvisato e il relativo stato di attesa di conseguenza interrotto. Per altre informazioni, vedere Attese e API.

La matrice puntata dal parametro Objects deve risiedere nella memoria di sistema non di pagina. In genere, un driver alloca l'archiviazione per la matrice Oggetti nello stack locale. La matrice Objects può essere allocata nello stack locale indipendentemente dal valore del parametro WaitMode .

Gli oggetti dispatcher puntati dagli elementi nella matrice Objects devono risiedere nella memoria di sistema non a pagina. Se il parametro WaitMode è UserMode, lo stack di kernel può essere scambiato durante l'attesa. Di conseguenza, un chiamante non deve mai tentare di passare parametri nello stack quando si chiama KeWaitForMultipleObjects con l'argomento UserMode . Se si alloca l'evento nello stack, è necessario impostare il parametro WaitMode su KernelMode.

Una considerazione speciale si applica quando il parametro Object passato a KeWaitForMultipleObjects è un mutex. Se l'oggetto dispatcher in attesa è un mutex, il recapito APC è uguale a quello di tutti gli altri oggetti dispatcher durante l'attesa. Tuttavia, dopo che KeWaitForMultipleObjects restituisce con STATUS_SUCCESS e il thread contiene effettivamente il mutex, vengono recapitate solo API in modalità kernel speciali. Il recapito di tutte le altre API, sia in modalità kernel che in modalità utente, è disabilitato. Questa restrizione sul recapito delle API persiste fino a quando non viene rilasciato il mutex.

È particolarmente importante controllare il valore restituito di KeWaitForMultipleObjects quando il parametro WaitMode è UserMode o Alertable è TRUE, perché KeWaitForMultipleObjects potrebbe restituire in anticipo uno stato di STATUS_USER_APC o STATUS_ALERTED.

Tutte le attese a lungo termine che possono essere interrotte da un utente devono essere WaitMode e Alertable devono essere impostate su FALSE.

Se possibile, l'opzione Alertable deve essere impostata su FALSE e WaitMode deve essere impostata su KernelMode, per ridurre la complessità del driver. L'eccezione principale è quando l'attesa è un'attesa a lungo termine.

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

I chiamanti di KeWaitForMultipleObjects possono essere eseguiti in IRQL <= DISPATCH_LEVEL. Tuttavia, se TimeoutNULL o *Timeout = != 0, il chiamante deve essere in esecuzione in IRQL <= APC_LEVEL e in un contesto di thread non arbiverso. Se Timeout != NULL e *Timeout = 0, il chiamante deve essere in esecuzione in IRQL <= DISPATCH_LEVEL.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows 2000.
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Vedere La sezione Osservazioni.
Regole di conformità DDI	HwStorPortProhibitedDDDIs(storport), IrpProcessingComplete(wdm), IrqlKeWaitForMultipleObjects(wdm), SpNoWait(storport)