structured_task_group, classe

La classe structured_task_group représente une collection très structurée de travail parallèle. Vous pouvez mettre en file d'attente des tâches parallèles individuelles dans un structured_task_group à l'aide d'objets task_handle, attendre qu'elles se terminent ou annuler le groupe de tâches avant la fin de leur exécution, ce qui annule toutes les tâches dont l'exécution n'a pas commencé.

Syntaxe

class structured_task_group;

Membres

Constructeurs publics

Nom	Description
structured_task_group	Surcharge. Construit un nouvel objet structured_task_group.
~structured_task_group Destructeur	Détruit un objet structured_task_group . Vous êtes censé appeler soit la ou run_and_wait la wait méthode sur l’objet avant l’exécution du destructeur, sauf si le destructeur s’exécute à la suite d’un déroulement de la pile en raison d’une exception.

Méthodes publiques

Nom	Description
cancel	Effectue une tentative optimale d’annulation de l’arborescence de travail enracinée dans ce groupe de tâches. Chaque tâche planifiée sur le groupe de tâches sera annulée de manière transitive si possible.
is_canceling	Informe l’appelant si le groupe de tâches est actuellement au milieu d’une annulation. Cela n’indique pas nécessairement que la cancel méthode a été appelée sur l’objet structured_task_group (bien que cela qualifie certainement cette méthode pour retourner true). Il peut s’agir du cas où l’objet structured_task_group s’exécute inline et qu’un groupe de tâches plus haut dans l’arborescence de travail a été annulé. Dans les cas tels que ceux où le runtime peut déterminer à l’avance que l’annulation transite par cet structured_task_group objet, true sera également retournée.
run	Surcharge. Planifie une tâche sur l’objet structured_task_group . L’appelant gère la durée de vie de l’objet task_handle passé dans le _Task_handle paramètre. La version qui accepte le paramètre _Placement entraîne le biais de la tâche vers l’exécution à l’emplacement spécifié par ce paramètre.
run_and_wait	Surcharge. Planifie l’exécution d’une tâche inline sur le contexte appelant à l’aide de l’objet pour la prise en charge complète de l’annulation structured_task_group . Si un task_handle objet est passé en tant que paramètre, run_and_waitl’appelant est responsable de la gestion de la durée de vie de l’objet task_handle . La fonction attend ensuite que tous les travaux sur l’objet structured_task_group soient terminés ou annulés.
Attendre	Attend que tous les travaux sur le site structured_task_group soient terminés ou annulés.

Notes

Il existe un certain nombre de restrictions sévères sur l’utilisation d’un structured_task_group objet afin d’obtenir des performances :

• Un seul structured_task_group objet ne peut pas être utilisé par plusieurs threads. Toutes les opérations sur un structured_task_group objet doivent être effectuées par le thread qui a créé l’objet. Les deux exceptions à cette règle sont les fonctions cancel membres et is_canceling. L’objet peut ne pas figurer dans la liste de capture d’une expression lambda et être utilisé dans une tâche, sauf si la tâche utilise l’une des opérations d’annulation.

• Toutes les tâches planifiées sur un structured_task_group objet sont planifiées par le biais de l’utilisation d’objets task_handle dont vous devez gérer explicitement la durée de vie.

• Plusieurs groupes peuvent uniquement être utilisés dans un ordre absolument imbriqué. Si deux structured_task_group objets sont déclarés, le deuxième doit être déclaré (l’intérieur) avant toute méthode sauf cancel ou is_canceling est appelé sur le premier (l’extérieur). Cette condition a la valeur true dans le cas de la simple déclaration de plusieurs structured_task_group objets dans les mêmes étendues imbriquées fonctionnellement ou dans le cas d’une tâche mise en file d’attente vers l’intermédiaire structured_task_group ou les runrun_and_wait méthodes.

• Contrairement à la classe générale task_group , tous les états de la structured_task_group classe sont définitifs. Une fois que vous avez mis en file d’attente les tâches vers le groupe et attendu qu’elles se terminent, vous n’utilisez peut-être plus le même groupe.

Pour plus d’informations, consultez Parallélisme des tâches.

Hiérarchie d'héritage

structured_task_group

Spécifications

En-tête : ppl.h

Espace de noms : concurrency

cancel

Effectue une tentative optimale d’annulation de l’arborescence de travail enracinée dans ce groupe de tâches. Chaque tâche planifiée sur le groupe de tâches sera annulée de manière transitive si possible.

void cancel();

Notes

Pour plus d’informations, consultez Annulation.

is_canceling

Informe l’appelant si le groupe de tâches est actuellement au milieu d’une annulation. Cela n’indique pas nécessairement que la cancel méthode a été appelée sur l’objet structured_task_group (bien que cela qualifie certainement cette méthode pour retourner true). Il peut s’agir du cas où l’objet structured_task_group s’exécute inline et qu’un groupe de tâches plus haut dans l’arborescence de travail a été annulé. Dans les cas tels que ceux où le runtime peut déterminer à l’avance que l’annulation transite par cet structured_task_group objet, true sera également retournée.

bool is_canceling();

Valeur de retour

Indication indiquant si l’objet structured_task_group se trouve au milieu d’une annulation (ou est garanti pour être bientôt).

Notes

Pour plus d’informations, consultez Annulation.

Exécuter

Planifie une tâche sur l’objet structured_task_group . L’appelant gère la durée de vie de l’objet task_handle passé dans le _Task_handle paramètre. La version qui accepte le paramètre _Placement entraîne le biais de la tâche vers l’exécution à l’emplacement spécifié par ce paramètre.

template<class _Function>
void run(
    task_handle<_Function>& _Task_handle);

template<class _Function>
void run(
    task_handle<_Function>& _Task_handle,
    location& _Placement);

Paramètres

_Fonction
Type de l’objet de fonction qui sera appelé pour exécuter le corps du handle de tâche.

_Task_handle
Handle pour le travail en cours de planification. Notez que l’appelant a la responsabilité de la durée de vie de cet objet. Le runtime continuera à s’attendre à ce qu’il soit actif tant que la ou la waitrun_and_wait méthode n’a pas été appelée sur cet structured_task_group objet.

_Placement
Référence à l’emplacement où la tâche représentée par le _Task_handle paramètre doit s’exécuter.

Notes

Le runtime crée une copie de la fonction de travail que vous passez à cette méthode. Toute modification d’état qui se produit dans un objet de fonction que vous passez à cette méthode n’apparaît pas dans votre copie de cet objet de fonction.

Si les structured_task_group destructeurs résultent du déroulement de la pile à partir d’une exception, vous n’avez pas besoin de garantir qu’un appel a été effectué à l’aide de la ou run_and_wait de la wait méthode. Dans ce cas, le destructeur annule et attend la fin de la tâche représentée par le _Task_handle paramètre.

Lève une exception invalid_multiple_scheduling si le handle de tâche donné par le _Task_handle paramètre a déjà été planifié sur un objet de groupe de tâches via la run méthode et qu’aucun appel intermédiaire n’a été effectué sur ce run_and_waitwait groupe de tâches.

run_and_wait

Planifie l’exécution d’une tâche inline sur le contexte appelant à l’aide de l’objet pour la prise en charge complète de l’annulation structured_task_group . Si un task_handle objet est passé en tant que paramètre, run_and_waitl’appelant est responsable de la gestion de la durée de vie de l’objet task_handle . La fonction attend ensuite que tous les travaux sur l’objet structured_task_group soient terminés ou annulés.

template<class _Function>
task_group_status run_and_wait(task_handle<_Function>& _Task_handle);

template<class _Function>
task_group_status run_and_wait(const _Function& _Func);

Paramètres

_Fonction
Type de l’objet de fonction qui sera appelé pour exécuter la tâche.

_Task_handle
Handle de la tâche qui sera exécutée en ligne sur le contexte appelant. Notez que l’appelant a la responsabilité de la durée de vie de cet objet. Le runtime continuera de s’attendre à ce qu’il soit actif jusqu’à la fin de l’exécution de la run_and_wait méthode.

_Func
Fonction qui sera appelée pour appeler le corps du travail. Il peut s’agir d’un objet lambda ou autre qui prend en charge une version de l’opérateur d’appel de fonction avec la signature void operator()().

Valeur de retour

Indique si l’attente a été satisfaite ou si le groupe de tâches a été annulé, en raison d’une opération d’annulation explicite ou d’une exception levée à partir de l’une de ses tâches. Pour plus d’informations, consultez task_group_status

Notes

Notez qu’une ou plusieurs des tâches planifiées sur cet structured_task_group objet peuvent s’exécuter inline sur le contexte appelant.

Si une ou plusieurs des tâches planifiées à cet structured_task_group objet lèvent une exception, le runtime sélectionne une exception de ce type de choix et la propage hors de l’appel à la run_and_wait méthode.

Une fois cette fonction retournée, l’objet structured_task_group est considéré dans un état final et ne doit pas être utilisé. Notez que l’utilisation après le retour de la run_and_wait méthode entraîne un comportement non défini.

Dans le chemin d’exécution non exceptionnel, vous avez le mandat d’appeler cette méthode ou la wait méthode avant le destructeur des structured_task_group exécutions.

structured_task_group

Construit un nouvel objet structured_task_group.

structured_task_group();

structured_task_group(cancellation_token _CancellationToken);

Paramètres

_Cancellationtoken
Jeton d’annulation à associer à ce groupe de tâches structuré. Le groupe de tâches structuré est annulé lorsque le jeton est annulé.

Notes

Le constructeur qui accepte un jeton d’annulation crée un structured_task_group jeton qui sera annulé lorsque la source associée au jeton est annulée. Fournir un jeton d’annulation explicite isole également ce groupe de tâches structuré de participer à une annulation implicite d’un groupe parent avec un jeton différent ou aucun jeton.

~structured_task_group

Détruit un objet structured_task_group . Vous êtes censé appeler soit la ou run_and_wait la wait méthode sur l’objet avant l’exécution du destructeur, sauf si le destructeur s’exécute à la suite d’un déroulement de la pile en raison d’une exception.

~structured_task_group();

Notes

Si le destructeur s’exécute en conséquence de l’exécution normale (par exemple, pas de déroulement de pile en raison d’une exception) et que ni les wait méthodes n’ont run_and_wait été appelées, le destructeur peut lever une exception missing_wait .

wait

Attend que tous les travaux sur le site structured_task_group soient terminés ou annulés.

task_group_status wait();

Valeur de retour

Indique si l’attente a été satisfaite ou si le groupe de tâches a été annulé, en raison d’une opération d’annulation explicite ou d’une exception levée à partir de l’une de ses tâches. Pour plus d’informations, consultez task_group_status

Notes

Notez qu’une ou plusieurs des tâches planifiées sur cet structured_task_group objet peuvent s’exécuter inline sur le contexte appelant.

Si une ou plusieurs des tâches planifiées à cet structured_task_group objet lèvent une exception, le runtime sélectionne une exception de ce type de choix et la propage hors de l’appel à la wait méthode.

Une fois cette fonction retournée, l’objet structured_task_group est considéré dans un état final et ne doit pas être utilisé. Notez que l’utilisation après le retour de la wait méthode entraîne un comportement non défini.

Dans le chemin d’exécution non exceptionnel, vous avez le mandat d’appeler cette méthode ou la run_and_wait méthode avant le destructeur des structured_task_group exécutions.

Voir aussi

accès concurrentiel Namespace
Classe task_group
task_handle, classe