Vue d’ensemble de l’API de file d’attente de tâches
Une file d’attente de tâches est composée de deux ports de file d’attente : un port de travail et un port d’achèvement. Ces ports sont regroupés dans le même objet parce que vous avez souvent besoin des deux : le port de travail pour effectuer le travail asynchrone et le port d’achèvement pour en informer l’utilisateur. Une file d’attente de tâches se décrit comme suit.- Elle contient deux ports de file d’attente de tâches.
- Chaque port de file d’attente de tâches peut avoir son propre mode de distribution, qui détermine la façon dont les éléments de la file d’attente sont distribués.
- Les modes de distribution vont de la distribution entièrement automatique par le pool de threads du système à la distribution entièrement manuelle, où les tâches doivent être retirées explicitement.
- Des rappels peuvent être soumis à l’un ou l’autre des ports de la file d’attente.
- Les files d’attente sont représentées par des handles. Les handles peuvent être dupliqués, ce qui revient essentiellement à augmenter un compteur de références sur la file d’attente.
- Pool de threads : Les rappels mis en file d’attente dans une file d’attente du pool de threads sont exécutés sur le pool de threads du système. Le pool de threads appelle les appels en parallèle, prenant tour à tour un appel à exécuter dans la file d’attente à mesure que les threads du pool de threads deviennent disponibles.
- Pool de threads sérialisé : Les rappels sont mis en file d’attente et exécutés sur le pool de threads, mais ils sont exécutés l’un après l’autre au lieu de s’exécuter en parallèle sur tous les threads du pool de threads.
- Manuel : Les rappels mis en file d’attente dans une file d’attente manuelle ne sont pas distribués automatiquement. C’est à vous de les distribuer sur le thread de votre choix. Si vous utilisez des files d’attente de tâches manuelles, vous devez vous assurer de pomper également la file d’attente de messages Windows.
- Immédiat : Le mode de distribution immédiat ne met rien en file d’attente. Il exécute immédiatement l’appel sur le thread qui a soumis le rappel.
XTaskQueueDuplicateHandle,
XTaskQueueSubmitCallback, XTaskQueueSubmitDelayedCallback et
XTaskQueueCreateComposite ajoutent tous une référence au handle de la file d’attente. Cela
signifie que la file d’attente n’est réellement détruite qu’une fois tous les rappels
achevés.
Un handle de file d’attente de tâches est une ressource propre à chaque processus et ne peut pas être marshalé ni
utilisé en dehors du processus.
Modèle d’utilisation
Le modèle d’utilisation typique d’une file d’attente de tâches est le suivant.- Créez un handle de file d’attente de tâches, puis spécifiez les modes de distribution de chaque port.
- Si vous utilisez la distribution manuelle, établissez des threads propres à l’application pour appeler la fonction de distribution de la file d’attente.
-
Utilisez la file d’attente comme paramètre des appels du Microsoft Game Development Kit (GDK) ou soumettez
directement à l’aide de
XTaskQueueCallback. - Vous pouvez, si vous le souhaitez, terminer la file d’attente de tâches lorsque votre application s’arrête.
Rubriques de procédures sur la file d’attente de tâches asynchrones
Cette section fournit des exemples de procédures pour des scénarios courants de file d’attente de tâches asynchrones.Dans cette section
Création d’une file d’attente de tâches du pool de threads Fournit un exemple qui montre comment créer une file d’attente de tâches qui distribue les rappels de travail et d’achèvement sur le pool de threads du système. Soumission de rappels Fournit un exemple qui montre comment un rappel est soumis au port de travail ou au port d’achèvement d’une file d’attente de tâches. Duplication d’un handle de file d’attente de tâches Fournit un exemple qui montre comment dupliquer un handle de file d’attente de tâches. Si vous avez un travail de longue durée, vous pourriez vouloir dupliquer le handle de la file d’attente de tâches pendant la durée du travail. Ainsi, quiconque appelleXTaskQueueCloseHandle ne fermera pas la file d’attente tant que vous en aurez encore besoin.
Création d’une file d’attente de tâches manuelle
Fournit un exemple qui montre comment créer une file d’attente de tâches pompée manuellement. Il crée deux threads STL qui distribuent les appels pour le port de travail et le port d’achèvement.
Utilisation d’événements pour contrôler la distribution manuelle de la file d’attente
Fournit un exemple qui montre comment utiliser une file d’attente de tâches pour signaler une variable de condition lorsqu’elle contient des éléments à distribuer.
Utilisation d’une file d’attente de tâches avec une boucle de messages Windows
Fournit un exemple qui utilise le pool de threads pour le travail, mais intègre les rappels du port d’achèvement dans une procédure de fenêtre (Window proc) Win32. Cet exemple montre également comment terminer correctement une file d’attente de tâches lorsque vous l’intégrez à un autre modèle de threads.
Utilisation de la file d’attente de tâches du processus
Fournit un exemple qui montre comment utiliser la file d’attente de tâches du processus. La file d’attente de tâches du processus par défaut utilise le pool de threads pour la distribution du travail et des achèvements.
Création d’une file d’attente de tâches composite
Fournit un exemple qui utilise le pool de threads pour le travail, mais intègre les rappels du port d’achèvement dans une fonction de rappel WindowProc Win32. Cet exemple montre également comment terminer correctement une file d’attente de tâches lorsque vous l’intégrez à un autre modèle de threads.
Utilisation de rappels différés
Fournit un exemple qui montre comment utiliser des rappels différés, en appelant 10 rappels une fois toutes les 500 ms. Utilisez une file d’attente de tâches pour soumettre des rappels ultérieurs à l’aide de l’API XTaskQueueSubmitDelayedCallback. Ainsi, vous pouvez réessayer un appel ayant échoué après un court délai, ou l’utiliser comme minuterie peu coûteuse pour des événements périodiques.
Utilisation d’un élément d’attente de file d’attente de tâches
Fournit un exemple qui montre comment utiliser un élément d’attente (waiter) de file d’attente de tâches. Vous pouvez inscrire un handle de noyau Win32 auprès d’une file d’attente de tâches. Votre rappel sera soumis à la file d’attente lorsque le handle sera signalé.