WaitForMultipleObjects, fonction (synchapi.h)
Attend qu’un ou tous les objets spécifiés soient dans l’état signalé ou que l’intervalle de délai d’attente s’écoule.
Pour entrer un état d’attente alertable, utilisez la fonction WaitForMultipleObjectsEx.
Syntaxe
DWORD WaitForMultipleObjects(
[in] DWORD nCount,
[in] const HANDLE *lpHandles,
[in] BOOL bWaitAll,
[in] DWORD dwMilliseconds
);
Paramètres
[in] nCount
Nombre de handles d’objets dans le tableau pointés par lpHandles. Le nombre maximal de handles d’objet est MAXIMUM_WAIT_OBJECTS. Ce paramètre ne peut pas être égal à zéro.
[in] lpHandles
Tableau de handles d’objet. Pour obtenir la liste des types d’objets dont les handles peuvent être spécifiés, consultez la section Remarques suivante. Le tableau peut contenir des handles vers des objets de différents types. Il peut ne pas contenir plusieurs copies du même handle.
Si l’un de ces handles est fermé pendant que l’attente est toujours en attente, le comportement de la fonction n’est pas défini.
Les handles doivent disposer du droit d’accès SYNCHRONIZE. Pour plus d’informations, consultez Standard Access Rights.
[in] bWaitAll
Si ce paramètre est TRUE, la fonction retourne lorsque l’état de tous les objets dans le tableau lpHandles est signalé. Si faux, la fonction retourne lorsque l’état d’un des objets est défini sur signalé. Dans ce dernier cas, la valeur de retour indique l’objet dont l’état a provoqué le retour de la fonction.
[in] dwMilliseconds
Intervalle de délai d’attente, en millisecondes. Si une valeur différente de zéro est spécifiée, la fonction attend que les objets spécifiés soient signalés ou que l’intervalle s’écoule. Si dwMilliseconds est égal à zéro, la fonction n’entre pas dans un état d’attente si les objets spécifiés ne sont pas signalés ; elle retourne toujours immédiatement. Si dwMilliseconds est INFINITE, la fonction ne retourne que lorsque les objets spécifiés sont signalés.
Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 et Windows Server 2008 R2 : La valeur dwMilliseconds inclut le temps passé dans les états à faible alimentation. Par exemple, le délai d’attente ne cesse de compter pendant que l’ordinateur est endormi.
Windows 8 et versions ultérieures, Windows Server 2012 et versions ultérieures : La valeur dwMilliseconds n’inclut pas le temps passé dans les états à faible alimentation. Par exemple, le délai d’expiration ne continue pas à compter pendant que l’ordinateur est endormi.
Valeur de retour
Si la fonction réussit, la valeur de retour indique l’événement qui a provoqué le retour de la fonction. Il peut s’agir de l’une des valeurs suivantes. (Notez que WAIT_OBJECT_0 est défini comme 0 et WAIT_ABANDONED_0 est défini comme 0x00000080L.)
| Retourner le code/la valeur | Description |
|---|---|
|
Si bWaitAll est TRUE, une valeur de retour dans la plage spécifiée indique que l’état de tous les objets spécifiés est signalé.
Si bWaitAll est FALSE, la valeur de retour moins WAIT_OBJECT_0 indique l’index de tableau lpHandles de l’objet qui satisfait l’attente. Si plusieurs objets sont devenus signalés pendant l’appel, il s’agit de l’index de tableau de l’objet signalé avec la plus petite valeur d’index de tous les objets signalés. |
|
Si bWaitAll est TRUE, une valeur de retour dans la plage spécifiée indique que l’état de tous les objets spécifiés est signalé et qu’au moins l’un des objets est un objet mutex abandonné.
Si bWaitAll est FALSE, la valeur de retour moins WAIT_ABANDONED_0 indique l’index de tableau lpHandles d’un objet mutex abandonné qui satisfait l’attente. La propriété de l’objet mutex est accordée au thread appelant et le mutex est défini sur non signé. Si un mutex protège les informations d’état persistant, vous devez vérifier sa cohérence. |
|
L’intervalle de délai d’attente écoulé et les conditions spécifiées par le paramètre bWaitAll ne sont pas satisfaites. |
|
La fonction a échoué. Pour obtenir des informations d’erreur étendues, appelez GetLastError. |
Remarques
La fonction WaitForMultipleObjects détermine si les critères d’attente ont été remplis. Si les critères n’ont pas été remplis, le thread appelant entre dans l’état d’attente jusqu’à ce que les conditions des critères d’attente aient été remplies ou que l’intervalle de délai d’attente s’écoule.
Lorsque bWaitAll est TRUE, l’opération d’attente de la fonction est terminée uniquement lorsque les états de tous les objets ont été définis sur signalés. La fonction ne modifie pas les états des objets spécifiés tant que les états de tous les objets n’ont pas été définis comme signalés. Par exemple, un mutex peut être signalé, mais le thread n’obtient pas la propriété tant que les états des autres objets ne sont pas également définis sur signalés. En attendant, un autre thread peut obtenir la propriété du mutex, ce qui définit son état sur non signé.
Lorsque bWaitAll est FALSE, cette fonction vérifie les handles du tableau dans l’ordre commençant par l’index 0, jusqu’à ce qu’un des objets soit signalé. Si plusieurs objets deviennent signalés, la fonction retourne l’index du premier handle dans le tableau dont l’objet a été signalé.
La fonction modifie l’état de certains types d’objets de synchronisation. La modification se produit uniquement pour l’objet ou les objets dont l’état signalé a provoqué le retour de la fonction. Par exemple, le nombre d’un objet sémaphore est diminué d’un. Pour plus d’informations, consultez la documentation relative aux objets de synchronisation individuels.
Pour attendre plus de MAXIMUM_WAIT_OBJECTS handles, utilisez l’une des méthodes suivantes :
- Créez un thread à attendre sur MAXIMUM_WAIT_OBJECTS handles, puis attendez ce thread et les autres handles. Utilisez cette technique pour décomposer les handles en groupes de MAXIMUM_WAIT_OBJECTS.
- Appelez RegisterWaitForSingleObject ou SetThreadpoolWait attendre chaque handle. Le pool de threads attend efficacement sur les handles et affecte un thread de travail une fois l’objet signalé ou l’intervalle de délai d’expiration.
- Notification de modification
- Entrée de console
- Événement
- Notification de ressource mémoire
- Mutex
- Processus
- Sémaphore
- Fil
- Minuteur pouvant être attendu
Exemples
Pour obtenir un exemple, consultez Attente de plusieurs objets.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows XP [applications de bureau | Applications UWP] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau | Applications UWP] |
| plateforme cible | Windows |
| d’en-tête | synchapi.h (include Windows.h) |
| bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |