Funzione WaitForMultipleObjectsEx (synchapi.h)

Attende che uno o tutti gli oggetti specificati si trovino nello stato segnalato, una routine di completamento I/O o una chiamata asincrona (APC) al thread o l'intervallo di timeout trascorso.

Sintassi

DWORD WaitForMultipleObjectsEx(
  [in] DWORD        nCount,
  [in] const HANDLE *lpHandles,
  [in] BOOL         bWaitAll,
  [in] DWORD        dwMilliseconds,
  [in] BOOL         bAlertable
);

Parametri

[in] nCount

Numero di handle di oggetto da attendere 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 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 Standard Access Rights.

[in] bWaitAll

Se questo parametro è TRUE, la funzione restituisce quando lo stato di tutti gli oggetti nella matrice lpHandles viene impostato su segnalato. 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, viene accodata una routine di completamento di I/O o APC o l'intervallo trascorso. Se dwMilliseconds è zero, la funzione non immette uno stato di attesa se i criteri non vengono soddisfatti; restituisce sempre immediatamente. Se dwMilliseconds è INFINITE, la funzione restituirà solo quando gli oggetti specificati vengono segnalate o viene accodata una routine di completamento I/O o APC.

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 stato di sospensione.

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.

[in] bAlertable

Se questo parametro è TRUE e il thread si trova nello stato di attesa, la funzione restituisce quando il sistema accoda una routine di completamento I/O o APC e il thread esegue la routine o la funzione. In caso contrario, la funzione non restituisce e la routine di completamento o la funzione APC non viene eseguita.

Una routine di completamento viene accodata quando la funzione ReadFileEx o WriteFileEx in cui è stata specificata è stata completata. La funzione wait restituisce e la routine di completamento viene chiamata solo se bAlertable è TRUE e il thread chiamante è il thread che ha avviato l'operazione di lettura o scrittura. Un APC viene accodato quando si chiama QueueUserAPC.

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.

Osservazioni

La funzione WaitForMultipleObjectsEx 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 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.