Skip to main content

XTaskQueueTerminate

Arrête une file d’attente de tâches en annulant tous les éléments en attente et en empêchant la mise en file d’attente de nouveaux éléments.

Syntaxe

Paramètres

queue   _In_
Type : XTaskQueueHandle
File d’attente à arrêter. wait   _In_
Type : bool
True pour attendre la fin de l’arrêt. callbackContext   _In_opt_
Type : void*
Pointeur de contexte facultatif à passer au rappel. callback   _In_opt_
Type : XTaskQueueTerminatedCallback*
Rappel facultatif qui sera appelé une fois la file d’attente arrêtée.

Valeur de retour

Type : HRESULT Code de réussite ou d’erreur HRESULT.

Remarques

Il n’est pas sûr d’appeler cette fonction sur un thread urgent. Pour plus d’informations, consultez Threads urgents.
XTaskQueueCloseHandle se contente de décrémenter un décompte de références interne sur l’objet file d’attente de tâches. S’il reste des rappels dans la file d’attente, ces rappels détiennent une référence sur l’objet file d’attente et peuvent encore être appelés. Cela peut poser problème lors de l’arrêt de l’application. Lorsqu’une application s’arrête, elle doit s’assurer qu’aucun rappel parasite ne s’exécute après le nettoyage. XTaskQueue fournit l’API XTaskQueueTerminate pour effectuer un arrêt contrôlé d’une file d’attente. L’arrêt d’une file d’attente de tâches effectue les opérations suivantes :
  1. Tous les rappels des deux ports sont invoqués avec leur paramètre canceled défini sur true.
  2. Tous les rappels en attente sur le port de travail sont distribués. La soumission de nouveaux rappels au port de travail échoue avec E_ABORT.
  3. Tous les rappels en attente sur le port d’achèvement sont distribués. La soumission de nouveaux rappels au port d’achèvement échoue avec E_ABORT.
Une fois ce processus terminé, XTaskQueueTerminate retourne si wait a la valeur true. Si wait a la valeur false, l’arrêt se produit de manière asynchrone. Si vous fournissez un rappel d’arrêt, il est invoqué à partir du thread d’achèvement à la fin de l’arrêt.
  • XTaskQueueTerminate ne ferme pas le handle de file d’attente. Après l’arrêt, vous devez toujours appeler XTaskQueueCloseHandle.
  • Si vous appelez XTaskQueueTerminate sur un thread qui traite les rappels de la file d’attente en appelant XTaskQueueDispatch, ne passez pas true pour le paramètre wait, sinon votre code risque de se bloquer (interblocage).
L’exemple suivant montre comment arrêter une file d’attente de tâches précédemment créée.
SubmitCallback est une fonction d’assistance définie dans l’exemple de code de la fonction XTaskQueueSubmitCallback.
Une file d’attente de tâches peut être intégrée à un thread d’interface utilisateur. En général, vous souhaitez que les rappels mis en file d’attente sur le port d’achèvement s’exécutent sur le thread d’interface utilisateur. Cet exemple 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. Il montre également l’arrêt correct d’une file d’attente de tâches lors de son intégration à un autre modèle de threading.

Configuration requise

En-tête : XTaskQueue.h Bibliothèque : xgameruntime.lib Plateformes prises en charge : Windows, consoles de la famille XBOX One et consoles XBOX Series

Documentation conceptuelle

Voir aussi

Membres XTaskQueue
Modèle de programmation asynchrone
Conception de la file d’attente de tâches asynchrones
Last modified on October 6, 2026