Funzione ZwWaitForSingleObject (ntifs.h)

Articolo
12/21/2024

La routine ZwWaitForSingleObject attende fino a quando l'oggetto specificato non raggiunge lo 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 il tempo assoluto o relativo 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 assoluta 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	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 utente APC 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".

Osservazioni

ZwWaitForSingleObject attende fino a quando l'oggetto specificato non raggiunge lo 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 di timeout, l'attesa non verrà soddisfatta fino a quando l'oggetto non raggiunge lo 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 timeout esplicito valore pari a zero, non verrà eseguita alcuna attesa se l'attesa non può essere soddisfatta immediatamente. Un timeout valore 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. 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 chiusura. Un thread viene reso automaticamente 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 non documentata in modalità kernel usata per avvisare i thread.
L'origine dell'avviso è un APC in modalità utente.

Nel primo di questi due casi, l'attesa del thread è soddisfatta con lo stato di completamento di STATUS_ALERTED. Nel secondo caso, è soddisfatto di uno 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 viene avvisato. Al termine dell'esecuzione dell'APC, l'attesa del thread riprende. Un thread non viene mai avvisato, né viene interrotta l'attesa, 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) l'IRQL è minore di APC_LEVEL, (2) non è in corso alcun kernel APC e (3) il thread non si trova 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 ZwWaitForSingleObject restituisce con STATUS_SUCCESS e il thread contiene effettivamente il mutex, vengono recapitati 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.

È 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 avvisabile è impostato su FALSE.

Per altre informazioni, vedere I thread in attesa ricevono avvisi e APC?

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 timeout parametro 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 di ZwWaitForSingleObject viene eseguita in modalità utente, è necessario usare il nome "NtWaitForSingleObject" anziché "ZwWaitForSingleObject".

Per le chiamate da driver in modalità kernel, le NtXxx e ZwXxx versioni di una routine di Windows Native System Services 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.

Fabbisogno

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	HwStorPortProhibitedDDIs(storport), SpNoWait(storport)