Funzione WaitForSingleObject (synchapi.h)

  • Articolo

Attende fino a quando l'oggetto specificato non si trova nello stato segnalato o l'intervallo di timeout trascorso.

Per immettere uno stato di attesa avvisabile, usare la funzione WaitForSingleObjectEx . Per attendere più oggetti, usare WaitForMultipleObjects.

Sintassi

DWORD WaitForSingleObject(
  [in] HANDLE hHandle,
  [in] DWORD  dwMilliseconds
);

Parametri

[in] hHandle

Handle per l'oggetto. Per un elenco dei tipi di oggetto i cui handle possono essere specificati, vedere la sezione Osservazioni seguente.

Se questo handle viene chiuso mentre l'attesa è ancora in sospeso, il comportamento della funzione non è definito.

L'handle deve avere il diritto di accesso SYNC . Per altre informazioni, vedere Diritti di accesso standard.

[in] dwMilliseconds

Intervallo di timeout, in millisecondi. Se viene specificato un valore diverso da zero, la funzione attende fino a quando l'oggetto non viene segnalato o l'intervallo trascorso. Se dwMilliseconds è zero, la funzione non immette uno stato di attesa se l'oggetto non viene segnalato; restituisce sempre immediatamente. Se dwMilliseconds è INFINITE, la funzione restituirà solo quando l'oggetto viene segnalato.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 e Windows Server 2008 R2: Il valore dwMilliseconds include tempo trascorso in stati di bassa potenza. Ad esempio, il timeout mantiene il conteggio mentre il computer è inattivo.

Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 e Windows Server 2016: il valore dwMilliseconds non include tempo trascorso in bassa potenza Stati. Ad esempio, il timeout non mantiene il conteggio mentre il computer è inattivo.

Valore restituito

Se la funzione ha esito positivo, il valore restituito indica l'evento che ha causato la restituzione della funzione. Può essere uno dei valori seguenti.

Codice/valore restituito Descrizione
WAIT_ABANDONED
0x00000080L
 L'oggetto specificato è un oggetto mutex che non è stato rilasciato dal thread che appartiene all'oggetto mutex prima della chiusura del thread proprietario. La proprietà dell'oggetto mutex viene concessa al thread chiamante e lo stato mutex è impostato su nonsignaled.

Se il mutex proteggeva le informazioni sullo stato persistenti, è necessario controllarlo per la coerenza.
WAIT_OBJECT_0
0x00000000L
 Lo stato dell'oggetto specificato viene segnalato.
WAIT_TIMEOUT
0x00000102L
 Intervallo di timeout trascorso e lo stato dell'oggetto non è assegnato.
WAIT_FAILED
(DWORD)0xFFFFFFFF
 La funzione non è riuscita. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

La funzione WaitForSingleObject controlla lo stato corrente dell'oggetto specificato. Se lo stato dell'oggetto non è firmato, il thread chiamante entra nello stato di attesa fino a quando l'oggetto non viene segnalato o l'intervallo di timeout trascorso.

La funzione modifica lo stato di alcuni tipi di oggetti di sincronizzazione. La modifica si verifica solo per l'oggetto il cui stato segnalato ha causato la restituzione della funzione. Ad esempio, il conteggio di un oggetto semaforo è ridotto di uno.

La funzione WaitForSingleObject può attendere gli oggetti seguenti:

  • Notifica di modifica
  • Input della console
  • Evento
  • Notifica delle risorse di memoria
  • Mutex
  • Processo
  • Semaphore
  • Thread
  • Timer attendebile
Prestare attenzione quando si chiamano le funzioni di attesa e il codice che crea direttamente o indirettamente finestre. Se un thread crea finestre, deve elaborare i messaggi. Le trasmissioni dei messaggi vengono inviate a tutte le finestre del sistema. Un thread che usa una funzione di attesa senza intervallo di timeout può causare il deadlock del sistema. Due esempi di codice che creano indirettamente finestre sono DDE e la funzione CoInitialize . Pertanto, se si dispone di un thread che crea finestre, usare MsgWaitForMultipleObjects o MsgWaitForMultipleObjectsEx, anziché WaitForSingleObject.

Esempio

Per un esempio, vedere Uso di oggetti Mutex.

Requisiti

Requisito Valore
Client minimo supportato Windows XP [app desktop | App UWP]
Server minimo supportato Windows Server 2003 [app desktop | App UWP]
Piattaforma di destinazione Windows
Intestazione synchapi.h (includere Windows.h in Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Libreria Kernel32.lib
DLL Kernel32.dll

Vedere anche

Funzioni di sincronizzazione

Funzioni di attesa