QtTaskTree::QTaskTree Class

Documentation des fonctions membres

[explicit] QTaskTree::QTaskTree(QObject *parent)

Construit un arbre de tâches vide avec un parent donné. Utilisez setRecipe() pour transmettre une description déclarative de la manière dont l'arbre des tâches doit exécuter les tâches et de la manière dont il doit gérer les tâches terminées.

Le démarrage d'un arbre des tâches vide est sans effet et le message d'avertissement correspondant est émis.

Voir aussi setRecipe() et start().

[explicit] QTaskTree::QTaskTree(const QtTaskTree::Group &recipe, QObject *parent = nullptr)

Construit un arbre de tâches avec un recipe et un parent donnés. Une fois l'arbre des tâches démarré, il exécute les tâches contenues dans recipe et traite les tâches terminées en fonction de la description transmise.

Voir aussi setRecipe() et start().

[override virtual noexcept] QTaskTree::~QTaskTree()

Détruit l'arbre des tâches.

Lorsque l'arborescence des tâches est en cours d'exécution pendant la destruction, toutes les tâches en cours sont immédiatement annulées. Dans ce cas, aucun gestionnaire n'est appelé, pas même les gestionnaires done des groupes et des tâches ou les gestionnaires onStorageDone(). L'arbre des tâches n'émet pas non plus de signaux à partir du destructeur, pas même les signaux done() ou progressValueChanged(). On peut toujours compter sur ce comportement. Il est tout à fait sûr de détruire l'arbre des tâches en cours d'exécution.

Il s'agit d'un modèle habituel de destruction de l'arbre des tâches en cours d'exécution. Il est garanti que la destruction s'effectuera rapidement, sans avoir à attendre que les tâches en cours d'exécution se terminent, à condition que les tâches utilisées implémentent leurs destructeurs d'une manière non bloquante.

Voir aussi cancel().

qsizetype QTaskTree::asyncCount() const

Renvoie le nombre réel actuel de chaînes d'invocations asynchrones.

La valeur renvoyée indique combien de fois le contrôle retourne à la boucle d'événements de l'appelant pendant que l'arbre des tâches est en cours d'exécution. Initialement, cette valeur est 0. Si l'exécution de l'arbre des tâches se termine de manière entièrement synchrone, cette valeur reste 0. Si l'arborescence des tâches contient des tâches asynchrones lancées avec succès lors d'un appel à start(), cette valeur passe à 1 juste avant que l'appel à start() ne se termine. Plus tard, lorsqu'une tâche asynchrone se termine et que les éventuelles continuations sont lancées, cette valeur est à nouveau déplacée. Le changement de valeur se poursuit jusqu'à ce que l'arbre des tâches se termine. Lorsque l'arbre des tâches émet le signal done(), le pompage s'arrête. Le signal asyncCountChanged() est émis à chaque déclenchement de cette valeur.

Voir aussi asyncCountChanged().

[signal] void QTaskTree::asyncCountChanged(qsizetype count)

Ce signal est émis lorsque l'arbre des tâches en cours d'exécution est sur le point de rendre le contrôle à la boucle d'événements de l'appelant. Lorsque l'arbre des tâches est lancé, ce signal est émis avec la valeur count de 0, et émis ultérieurement à chaque saut de valeur asyncCount() avec une valeur count mise à jour. Chaque signal envoyé (à l'exception du signal initial avec la valeur 0) garantit que l'arbre des tâches fonctionne toujours de manière asynchrone après l'émission.

Voir également asyncCount().

void QTaskTree::cancel()

Annule l'exécution de l'arbre des tâches en cours.

Annule immédiatement toutes les tâches en cours. Toutes les tâches et tous les groupes en cours d'exécution se terminent par une erreur, en invoquant leur gestionnaire done à l'adresse DoneWith::Cancel. Les gestionnaires onStorageDone() des magasins sont également invoqués. Les signaux progressValueChanged() sont également envoyés. On peut toujours compter sur ce comportement.

La fonction cancel() est exécutée de manière synchrone, de sorte qu'après un appel à cancel(), toutes les tâches en cours sont terminées et l'arbre est déjà annulé. Il est garanti que cancel() s'exécutera rapidement, sans attente bloquante pour les tâches en cours d'exécution, à condition que les tâches utilisées implémentent leurs destructeurs de manière non bloquante.

Lorsque l'arbre des tâches est vide, c'est-à-dire construit avec un constructeur par défaut, un appel à cancel() est sans effet et le message d'avertissement correspondant est émis.

Dans le cas contraire, si l'arbre des tâches n'a pas été démarré, l'appel à cancel() est ignoré.

Voir aussi ~QTaskTree().

[signal] void QTaskTree::done(QtTaskTree::DoneWith result)

Ce signal est émis lorsque l'arbre des tâches a terminé, en transmettant le dernier result de l'exécution. L'arbre des tâches n'appelle aucun gestionnaire et n'émet plus aucun signal après l'émission de ce signal.

Voir aussi started().

[override virtual protected] bool QTaskTree::event(QEvent *event)

Réimplémente : QObject::event(QEvent *e).

bool QTaskTree::isRunning() const

Renvoie true si l'arbre des tâches est en cours d'exécution ; sinon, renvoie false.

Voir aussi start() et cancel().

template <typename StorageStruct, typename Handler> void QTaskTree::onStorageDone(const QtTaskTree::Storage<StorageStruct> &storage, Handler &&handler)

Installe un stockage fait handler pour que storage puisse récupérer les données finales de manière dynamique à partir de l'arborescence des tâches en cours d'exécution.

Le StorageHandler prend une référence const à l'instance StorageStruct:

statique QByteArray load(const QString &fileName) { ... }  Storage<QByteArray> storage ;const auto onLoaderSetup = [](QThreadFunction<QByteArray> &task) { task.setThreadFunctionData(&load, "foo.txt") ; } ;const auto onLoaderDone = [storage](const QThreadFunction<QByteArray> &task) { *storage = task.result() ; } ;const Group root { storage,    QThreadFunctionTask(onLoaderSetup, onLoaderDone, CallDoneFlag::OnSuccess) } ;QTaskTree taskTree(root) ;auto collectStorage = [](const QByteArray &storage){    qDebug() << "final content" << storage;
} ; taskTree.onStorageDone(storage, collectStorage) ; taskTree.start() ;

Lorsque l'arbre des tâches en cours d'exécution est sur le point de quitter un Group dans lequel est placé le storage, il détruit une instance StorageStruct. Juste avant que l'instance StorageStruct ne soit détruite, et après que tous les gestionnaires possibles de ce groupe ont été appelés, l'arbre des tâches invoque le handler passé. Cela permet de lire dynamiquement le contenu final du stockage donné et de le traiter en dehors de l'arbre des tâches.

Ce gestionnaire est également appelé lorsque l'arbre en cours d'exécution est annulé. Cependant, il n'est pas appelé lorsque l'arbre en cours d'exécution est détruit.

Voir aussi onStorageSetup().

template <typename StorageStruct, typename Handler> void QTaskTree::onStorageSetup(const QtTaskTree::Storage<StorageStruct> &storage, Handler &&handler)

Installe une configuration de stockage handler pour que storage transmette dynamiquement les données initiales à l'arbre des tâches en cours d'exécution.

Le site StorageHandler fait référence à l'instance StorageStruct:

static void save(const QString &fileName, const QByteArray &array) { ... }

Storage<QByteArray> storage;

const auto onSaverSetup = [storage](QThreadFunction<QByteArray> &task) {
    task.setThreadFunctionData(&save, "foo.txt", *storage);
};

const Group root {
    storage,
    QThreadFunctionTask(onSaverSetup)
};

QTaskTree taskTree(root);
auto initStorage = [](QByteArray &storage){
    storage = "initial content";
};
taskTree.onStorageSetup(storage, initStorage);
taskTree.start();

Lorsque l'arbre des tâches en cours d'exécution entre dans un groupe dans lequel storage est placé, il crée une instance StorageStruct, prête à être utilisée dans ce groupe. Juste après la création de l'instance StorageStruct et avant qu'un gestionnaire de ce groupe ne soit appelé, l'arborescence des tâches invoque l'instance handler qui lui a été transmise. Cela permet de définir dynamiquement le contenu initial du stockage donné. Plus tard, lorsque le gestionnaire d'un groupe est appelé, l'arbre des tâches active le stockage créé et initialisé, de sorte qu'il soit disponible dans le gestionnaire de n'importe quel groupe.

Voir aussi onStorageDone().

qsizetype QTaskTree::progressMaximum() const

Renvoie le maximum de progressValue().

Voir aussi progressValue().

qsizetype QTaskTree::progressValue() const

Renvoie la valeur actuelle de la progression, qui se situe entre 0 et progressMaximum().

Le nombre renvoyé indique combien de tâches ont déjà été terminées, annulées ou ignorées pendant l'exécution de l'arborescence des tâches. Au démarrage de l'arbre des tâches, ce nombre est égal à 0. Lorsque l'arbre des tâches est terminé, ce nombre est toujours égal à progressMaximum().

Voir également progressMaximum() et progressValueChanged().

[signal] void QTaskTree::progressValueChanged(qsizetype value)

Ce signal est émis lorsque l'arbre des tâches en cours d'exécution a terminé, annulé ou ignoré certaines tâches. Le message value indique le nombre total de tâches terminées, annulées ou ignorées. Lorsque l'arbre des tâches est démarré et après l'émission du signal started(), ce signal est émis avec une valeur initiale value de 0. Lorsque l'arbre des tâches est sur le point de se terminer et avant l'émission du signal done(), ce signal est émis avec une valeur finale value de progressMaximum().

Voir également progressValue() et progressMaximum().

QtTaskTree::DoneWith QTaskTree::runBlocking()

Exécute une boucle d'événement locale avec QEventLoop::ExcludeUserInputEvents et démarre l'arbre des tâches.

Renvoie DoneWith::Success si l'arbre des tâches s'est terminé avec succès ; sinon, renvoie DoneWith::Error.

Voir aussi start().

[static] QtTaskTree::DoneWith QTaskTree::runBlocking(const QtTaskTree::Group &recipe)

Construit un arbre des tâches temporaire à l'aide de recipe et l'exécute en le bloquant.

Retourne DoneWith::Success si l'arbre des tâches s'est terminé avec succès ; sinon, retourne DoneWith::Error.

Voir aussi start().

QtTaskTree::DoneWith QTaskTree::runBlocking(const QFuture<void> &future)

L'adresse future transmise est utilisée pour écouter l'événement d'annulation. Lorsque l'arbre des tâches est annulé, cette méthode annule l'événement future.

[static] QtTaskTree::DoneWith QTaskTree::runBlocking(const QtTaskTree::Group &recipe, const QFuture<void> &future)

L'adresse future transmise est utilisée pour écouter l'événement d'annulation. Lorsque l'arbre des tâches est annulé, cette méthode annule le future passé.

void QTaskTree::setRecipe(const QtTaskTree::Group &recipe)

Définit un site recipe donné pour l'arbre des tâches. Une fois l'arborescence démarrée, elle exécute les tâches contenues dans le site recipe et gère les tâches terminées en fonction de la description transmise.

Voir aussi QTaskTree(const QtTaskTree::Group &recipe, QObject *parent = nullptr) et start().

void QTaskTree::start()

Démarre l'arbre des tâches.

Utilisez setRecipe() ou le constructeur pour définir la description déclarative selon laquelle l'arbre des tâches exécutera les tâches contenues et traitera les tâches terminées.

Lorsque l'arbre des tâches est vide, c'est-à-dire construit avec un constructeur par défaut, un appel à start() est sans effet et le message d'avertissement correspondant est émis.

Sinon, lorsque l'arbre des tâches est déjà en cours d'exécution, un appel à start() est ignoré et le message d'avertissement correspondant est émis.

Dans le cas contraire, l'arbre des tâches est démarré.

L'arborescence des tâches démarrée peut se terminer de manière synchrone, par exemple lorsque le gestionnaire de démarrage du groupe principal renvoie SetupResult::StopWithError. Pour cette raison, la connexion au signal "done" doit être établie avant d'appeler start(). Utilisez isRunning() pour détecter si l'arbre des tâches est toujours en cours d'exécution après un appel à start().

L'implémentation de l'arbre des tâches repose sur la boucle d'événements en cours d'exécution. Assurez-vous que vous avez un QEventLoop, QCoreApplication, ou l'une de ses sous-classes en cours d'exécution (ou sur le point d'être exécutée) lorsque vous appelez cette méthode.

Voir aussi QTaskTree(const QtTaskTree::Group &recipe, QObject *parent = nullptr), setRecipe(), isRunning(), et cancel().

[signal] void QTaskTree::started()

Ce signal est émis lorsque l'arbre des tâches est démarré. L'émission de ce signal est suivie de manière synchrone par le signal progressValueChanged() avec une valeur initiale de 0.

Voir également start() et done().

qsizetype QTaskTree::taskCount() const

Renvoie le nombre de tâches asynchrones contenues dans la recette stockée.

Voir également setRecipe() et progressMaximum().