Back to Qt.io
Contact Us Blog Download Qt
Sur cette page

QtTaskTree::QCustomTask Class

template <typename Task, typename Adapter, typename Deleter> class QtTaskTree::QCustomTask

Modèle de classe permettant de déclarer des éléments de tâche personnalisés et de définir leurs gestionnaires « setup » et « done ». En savoir plus...

En-tête : #include <qtasktree.h>
CMake : find_package(Qt6 REQUIRED COMPONENTS TaskTree)
target_link_libraries(mytarget PRIVATE Qt6::TaskTree)
qmake : QT += tasktree
Depuis : Qt 6.11
Hérite de : QtTaskTree::ExecutableItem
Statut : Aperçu technologique

Cette classe est en avant-première technologique et est susceptible d'être modifiée.

Remarque : toutes les fonctions de cette classe sont réentrantes.

Types publics

TaskDoneHandler
TaskSetupHandler

Fonctions publiques

QCustomTask(SetupHandler &&setup = QCustomTask::TaskSetupHandler(), DoneHandler &&done = QCustomTask::TaskDoneHandler(), QtTaskTree::CallDone callDone = QtTaskTree::CallDoneFlag::Always)
QBarrierTask
QNetworkReplyWrapperTask
QProcessTask
QTaskTreeTask
QTcpSocketWrapperTask
QThreadFunctionTask
QTimeoutTask

Description détaillée

Décrit les éléments de tâches personnalisées au sein des recettes de l’arborescence des tâches.

Les noms de tâches personnalisées sont associés à des alias uniques à l’aide du modèle QCustomTask avec les paramètres suivants : Task, Adapter et Deleter. Par exemple, QThreadFunctionTask<T> est un alias de la classe QCustomTask définie pour fonctionner avec QThreadFunction<T> en tant que classe de tâche associée. Le tableau suivant répertorie les tâches personnalisées fournies par la bibliothèque TaskTree et leurs classes de tâches associées :

Nom de la tâche aliaséeClasse de tâche associéeBrève description
QBarrierTaskQBarrierLance une tâche d’attente.
QThreadFunctionTask<ReturnType>QThreadFunction<Type de retour>Lance une tâche asynchrone. S'exécute dans un thread distinct.
QProcessTaskQProcessLance un processus.
QNetworkReplyWrapperTaskQNetworkReplyWrapperEnvoie une requête réseau.
QTaskTreeTaskQTaskTreeLance une arborescence de tâches imbriquées.
QTcpSocketWrapperTaskQTcpSocketWrapperÉtablit une connexion TCP.
QTimeoutTaskstd::chrono::millisecondsDémarre un minuteur.

Le paramètre de modèle ` Task ` est obligatoire et spécifie le type d’ Task que l’ QTaskTree en cours d’exécution instanciera lorsqu’elle fait partie d’une recette. Le type ` Task ` doit pouvoir être construit par défaut.

L’argument de modèle ` Adapter ` est facultatif. Il peut être omis si ` QDefaultTaskAdapter<Task>` permet de s’adapter au type ` Task `. Sinon, l’ Adapter pour certaines ` Task ` doit prendre la forme suivante :

class Adapter
{
public:
    void operator()(Task *task, QTaskInterface *iface) { ... }
};

Implémentez l’opérateur () ci-dessus pour lancer l’ task, puis appelez la méthode QTaskInterface::reportDone() sur l’ iface transmis une fois la tâche terminée.

Il est garanti que l'Task et l'QTaskInterface transmis survivent à l'Adapter. Si nécessaire, le destructeur de Adapter peut toujours accéder à l'Task transmis.

Pour plus de détails, voir QTaskInterface.

L’argument de modèle Deleter est facultatif. Par défaut, l’objet std::default_delete<Task> est utilisé. L’objet Deleter personnalisé est utile lorsque le destructeur de l’objet Task en cours d’exécution est susceptible de bloquer le thread appelant. Au lieu de bloquer, le destructeur personnalisé peut déplacer la tâche en cours d’exécution vers un thread distinct et y implémenter la destruction bloquante. De cette manière, il est possible d’obtenir une destruction rapide (du point de vue du thread appelant) de la tâche en cours d’exécution dotée d’un destructeur bloquant.

Voir également QTaskInterface.

Documentation sur les types de membres

[alias] QCustomTask::TaskDoneHandler

Alias de type pour std::function<QtTaskTree::DoneResult(const Task &, QtTaskTree::DoneWith)> ou DoneResult.

TaskDoneHandler est un argument facultatif du constructeur d’un élément de tâche personnalisé. Toute fonction présentant la signature ci-dessus, lorsqu’elle est transmise en tant que gestionnaire de fin de tâche, sera appelée par l’arborescence des tâches en cours d’exécution une fois celle-ci terminée et avant que le résultat final de l’exécution ne soit renvoyé au groupe parent.

Dans le corps du gestionnaire, vous pouvez récupérer les données finales de la tâche terminée. Les paramètres supplémentaires, y compris les stockages, peuvent être transmis au gestionnaire via la capture lambda. Il est également possible de décider dynamiquement si la tâche doit se terminer avec sa valeur de retour, ou si le résultat final doit être modifié.

L’argument ` DoneWith ` est facultatif et votre gestionnaire de fin peut l’omettre. Lorsqu’il est fourni, il contient les informations relatives au résultat final d’une tâche qui seront transmises à son parent.

Si vous ne prévoyez pas de lire de données issues de la tâche terminée, vous pouvez omettre l'argument ` const Task & `.

La valeur ` DoneResult ` renvoyée est facultative et votre gestionnaire peut renvoyer ` void ` à la place. Dans ce cas, le résultat final de la tâche sera égal à la valeur indiquée par l’argument ` DoneResult `. Lorsque le gestionnaire renvoie la valeur ` DoneResult `, le résultat final de la tâche peut être modifié à l’intérieur du corps du gestionnaire `done` à l’aide de la valeur renvoyée.

Pour un `TaskDoneHandler` de type ` DoneResult `, aucune gestion supplémentaire n’est exécutée, et la tâche se termine inconditionnellement avec la valeur transmise par ` DoneResult`.

Voir également QCustomTask(), TaskSetupHandler et GroupDoneHandler.

[alias] QCustomTask::TaskSetupHandler

Alias de type pour ` std::function<SetupResult(Task &)>`.

TaskSetupHandler est un argument facultatif du constructeur d’un élément de tâche personnalisé. Toute fonction présentant la signature ci-dessus, lorsqu’elle est transmise en tant que gestionnaire de configuration de tâche, sera appelée par l’arborescence des tâches en cours d’exécution après la création de la tâche et avant son lancement.

Dans le corps du gestionnaire, vous pouvez configurer la tâche selon vos besoins. Les paramètres supplémentaires, y compris les stockages, peuvent être transmis au gestionnaire via la capture lambda. Vous pouvez décider de manière dynamique si la tâche doit être lancée ou ignorée, en cas de succès ou d’erreur.

Remarque : ne lancez pas vous-même la tâche à l’intérieur du gestionnaire de démarrage. Laissez cette tâche à QTaskTree; sinon, le comportement est indéfini. QTaskTree sait déjà comment lancer la tâche grâce au paramètre de modèle Adapter transmis au constructeur QCustomTask<Task, Adapter, Deleter>.

La valeur de retour du gestionnaire indique à l’arborescence des tâches en cours d’exécution comment procéder une fois l’appel du gestionnaire terminé. La valeur de retour de ` SetupResult::Continue ` indique à l’arborescence de tâches de poursuivre son exécution, c’est-à-dire d’exécuter le ` Task` associé. La valeur de retour de ` SetupResult::StopWithSuccess ` ou ` SetupResult::StopWithError ` indique à l’arborescence de tâches d’ignorer l’exécution de la tâche et de la terminer immédiatement, respectivement avec succès ou en signalant une erreur.

Lorsque le type de retour est soit SetupResult::StopWithSuccess soit SetupResult::StopWithError, le gestionnaire « done » de la tâche (s'il est fourni) n'est pas appelé par la suite.

Le constructeur d’une tâche personnalisée accepte également des fonctions sous la forme abrégée std::function<void(Task &)>, c’est-à-dire que la valeur de retour est void. Dans ce cas, on suppose que la valeur de retour est SetupResult::Continue.

Voir également QCustomTask(), TaskDoneHandler et GroupSetupHandler.

Documentation sur les fonctions membres

[explicit] template < typename SetupHandler = QtTaskTree::QCustomTask<Task, Adapter, Deleter>::TaskSetupHandler, typename DoneHandler = QtTaskTree::QCustomTask<Task, Adapter, Deleter>::TaskDoneHandler, std::enable_if_t<!std::is_same_v<q20::remove_cvref_t<SetupHandler>, QCustomTask<Task, Adapter, Deleter>>, bool> = true > QCustomTask::QCustomTask(SetupHandler &&setup = QCustomTask::TaskSetupHandler(), DoneHandler &&done = QCustomTask::TaskDoneHandler(), QtTaskTree::CallDone callDone = QtTaskTree::CallDoneFlag::Always)

Crée une instance de QCustomTask et associe les gestionnaires setup et done à la tâche. Lorsque l'arborescence des tâches en cours d'exécution s'apprête à lancer la tâche, elle instancie l'objet Task associé, appelle le gestionnaire setup en lui passant une référence à la tâche créée, puis la lance. Lorsque la tâche en cours d'exécution se termine, l'arborescence des tâches appelle le gestionnaire done en lui passant une référence const à la tâche créée.

Le gestionnaire setup transmis est de type TaskSetupHandler. Par exemple :

static void parseAndLog(const QString &input);

...

const QString input = ...;

const auto onFirstSetup = [input](QThreadFunction<void> &task) {
    if (input == "Skip")
        return SetupResult::StopWithSuccess; // This task won't start, the next one will
    if (input == "Error")
        return SetupResult::StopWithError; // This task and the next one won't start
    task.setThreadFunctionData(parseAndLog, input);
    // This task will start, and the next one will start after this one finished with success
    return SetupResult::Continue;
};

const auto onSecondSetup = [input](QThreadFunction<void> &task) {
    task.setThreadFunctionData(parseAndLog, input);
};

const Group group {
    QThreadFunctionTask<void>(onFirstSetup),
    QThreadFunctionTask<void>(onSecondSetup)
};

Le gestionnaire done est de type TaskDoneHandler. Par défaut, le gestionnaire done est appelé dès que la tâche se termine. Passez une valeur non par défaut à l’argument callDone si vous souhaitez que le gestionnaire ne soit appelé qu’en cas de réussite, d’échec ou d’annulation de l’exécution.

Voir également TaskSetupHandler et TaskDoneHandler.

Éléments non membres associés

[alias] QBarrierTask

Alias de type pour l'QCustomTask<QBarrier>, à utiliser dans les recettes.

[alias] QNetworkReplyWrapperTask

Alias de type pour l'QCustomTask<QNetworkReplyWrapper>, à utiliser dans les recettes.

[alias] QProcessTask

Alias de type pour l'QCustomTask ion <QProcess>, utilisant QProcessTaskDeleter, à utiliser dans les recettes.

[alias] QTaskTreeTask

Alias de type pour l'QCustomTask<QTaskTree>, à utiliser dans les recettes.

[alias] QTcpSocketWrapperTask

Alias de type pour l'QCustomTask<QTcpSocketWrapper>, à utiliser dans les recettes.

[alias] template <typename ResultType> QThreadFunctionTask

Alias de type pour QCustomTask<QThreadFunction<ResultType>>, où ResultType spécifie le type de retour de la fonction de thread, à utiliser dans les recettes.

[alias] QTimeoutTask

Alias de type pour la classe ` QCustomTask` <std::chrono::milliseconds>, destiné à être utilisé dans les recettes. La propriété ` std::chrono::milliseconds ` permet de définir la durée du délai d'expiration. Le délai d'expiration par défaut est ` std::chrono::milliseconds::zero()` ; cela signifie que la classe `QTimeoutTask` se termine dès que le contrôle revient à la boucle d'événements en cours d'exécution.

Exemple d'utilisation :

using namespace std::chrono;
using namespace std::chrono_literals;

const auto onSetup = [](milliseconds &timeout) { timeout = 1000ms; }
const auto onDone = [] { qDebug() << "Timed out."; }

const Group root {
    QTimeoutTask(onSetup, onDone)
};

Voir également timeoutTask().

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.