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 cui il chiamante fornisce l'archiviazione. L'oggetto dispatcher deve risiedere nella memoria di sistema non di paging. Per altre informazioni, vedere 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 all'ora di sistema.
Se timeout = 0, la routine viene restituita senza attendere. Se il chiamante fornisce un puntatore NULL, la routine attende a tempo indeterminato fino a quando l'oggetto dispatcher non viene impostato sullo stato segnalato. Per altre informazioni, vedere la sezione Osservazioni seguente.
Valore restituito
KeWaitForSingleObject può restituire uno dei seguenti elementi.
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. |
Osservazioni
Lo stato corrente del 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 di conseguenza interrotto. Per altre informazioni, vedere 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 è uguale a quello di tutti gli altri oggetti dispatcher durante l'attesa. Tuttavia, dopo KeWaitForSingleObject restituisce con STATUS_SUCCESS e il thread contiene effettivamente il mutex, vengono recapitate solo API speciali in modalità kernel. Il recapito di tutte le altre API, 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 di paging.
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 presto 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 avvisabile deve essere impostata su FALSE.
Laddove possibile, è consigliabile impostare Alertable su FALSE e WaitMode deve essere impostato su KernelModeper ridurre la complessità dei 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 non viene segnalato il Object.
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 soddisfatta immediatamente, 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 è limitata 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 Timeout = NULL o Timeout != 0, il chiamante deve essere in esecuzione in IRQL <= APC_LEVEL e in un contesto di thread non arbitro. Se Timeout != NULL e Timeout = 0, il chiamante deve essere in esecuzione in IRQL <= DISPATCH_LEVEL.
KeWaitForMutexObject è una macro che esegue la conversione in KeWaitForSingleObject, che può essere invece usata.
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.