Fonction WaitForMultipleObjectsEx (synchapi.h)
Attend qu’un ou tous les objets spécifiés soient à l’état signalé, qu’une routine d’achèvement d’E/S ou un appel de procédure asynchrone (APC) soit mis en file d’attente vers le thread, ou que l’intervalle de délai d’attente s’écoule.
Syntaxe
DWORD WaitForMultipleObjectsEx(
[in] DWORD nCount,
[in] const HANDLE *lpHandles,
[in] BOOL bWaitAll,
[in] DWORD dwMilliseconds,
[in] BOOL bAlertable
);
Paramètres
[in] nCount
Nombre de handles d’objet à attendre dans le tableau pointé 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 d’objets de différents types. Il ne peut pas contenir plusieurs copies du même handle.
Si l’un de ces handles est fermé alors que l’attente est toujours en attente, le comportement de la fonction n’est pas défini.
Les handles doivent avoir le droit d’accès SYNCHRONIZE . Pour plus d’informations, consultez Droits d’accès standard.
[in] bWaitAll
Si ce paramètre a la valeur TRUE, la fonction retourne quand l’état de tous les objets du tableau lpHandles est défini sur signalé. Si la valeur est FALSE, la fonction retourne quand l’état de l’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, qu’une routine d’achèvement d’E/S ou un APC soit mis en file d’attente, ou que l’intervalle s’écoule. Si dwMilliseconds est égal à zéro, la fonction n’entre pas en état d’attente si les critères ne sont pas remplis ; elle retourne toujours immédiatement. Si dwMilliseconds a la valeur INFINITE, la fonction retourne uniquement lorsque les objets spécifiés sont signalés ou qu’une routine d’achèvement d’E/S ou qu’APC est mis en file d’attente.
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 de faible consommation d’énergie. Par exemple, le décompte du délai d’expiration continue pendant que l’ordinateur est en veille.
Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 et Windows Server 2016 : la valeur dwMilliseconds n’inclut pas le temps passé dans les états de faible consommation d’énergie. Par exemple, le décompte du délai d’expiration est arrêté quand l’ordinateur est en veille.
[in] bAlertable
Si ce paramètre a la valeur TRUE et que le thread est dans l’état d’attente, la fonction retourne lorsque le système met en file d’attente une routine d’achèvement d’E/S ou APC, et que le thread exécute la routine ou la fonction. Sinon, la fonction ne retourne pas et la routine d’achèvement ou la fonction APC n’est pas exécutée.
Une routine d’achèvement est mise en file d’attente lorsque la fonction ReadFileEx ou WriteFileEx dans laquelle elle a été spécifiée s’est terminée. La fonction wait retourne et la routine d’achèvement est appelée uniquement si bAlertable a la valeur TRUE et si le thread appelant est le thread qui a lancé l’opération de lecture ou d’écriture. Un APC est mis en file d’attente quand vous appelez QueueUserAPC.
Valeur retournée
Si la fonction réussit, la valeur de retour indique l’événement qui a provoqué le retour de la fonction. Il peut avoir l’une des valeurs suivantes. (Notez que WAIT_OBJECT_0 est défini sur 0 et WAIT_ABANDONED_0 est défini sur 0x0000080L.)
| Code/valeur de retour | Description |
|---|---|
|
Si bWaitAll a la valeur TRUE, une valeur de retour dans cette plage indique que l’état de tous les objets spécifiés est signalé.
Si bWaitAll a la valeur FALSE, la valeur de retour moins WAIT_OBJECT_0 indique l’index du tableau lpHandles de l’objet qui a satisfait l’attente. Si plusieurs objets ont été 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 a la valeur TRUE, une valeur de retour dans cette plage indique que l’état de tous les objets spécifiés est signalé, et qu’au moins un des objets est un objet mutex abandonné.
Si bWaitAll a la valeur FALSE, la valeur de retour moins WAIT_ABANDONED_0 indique l’index de tableau lpHandles d’un objet mutex abandonné qui a 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égeait les informations d’état persistantes, vous devez l’case activée par souci de cohérence. |
|
L’attente a été terminée par un ou plusieurs appels de procédure asynchrone en mode utilisateur (APC) mis en file d’attente vers le thread. |
|
L’intervalle de délai d’attente s’est écoulé, les conditions spécifiées par le paramètre bWaitAll n’ont pas été satisfaites et aucune routine d’achèvement n’est mise en file d’attente. |
|
La fonction a échoué. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError. |
Remarques
La fonction WaitForMultipleObjectsEx détermine si les critères d’attente ont été remplis. Si les critères n’ont pas été remplis, le thread appelant passe à l’état d’attente jusqu’à ce que les conditions des critères d’attente soient remplies ou que l’intervalle de délai d’attente s’écoule.
Lorsque bWaitAll a la valeur 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 sur 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, définissant ainsi son état sur non signé.
Lorsque bWaitAll a la valeur FALSE, cette fonction vérifie les handles dans le tableau dans l’ordre à partir de l’index 0, jusqu’à ce que l’un des objets soit signalé. Si plusieurs objets sont 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 réduit 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 pour attendre sur MAXIMUM_WAIT_OBJECTS handles, puis attendez ce thread plus les autres handles. Utilisez cette technique pour diviser les handles en groupes de MAXIMUM_WAIT_OBJECTS.
- Appelez RegisterWaitForSingleObject ou SetThreadpoolWait pour attendre sur chaque handle. Le pool de threads attend efficacement sur les handles et affecte un thread de travail une fois l’objet signalé ou l’expiration de l’intervalle de délai d’attente.
- Notification de modification
- Entrée de console
- Événement
- Notification de ressource mémoire
- Mutex
- Processus
- Semaphore
- Thread
- Minuteur d’attente
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows XP [applications de bureau | applications UWP] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau | applications UWP] |
| Plateforme cible | Windows |
| En-tête | synchapi.h (inclure Windows.h sur Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| Bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour