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

QtTaskTree::QCustomTask Class

template <typename Task, typename Adapter = QtTaskTree::QDefaultTaskAdapter<Task>, typename Deleter = std::default_delete<Task>> class QtTaskTree::QCustomTask

Un modèle de classe utilisé pour déclarer des éléments de tâche personnalisés et définir leurs gestionnaires de configuration et d'exécution. Plus d'informations...

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 : QtTaskTree::ExecutableItem

Note : 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 dans les recettes de l'arbre des tâches.

Les noms des tâches personnalisées sont aliasés avec des noms uniques en utilisant le modèle QCustomTask avec une tâche, un adaptateur et un suppresseur donnés. Par exemple, QThreadFunctionTask<T> est un alias de la QCustomTask définie pour fonctionner avec QThreadFunction<T> en tant que classe de tâche associée. Le tableau suivant contient 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
QBarrierTaskQBarrierDémarre une tâche d'attente.
QThreadFunctionTask<ReturnType>QThreadFunction<ReturnType>Démarre une tâche asynchrone. S'exécute dans un thread séparé.
QProcessTaskQProcessDémarre un processus.
QNetworkReplyWrapperTaskQNetworkReplyWrapperEnvoie une requête réseau.
QTaskTreeTaskQTaskTreeDémarre un arbre de tâches imbriquées.
QTcpSocketWrapperTaskQTcpSocketWrapperÉtablit une connexion TCP.
QTimeoutTaskstd::chrono::millisecondsDémarre un timer.

Le paramètre de modèle Task est obligatoire et spécifie le type de Task que le QTaskTree en cours d'exécution instanciera lorsqu'il fera partie de la recette. Le type Task doit être constructible par défaut.

L'argument du modèle Adapter est facultatif. Il peut être ignoré si QDefaultTaskAdapter<Task> permet d'adapter le type Task. Sinon, le type Adapter pour certains Task doit avoir la forme suivante :

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

Mettre en œuvre l'opérateur() ci-dessus pour démarrer task, et appeler la méthode QTaskInterface::reportDone() sur le iface passé lorsque la tâche est terminée.

Il est garanti que les Task et QTaskInterface passés survivent au Adapter. Si nécessaire, le destructeur de Adapter peut toujours accéder au Task passé.

Pour plus de détails, voir QTaskInterface.

L'argument du modèle Deleter est facultatif. Par défaut, le modèle std::default_delete<Task> est utilisé. La version personnalisée de Deleter est utile lorsque le destructeur de Task en cours d'exécution peut potentiellement bloquer le thread de l'appelant. Au lieu de bloquer, le destructeur personnalisé peut déplacer la tâche en cours d'exécution dans un thread séparé et y implémenter la destruction bloquante. De cette manière, la destruction rapide (vue du thread de l'appelant) de la tâche en cours d'exécution avec un destructeur bloquant peut être réalisée.

Voir également QTaskInterface.

Documentation sur les types de membres

[alias] QCustomTask::TaskDoneHandler

Type alias 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 portant la signature ci-dessus, lorsqu'elle est transmise en tant que gestionnaire de tâche terminée, sera appelée par l'arbre des tâches en cours d'exécution une fois l'exécution de la tâche terminée et avant que le résultat final de l'exécution ne soit communiqué 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 espaces de stockage, 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 tâches peut l'omettre. Lorsqu'il est fourni, il contient des informations sur le résultat final d'une tâche qui seront communiquées à son parent.

Si vous ne prévoyez pas de lire les données 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é dans le corps du gestionnaire done en fonction de la valeur renvoyée.

Pour un TaskDoneHandler de type DoneResult, aucune manipulation supplémentaire n'est exécutée, et la tâche se termine inconditionnellement avec la valeur passée de DoneResult.

Voir également QCustomTask(), TaskSetupHandler, et GroupDoneHandler.

[alias] QCustomTask::TaskSetupHandler

Type alias pour std::function<SetupResult(Task &)>.

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

Dans le corps du gestionnaire, vous pouvez configurer la tâche selon vos besoins. Les paramètres supplémentaires, y compris les espaces de stockage, peuvent être transmis au gestionnaire par l'intermédiaire de la capture lambda. Vous pouvez décider dynamiquement si la tâche doit être lancée ou ignorée avec un succès ou une erreur.

Remarque : ne démarrez 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 démarrer 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'arbre des tâches en cours d'exécution comment procéder une fois l'invocation du gestionnaire terminée. La valeur de retour de SetupResult::Continue indique à l'arbre des tâches de continuer à fonctionner, c'est-à-dire d'exécuter la tâche associée Task. La valeur de retour de SetupResult::StopWithSuccess ou SetupResult::StopWithError indique à l'arbre des tâches de sauter l'exécution de la tâche et de la terminer immédiatement avec un succès ou une erreur, respectivement.

Lorsque le type de retour est SetupResult::StopWithSuccess ou SetupResult::StopWithError, le gestionnaire d'exécution 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 les fonctions sous la forme abrégée de 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 aussi 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)

Construit une instance de QCustomTask et attache les gestionnaires setup et done à la tâche. Lorsque l'arbre des tâches en cours d'exécution est sur le point de démarrer la tâche, il instancie l'objet Task associé, invoque le gestionnaire setup avec une référence à la tâche créée et la démarre. Lorsque la tâche en cours se termine, l'arbre des tâches invoque un gestionnaire done, avec 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 invoqué chaque fois que la tâche se termine. Passez une valeur différente de la valeur par défaut pour 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.

Non-membres associés

[alias] QBarrierTask

Type d'alias pour le QCustomTask<QBarrier>, à utiliser dans les recettes.

[alias] QNetworkReplyWrapperTask

Type d'alias pour le QCustomTask<QNetworkReplyWrapper>, à utiliser dans les recettes.

[alias] QProcessTask

Type d'alias pour le QCustomTask<QProcess>, utilisant QProcessTaskDeleter, à utiliser dans les recettes.

[alias] QTaskTreeTask

Type d'alias pour le QCustomTask<QTaskTree>, à utiliser dans les recettes.

[alias] QTcpSocketWrapperTask

Type d'alias pour le QCustomTask<QTcpSocketWrapper>, à utiliser dans les recettes.

[alias] template <typename ResultType> QThreadFunctionTask

Type alias pour le QCustomTask<QThreadFunction<ResultType>>, à utiliser dans les recettes.

[alias] QTimeoutTask

Type d'alias pour QCustomTask<std::chrono::milliseconds>, à utiliser dans les recettes. std::chrono::milliseconds est utilisé pour définir la durée du délai d'attente. La durée par défaut est std::chrono::milliseconds::zero(), c'est-à-dire que la QTimeoutTask se termine dès que le contrôle revient dans la boucle d'événements en cours.

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.