Funzione MsgWaitForMultipleObjects (winuser.h)
Attende che uno o tutti gli oggetti specificati si trovino nello stato segnalato o che sia trascorso l'intervallo di timeout. Gli oggetti possono includere oggetti evento di input, specificati usando il parametro dwWakeMask .
Per immettere uno stato di attesa avvisabile, usare la funzione MsgWaitForMultipleObjectsEx .
Sintassi
DWORD MsgWaitForMultipleObjects(
[in] DWORD nCount,
[in] const HANDLE *pHandles,
[in] BOOL fWaitAll,
[in] DWORD dwMilliseconds,
[in] DWORD dwWakeMask
);
Parametri
[in] nCount
Numero di handle di oggetto nella matrice a cui punta pHandles. Il numero massimo di handle di oggetti è MAXIMUM_WAIT_OBJECTS meno uno. Se questo parametro ha il valore zero, la funzione attende solo un evento di input.
[in] pHandles
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 di 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] fWaitAll
Se questo parametro è TRUE, la funzione restituisce quando gli stati di tutti gli oggetti nella matrice pHandles sono stati impostati su segnalato e viene ricevuto un evento di input. Se questo parametro è FALSE, la funzione restituisce quando lo stato di uno degli oggetti è impostato su segnalato o viene ricevuto un evento di input. In questo 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 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.
[in] dwWakeMask
Tipi di input per i quali verrà aggiunto un handle dell'oggetto evento di input alla matrice di handle di oggetto. Questo parametro può essere qualsiasi combinazione dei valori elencati nel parametro GetQueueStatusflags .
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 della matrice pHandles dell'oggetto che ha soddisfatto l'attesa. |
|
Il nuovo input del tipo specificato nel parametro dwWakeMask è disponibile nella coda di input del thread. Funzioni come PeekMessage, GetMessage e WaitMessage contrassegnano i messaggi nella coda come messaggi precedenti. Pertanto, dopo aver chiamato una di queste funzioni, una chiamata successiva a MsgWaitForMultipleObjects non restituirà finché non arriva un nuovo input del tipo specificato.
Questo valore viene restituito anche all'occorrenza di un evento di sistema che richiede l'azione del thread, ad esempio l'attivazione in primo piano. Pertanto, MsgWaitForMultipleObjects può restituire anche se non è disponibile alcun input appropriato e anche se dwWakeMask è impostato su 0. In questo caso, chiamare GetMessage o PeekMessage per elaborare l'evento di sistema prima di provare di nuovo la chiamata a MsgWaitForMultipleObjects . |
|
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 della matrice pHandles 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 il mutex proteggeva le informazioni sullo stato persistente, è necessario verificarne la coerenza. |
|
L'intervallo di timeout trascorso e le condizioni specificate dai parametri bWaitAll e dwWakeMask non sono state soddisfatte. |
|
La funzione non è riuscita. Per informazioni dettagliate sull'errore, chiamare GetLastError. |
Commenti
La funzione MsgWaitForMultipleObjects 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, la funzione non modifica gli stati degli oggetti specificati fino a quando 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é anche gli stati degli altri oggetti non sono stati impostati su segnalato. Nel frattempo, un altro thread può ottenere la proprietà del mutex, impostandone lo stato su non firmato.
Quando bWaitAll è TRUE, l'attesa della funzione viene completata solo quando gli stati di tutti gli oggetti sono stati impostati su segnalato e viene ricevuto un evento di input. Pertanto, l'impostazione di bWaitAll su TRUE impedisce l'elaborazione dell'input fino a quando lo stato di tutti gli oggetti nella matrice pHandles è stato impostato su segnalato. Per questo motivo, se si imposta bWaitAll su TRUE, è consigliabile usare un valore di timeout breve in dwMilliseconds. Se si dispone di un thread che crea finestre in attesa di tutti gli oggetti nella matrice pHandles , inclusi gli eventi di input specificati da dwWakeMask, senza un intervallo di timeout, il sistema verrà deadlock. Ciò è dovuto al fatto che i thread che creano finestre devono elaborare i messaggi. DDE invia un messaggio a tutte le finestre del sistema. Pertanto, se un thread crea finestre, non impostare il parametro bWaitAll su TRUE nelle chiamate a MsgWaitForMultipleObjects effettuate da tale thread.
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.
MsgWaitForMultipleObjects non restituisce se è presente un input non letto del tipo specificato nella coda dei messaggi dopo che il thread ha chiamato una funzione per controllare la coda. Ciò è dovuto al fatto che le funzioni come PeekMessage, GetMessage, GetQueueStatus e WaitMessage controllano la coda e quindi modificano le informazioni sullo stato per la coda in modo che l'input non venga più considerato nuovo. Una chiamata successiva a MsgWaitForMultipleObjects non restituirà fino all'arrivo di un nuovo input del tipo specificato. L'input non letto esistente (ricevuto prima dell'ultima volta che il thread ha controllato la coda) viene ignorato.
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.
La funzione MsgWaitForMultipleObjects può specificare handle di uno dei tipi di oggetto seguenti nella matrice pHandles :
- Notifica di modifica
- Input della console
- Evento
- Notifica delle risorse di memoria
- Mutex
- Processo
- Semaphore
- Thread
- Timer waitable
Requisiti
| Client minimo supportato | Windows XP [solo app desktop] |
| Server minimo supportato | Windows Server 2003 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | winuser.h (include Windows.h) |
| Libreria | User32.lib |
| DLL | User32.dll |
Vedi anche
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per