Funzione ZwWaitForSingleObject (ntifs.h)

Articolo
07/11/2023

La routine ZwWaitForSingleObject attende fino a quando l'oggetto specificato non raggiunge uno stato Signaled. È anche possibile specificare un timeout facoltativo.

Sintassi

NTSYSAPI NTSTATUS ZwWaitForSingleObject(
  [in]           HANDLE         Handle,
  [in]           BOOLEAN        Alertable,
  [in, optional] PLARGE_INTEGER Timeout
);

Parametri

[in] Handle

Handle per l'oggetto .

[in] Alertable

Valore booleano che specifica se l'attesa è avvisabile.

[in, optional] Timeout

Puntatore facoltativo a un valore di timeout che specifica l'ora assoluta o relativa in cui deve essere completata l'attesa. Un valore negativo specifica un intervallo relativo all'ora corrente. Il valore deve essere espresso in unità di 100 nanosecondi. Le ore di scadenza assolute tengono traccia delle modifiche apportate all'ora di sistema. Le scadenze relative non sono interessate dalle modifiche all'ora di sistema.

Valore restituito

ZwWaitForSingleObject può restituire uno dei codici di stato seguenti:

Codice restituito	Descrizione
STATUS_ACCESS_DENIED	Il chiamante non dispone dei privilegi necessari per l'evento specificato dal parametro Handle .
STATUS_ALERTED	L'attesa è stata interrotta per recapitare un avviso al thread corrente.
STATUS_INVALID_HANDLE	Il parametro Handle fornito non è valido.
STATUS_SUCCESS	L'oggetto specificato ha soddisfatto l'attesa.
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 il parametro Timeout è impostato su zero.
STATUS_USER_APC	L'attesa è stata interrotta per recapitare un APC utente al thread corrente.

Si noti che la macro NT_SUCCESS riconosce i valori di stato STATUS_ALERTED, STATUS_SUCCESS, STATUS_TIMEOUT e STATUS_USER_APC come valori di stato "operazione riuscita".

Commenti

ZwWaitForSingleObject attende fino a quando l'oggetto specificato non raggiunge uno stato Signaled. È anche possibile specificare un timeout facoltativo. ZwWaitForSingleObject esamina lo stato corrente dell'oggetto specificato per determinare se l'attesa può essere soddisfatta immediatamente. In tal caso, vengono eseguite azioni. 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.

Se non viene specificato un parametro Timeout , l'attesa non verrà soddisfatta fino a quando l'oggetto non raggiungerà uno stato Signaled. Se viene specificato un parametro Timeout e l'oggetto non ha raggiunto uno stato Segnalato alla scadenza del timeout , l'attesa viene soddisfatta automaticamente. Se viene specificato un valore di timeout esplicito pari a zero, non verrà eseguita alcuna attesa se l'attesa non può essere soddisfatta immediatamente. Un valore di timeout pari a zero consente il test di un set di condizioni di attesa e per le prestazioni condizionali di eventuali effetti collaterali se l'attesa può essere soddisfatta immediatamente, come nell'acquisizione di un mutex. L'attesa può essere specificata anche come avvisabile.

Il parametro Alertable consente di specificare se il thread può essere avvisato e il relativo stato di attesa interrotto. Se il valore di questo parametro è FALSE, il thread non può essere avvisato. L'unica eccezione a questa regola è quella di un thread di terminazione. In determinate circostanze un thread di terminazione può essere avvisato mentre è in fase di avvolgimento. Un thread viene automaticamente reso avvisabile, ad esempio, quando viene terminato da un utente con CTRL+C.

Se il valore di Alertableè TRUE e una delle condizioni seguenti è presente, il thread verrà avvisato:

Se l'origine dell'avviso è una routine interna in modalità kernel non documentata usata per inviare avvisi ai thread.
L'origine dell'avviso è un APC in modalità utente.

Nel primo di questi due casi, l'attesa del thread viene soddisfatta con lo stato di completamento di STATUS_ALERTED. Nel secondo caso, viene soddisfatto dello stato di completamento di STATUS_USER_APC.

Il thread deve essere avvisabile per il recapito di un APC in modalità utente. Questo non è il caso per le API in modalità kernel. Un APC in modalità kernel può essere recapitato ed eseguito anche se il thread non è avvisato. Al termine dell'esecuzione dell'APC, l'attesa del thread riprende. Un thread non viene mai avvisato, né la sua attesa interrotta, dal recapito di un APC in modalità kernel.

Il recapito delle API in modalità kernel a un thread in attesa non dipende dal fatto che il thread possa essere avvisato. Se l'APC in modalità kernel è un APC in modalità kernel speciale, il servizio APC viene recapitato a condizione che irQL sia minore di APC_LEVEL. Se l'APC in modalità kernel è un APC in modalità kernel normale, il servizio APC viene recapitato a condizione che le tre condizioni seguenti contengano: (1) irQL è minore di APC_LEVEL, (2) nessun APC del kernel è in corso e (3) il thread non è in una sezione critica.

Se l'handle passato a ZwWaitForSingleObject fa riferimento a un mutex, il recapito APC corrisponde a quello di tutti gli altri oggetti dispatcher durante l'attesa. Tuttavia, una volta restituito ZwWaitForSingleObject 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.

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

Tutte le attese a lungo termine possono essere interrotte da un utente se il parametro Alertable è impostato su FALSE.

Per altre informazioni, vedere Ricevere avvisi e APC nei thread in attesa?

I chiamanti di ZwWaitForSingleObject devono essere in esecuzione in IRQL minore o uguale a DISPATCH_LEVEL. In genere, il chiamante deve essere in esecuzione in IRQL PASSIVE_LEVEL e in un contesto di thread non arbiverso. Una chiamata durante l'esecuzione in IRQL DISPATCH_LEVEL è valida se e solo se il chiamante specifica un parametro Timeout pari a zero. Ovvero, un driver non deve attendere un intervallo diverso da zero in IRQL uguale a DISPATCH_LEVEL.

Gli intervalli di timeout vengono misurati rispetto all'orologio di sistema e l'accuratezza della misurazione del timeout è limitata dalla granularità dell'orologio di sistema. Per altre informazioni, vedere Accuratezza timer.

Se la chiamata alla funzione ZwWaitForSingleObject viene eseguita in modalità utente, è necessario usare il nome "NtWaitForSingleObject" anziché "ZwWaitForSingleObject".

Per le chiamate da driver in modalità kernel, le versioni NtXxx e ZwXxx di una routine di Servizi di sistema nativi di Windows possono comportarsi in modo diverso nel modo in cui gestiscono e interpretano i parametri di input. Per altre informazioni sulla relazione tra le versioni NtXxx e ZwXxx di una routine, vedere Using Nt and Zw Versions of the Native System Services Routines .For more information about the Nt Xxx and Zw versions of the Native System Services Routines.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP
Piattaforma di destinazione	Universale
Intestazione	ntifs.h (include Ntifs.h, FltKernel.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDDIs(storport), SpNoWait(storport)