Funzione KeWaitForSingleObject (wdm.h)
La routine KeWaitForSingleObject inserisce il thread corrente in uno stato di attesa fino a quando l'oggetto dispatcher specificato non viene impostato su uno stato segnalato o (facoltativamente) fino al timeout dell'attesa.
Sintassi
NTSTATUS
KeWaitForSingleObject (
PVOID Object,
KWAIT_REASON WaitReason,
KPROCESSOR_MODE WaitMode,
BOOLEAN Alertable,
PLARGE_INTEGER Timeout
);
Parametri
[in] Object
Puntatore a un oggetto dispatcher inizializzato (evento, mutex, semaforo, thread o timer) per il quale il chiamante fornisce la risorsa di archiviazione. L'oggetto dispatcher deve risiedere nella memoria di sistema non di paging. Per altre informazioni, vedere la sezione Osservazioni.
[in] WaitReason
Specifica il motivo dell'attesa. Un driver deve impostare questo valore su Executive, a meno che non funzioni per conto di un utente ed è in esecuzione nel contesto di un thread utente, nel qual caso deve impostare questo valore su UserRequest.
[in] WaitMode
Specifica se il chiamante attende in KernelMode o UserMode. I driver di livello più basso e intermedio devono specificare KernelMode. Se l'oggetto specificato è un mutex, il chiamante deve specificare KernelMode.
[in] Alertable
Specifica un valore booleano true se l'attesa è avvisabile e FALSE in caso contrario.
[in, optional] Timeout
Puntatore a un valore di timeout che specifica il tempo assoluto o relativo, in unità di 100 nanosecondi, in cui l'attesa deve essere completata.
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 Timeout = 0, la routine restituisce senza attendere. Se il chiamante fornisce un puntatore NULL , la routine attende per un periodo illimitato fino a quando l'oggetto dispatcher non viene impostato sullo stato segnalato. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
Valore restituito
KeWaitForSingleObject può restituire una delle opzioni seguenti.
La macro NT_SUCCESS riconosce tutti questi valori di stato come valori di "esito positivo".
| Codice restituito | Descrizione |
|---|---|
| STATUS_SUCCESS | L'oggetto dispatcher specificato dal parametro Object ha soddisfatto l'attesa. |
| STATUS_ALERTED | L'attesa è stata interrotta per recapitare 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 l'oggetto sia stato impostato su uno stato segnalato. Questo valore può essere restituito quando non è possibile soddisfare immediatamente il set specificato di condizioni di attesa e Timeout è impostato su zero. |
Commenti
Lo stato corrente dell'oggetto specificato viene esaminato per determinare se l'attesa può essere soddisfatta immediatamente. In tal caso, gli effetti collaterali necessari vengono eseguiti sull'oggetto . In caso contrario, il thread corrente viene inserito in uno stato di attesa e viene selezionato un nuovo thread per l'esecuzione nel processore corrente.
Il parametro Alertable determina quando il thread può essere avvisato e il relativo stato di attesa interrotto. Per altre informazioni, vedere Waits and APCs.For additional information, see Waits and APCs.
Una considerazione speciale si applica quando il parametro Object passato a KeWaitForSingleObject è 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 KeWaitForSingleObject 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.
L'oggetto dispatcher a cui punta il parametro Object deve risiedere nella memoria di sistema non in pagine.
Se il parametro WaitMode è UserMode, lo stack del kernel può essere scambiato durante l'attesa. Di conseguenza, un chiamante non deve mai tentare di passare parametri nello stack quando si chiama KeWaitForSingleObject usando l'argomento UserMode . Se si alloca l'evento nello stack, è necessario impostare il parametro WaitMode su KernelMode.
È particolarmente importante controllare il valore restituito di KeWaitForSingleObject quando il parametro WaitMode è UserMode o Alertable è TRUE, perché KeWaitForSingleObject 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 attese UserMode e Alertable deve essere impostato su FALSE.
Dove possibile, Alertable deve essere impostato su FALSE e WaitMode deve essere impostato su KernelMode, per ridurre la complessità del driver. L'eccezione principale è quando l'attesa è un'attesa a lungo termine.
Se viene fornito un puntatore NULL per Timeout, il thread chiamante rimane in uno stato di attesa fino a quando l'oggetto non viene segnalato.
Un valore di timeout pari a zero consente il test di un set di condizioni di attesa e per le prestazioni condizionali di qualsiasi effetto collaterale se l'attesa può essere immediatamente soddisfatta, come nell'acquisizione di un mutex.
Gli intervalli di timeout vengono misurati in relazione 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.
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.
I chiamanti di KeWaitForSingleObject devono essere in esecuzione 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.
KeWaitForMutexObject è una macro che converte in KeWaitForSingleObject, che può essere utilizzata.
Per prestazioni migliori, usare mutex veloci o mutex sorvegliati. Per altre informazioni, vedere Alternative agli oggetti Mutex.
Per altre informazioni sugli oggetti mutex, vedere Oggetti Mutex.