Funzione WaitForMultipleObjects (synchapi.h)
Attende che uno o tutti gli oggetti specificati si trovino nello stato segnalato o che sia trascorso l'intervallo di timeout.
Per immettere uno stato di attesa avvisabile, usare la funzione WaitForMultipleObjectsEx .
Sintassi
DWORD WaitForMultipleObjects(
[in] DWORD nCount,
[in] const HANDLE *lpHandles,
[in] BOOL bWaitAll,
[in] DWORD dwMilliseconds
);
Parametri
[in] nCount
Numero di handle di oggetto nella matrice a cui punta lpHandles. Il numero massimo di handle di oggetti è MAXIMUM_WAIT_OBJECTS. Questo parametro non può essere zero.
[in] lpHandles
Matrice di handle di oggetti. Per un elenco dei tipi di oggetto i cui handle possono essere specificati, vedere la sezione Osservazioni seguente. La matrice può contenere handle per oggetti di tipi diversi. Potrebbe non contenere più copie dello stesso handle.
Se uno di questi handle viene chiuso mentre l'attesa è ancora in sospeso, il comportamento della funzione non è definito.
Gli handle devono avere il diritto di accesso SYNCHRONIZE . Per altre informazioni, vedere Diritti di accesso standard.
[in] bWaitAll
Se questo parametro è TRUE, la funzione restituisce quando viene segnalato lo stato di tutti gli oggetti nella matrice lpHandles . Se FALSE, la funzione restituisce quando lo stato di uno degli oggetti è impostato su segnalato. Nel secondo caso, il valore restituito indica l'oggetto il cui stato ha causato la restituzione della funzione.
[in] dwMilliseconds
Intervallo di timeout, espresso in millisecondi. Se viene specificato un valore diverso da zero, la funzione attende finché gli oggetti specificati non vengono segnalate o l'intervallo scade. Se dwMilliseconds è zero, la funzione non immette uno stato di attesa se gli oggetti specificati non vengono segnalato; restituisce sempre immediatamente. Se dwMilliseconds è INFINITE, la funzione restituirà solo quando gli oggetti specificati vengono indicati.
Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 e Windows Server 2008 R2: Il valore dwMilliseconds include il tempo impiegato in stati a basso consumo. Ad esempio, il timeout continua a contare mentre il computer è in sospensione.
Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 e Windows Server 2016: il valore dwMilliseconds non include il tempo dedicato a basso consumo Stati. Ad esempio, il timeout non continua a contare mentre il computer è in stato di sospensione.
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. Si noti che WAIT_OBJECT_0 è definito come 0 e WAIT_ABANDONED_0 è definito come 0x00000080L.
| Codice/valore restituito | Descrizione |
|---|---|
|
Se bWaitAll è TRUE, un valore restituito all'interno dell'intervallo specificato indica che lo stato di tutti gli oggetti specificati viene segnalato.
Se bWaitAll è FALSE, il valore restituito meno WAIT_OBJECT_0 indica l'indice di matrice lpHandles dell'oggetto che ha soddisfatto l'attesa. Se più di un oggetto viene segnalato durante la chiamata, si tratta dell'indice di matrice dell'oggetto segnalato con il valore di indice più piccolo di tutti gli oggetti segnalato. |
|
Se bWaitAll è TRUE, un valore restituito all'interno dell'intervallo specificato indica che lo stato di tutti gli oggetti specificati viene segnalato e almeno uno degli oggetti è un oggetto mutex abbandonato.
Se bWaitAll è FALSE, il valore restituito meno WAIT_ABANDONED_0 indica l'indice di matrice lpHandles di un oggetto mutex abbandonato che ha soddisfatto l'attesa. La proprietà dell'oggetto mutex viene concessa al thread chiamante e il mutex è impostato su non firmato. Se un mutex proteggeva le informazioni sullo stato persistenti, è necessario verificarne la coerenza. |
|
L'intervallo di timeout trascorso e le condizioni specificate dal parametro bWaitAll non vengono soddisfatte. |
|
La funzione non è riuscita. Per informazioni dettagliate sull'errore, chiamare GetLastError. |
Commenti
La funzione WaitForMultipleObjects determina se i criteri di attesa sono stati soddisfatti. Se i criteri non sono stati soddisfatti, il thread chiamante entra nello stato di attesa fino a quando non sono state soddisfatte le condizioni dei criteri di attesa o l'intervallo di timeout scade.
Quando bWaitAll è TRUE, l'operazione di attesa della funzione viene completata solo quando gli stati di tutti gli oggetti sono stati impostati su segnalato. La funzione non modifica gli stati degli oggetti specificati finché gli stati di tutti gli oggetti non sono stati impostati su segnalato. Ad esempio, è possibile segnalare un mutex, ma il thread non ottiene la proprietà finché gli stati degli altri oggetti non vengono impostati anche su segnalato. Nel frattempo, un altro thread può ottenere la proprietà del mutex, impostandone lo stato su non firmato.
Quando bWaitAll è FALSE, questa funzione controlla gli handle nella matrice in ordine a partire dall'indice 0, fino a quando uno degli oggetti non viene segnalato. Se vengono rilevati più oggetti, la funzione restituisce l'indice del primo handle nella matrice il cui oggetto è stato segnalato.
La funzione modifica lo stato di alcuni tipi di oggetti di sincronizzazione. La modifica si verifica solo per l'oggetto o gli oggetti il cui stato segnalato ha causato la restituzione della funzione. Ad esempio, il conteggio di un oggetto semaforo viene ridotto di uno. Per altre informazioni, vedere la documentazione relativa ai singoli oggetti di sincronizzazione.
Per attendere più di MAXIMUM_WAIT_OBJECTS handle, usare uno dei metodi seguenti:
- Creare un thread per attendere gli handle di MAXIMUM_WAIT_OBJECTS , quindi attendere il thread più gli altri handle. Usare questa tecnica per suddividere gli handle in gruppi di MAXIMUM_WAIT_OBJECTS.
- Chiamare RegisterWaitForSingleObject o SetThreadpoolWait per attendere ogni handle. Il pool di thread attende in modo efficiente sugli handle e assegna un thread di lavoro dopo che l'oggetto viene segnalato o l'intervallo di timeout scade.
- Notifica di modifica
- Input della console
- Evento
- Notifica delle risorse di memoria
- Mutex
- Processo
- Semaphore
- Thread
- Timer waitable
Esempio
Per un esempio, vedere In attesa di più oggetti.
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 (include Windows.h) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |