Funzione WaitForMultipleObjects (synchapi.h)
Attende che uno o tutti gli oggetti specificati si trovino nello stato segnalato o che scade 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
[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 viene 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 fino a quando gli oggetti specificati non vengono segnalate o trascorso l'intervallo. 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 vengono segnalato gli oggetti specificati.
Windows 8 e versioni successive, Windows Server 2012 e versioni successive: Il valore dwMilliseconds non include il tempo impiegato in stati a basso consumo. 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'lpHandles indice di matrice dell'oggetto che ha soddisfatto l'attesa. Se più di un oggetto è stato 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 protegge le informazioni sullo stato persistente, è consigliabile verificarne la coerenza. |
|
L'intervallo di timeout trascorso e le condizioni specificate dal parametro bWaitAll non vengono soddisfatte. |
|
La funzione non è riuscita. Per ottenere informazioni estese sull'errore, chiamare GetLastError. |
Osservazioni
La funzione waitForMultipleObjects
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 non viene segnalato uno degli oggetti. Se vengono segnalate 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 viene eseguita 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, utilizzare uno dei metodi seguenti:
- Creare un thread per attendere MAXIMUM_WAIT_OBJECTS handle, 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 attendere su 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
- Semaforo
- Filo
- Timer waitable
Esempi
Per un esempio, vedere In attesa di più oggetti.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows XP [app desktop | App UWP] |
| server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| piattaforma di destinazione | Finestre |
| intestazione |
synchapi.h (include Windows.h) |
| libreria |
Kernel32.lib |
| dll | Kernel32.dll |