QtTaskTree::QTaskTree Class

Documentation des fonctions membres

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

Construit une arborescence de tâches vide à partir d'une description de l'parent. Utilisez la méthode setRecipe() pour fournir une description déclarative indiquant comment l'arborescence de tâches doit exécuter les tâches et comment elle doit gérer les tâches terminées.

Le lancement d’un arbre de tâches vide n’a aucun effet et un message d’avertissement correspondant s’affiche.

Voir également setRecipe() et start().

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

Construit une arborescence de tâches à partir d'une description donnée ( recipe ) et d'une liste de tâches ( parent). Une fois l'arborescence de tâches lancée, elle exécute les tâches contenues dans la liste des tâches ( recipe ) et gère les tâches terminées conformément à la description fournie.

Voir également setRecipe() et start().

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

Détruit l'arborescence des tâches.

Lorsque l'arborescence des tâches est en cours d'exécution au moment de sa destruction, elle annule immédiatement toutes les tâches en cours. Dans ce cas, aucun gestionnaire n'est appelé, pas même les gestionnaires « done » des groupes et des tâches, ni les gestionnaires « onStorageDone() ». L'arborescence des tâches n'émet pas non plus de signaux depuis le destructeur, pas même les signaux « done() » ou « progressValueChanged() ». On peut toujours se fier à ce comportement. Il est tout à fait sûr de détruire l'arborescence des tâches en cours d'exécution.

La destruction de l’arborescence de tâches en cours d’exécution est une pratique courante. Il est garanti que la destruction s’effectuera rapidement, sans qu’il soit nécessaire d’attendre la fin des tâches en cours d’exécution, à condition que les tâches utilisées implémentent leurs destructeurs de manière non bloquante.

Voir également cancel().

qsizetype QTaskTree::asyncCount() const

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

La valeur renvoyée indique le nombre de fois où le contrôle revient à la boucle d'événements de l'appelant pendant l'exécution de l'arborescence des tâches. Au départ, cette valeur est 0. Si l’exécution de l’arborescence de tâches se termine de manière entièrement synchrone, cette valeur reste 0. Si l’arborescence de tâches contient des tâches asynchrones qui ont été lancées avec succès lors d’un appel à start(), cette valeur est incrémentée à 1 juste avant la fin de l’appel à start(). Par la suite, lorsqu’une tâche asynchrone se termine et que d’éventuelles continuations sont lancées, cette valeur est à nouveau incrémentée. L’incrémentation se poursuit jusqu’à ce que l’arborescence des tâches se termine. Lorsque l’arborescence des tâches émet le signal ` done()`, l’incrémentation s’arrête. Le signal ` asyncCountChanged()` est émis à chaque incrémentation de cette valeur.

Voir également asyncCountChanged().

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

Ce signal est émis lorsque l’arborescence de tâches en cours d’exécution est sur le point de restituer le contrôle à la boucle d’événements de l’appelant. Lorsque l’arborescence de tâches est lancée, ce signal est émis avec une valeur d’ count de 0, puis réémis à chaque incrément de la valeur asyncCount() avec une valeur de count mise à jour. Chaque signal envoyé (à l’exception du premier, dont la valeur est 0) garantit que l’arborescence des tâches continue de s’exécuter de manière asynchrone après son émission.

Voir également asyncCount().

void QTaskTree::cancel()

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

Annule immédiatement toutes les tâches en cours d’exécution. Toutes les tâches et tous les groupes en cours d’exécution se terminent par une erreur, ce qui déclenche leurs gestionnaires « done » avec la valeur « DoneWith::Cancel ». Les gestionnaires « onStorageDone() » des stockages sont également appelé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 d’exécution sont terminées et l’arborescence est déjà annulée. Il est garanti que `cancel()` s’exécutera rapidement, sans attente bloquante de la fin des 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’arborescence de tâches est vide, c’est-à-dire construite avec un constructeur par défaut, un appel à `cancel()` n’a aucun effet et un message d’avertissement correspondant est émis.

Dans le cas contraire, lorsque l’arborescence de tâches n’a pas été lancée, l’appel à `cancel()` est ignoré.

Voir également ` ~QTaskTree()`.

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

Ce signal est émis lorsque l'arborescence des tâches est terminée, en transmettant l'result finale de l'exécution. Une fois ce signal émis, l'arborescence des tâches n'appelle plus aucun gestionnaire et n'émet plus aucun 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'arborescence des tâches est en cours d'exécution ; sinon, renvoie « false ».

Voir également start() et cancel().

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

Installe un système de stockage de type « done- handler » pour l'storage, afin de récupérer dynamiquement les données finales à partir de l'arborescence des tâches en cours d'exécution.

L’ StorageHandler e prend une référence d’ const à l’instance StorageStruct:

static 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’arborescence de tâches en cours d’exécution est sur le point de quitter un Group dans lequel se trouve l’ storage, elle détruit une instance StorageStruct. Juste avant la destruction de l’instance StorageStruct, et après l’appel de tous les gestionnaires possibles de ce groupe, l’arborescence de tâches invoque la fonction handler qui lui a été transmise. Cela permet de lire dynamiquement le contenu final du stockage donné et de le traiter ultérieurement en dehors de l’arborescence de tâches.

Ce gestionnaire est également appelé lorsque l’arborescence d’exécution est annulée. En revanche, il n’est pas appelé lorsque l’arborescence d’exécution est détruite.

Voir également onStorageSetup().

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

Installe une configuration de stockage handler permettant à l'storage de transmettre dynamiquement les données initiales à l'arborescence des tâches en cours d'exécution.

L'StorageHandler prend une référence à l'instance de l'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'arborescence des tâches en cours d'exécution entre dans un groupe où se trouve l'storage, celle-ci crée une instance de StorageStruct, prête à être utilisée au sein de ce groupe. Juste après la création de l'instance ` StorageStruct `, et avant que le moindre gestionnaire de ce groupe ne soit appelé, l’arborescence des tâches invoque la méthode ` handler` qui lui a été transmise. Cela permet de configurer dynamiquement le contenu initial du stockage donné. Par la suite, lorsqu’un gestionnaire de groupe est appelé, l’arborescence des tâches active le stockage créé et initialisé, afin qu’il soit disponible au sein du gestionnaire de n’importe quel groupe.

Voir également onStorageDone().

qsizetype QTaskTree::progressMaximum() const

Renvoie la valeur maximale de ` progressValue()`.

Voir également progressValue().

qsizetype QTaskTree::progressValue() const

Renvoie la valeur de progression actuelle, comprise entre 0 et progressMaximum().

Le nombre renvoyé indique le nombre de tâches déjà terminées, annulées ou ignorées pendant l'exécution de l'arborescence des tâches. Au démarrage de l'arborescence des tâches, ce nombre est défini sur 0. À la fin de l'arborescence des tâches, ce nombre est toujours égal à progressMaximum().

Voir également progressMaximum() et progressValueChanged().

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

Ce signal est émis lorsque l'arborescence des tâches en cours s'est terminée, a été annulée ou a ignoré certaines tâches. La fonction ` value ` renvoie le nombre total actuel de tâches terminées, annulées ou ignorées. Lorsque l'arborescence de tâches est lancée, et après l'émission du signal ` started()`, ce signal est émis avec une valeur initiale ` value ` de ` 0`. Lorsque l'arborescence de 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énements locale avec QEventLoop::ExcludeUserInputEvents et lance l'arborescence des tâches.

Renvoie ` DoneWith::Success ` si l'arborescence de tâches s'est terminée avec succès ; sinon, renvoie ` DoneWith::Error`.

Voir également start().

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

Crée une arborescence de tâches temporaire à partir de l'recipe fournie et l'exécute en mode bloquant.

Renvoie ` DoneWith::Success ` si l'arborescence de tâches s'est terminée avec succès ; sinon, renvoie ` DoneWith::Error`.

Voir également start().

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

L'objet ` future ` passé en paramètre sert à écouter l'événement « cancel ». Lorsque l'arborescence des tâches est annulée, cette méthode annule l'objet ` future` passé en paramètre.

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

L'objet ` future ` passé en paramètre sert à écouter l'événement d'annulation. Lorsque l'arborescence des tâches est annulée, cette méthode annule l'objet ` future` passé en paramètre.

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

Définit une « recipe » donnée pour l’arborescence des tâches. Une fois l’arborescence des tâches lancée, celle-ci exécute les tâches contenues dans l’« recipe » et gère les tâches terminées conformément à la description fournie.

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

void QTaskTree::start()

Lance l'arborescence des tâches.

Utilisez la méthode setRecipe() ou le constructeur pour définir la description déclarative selon laquelle l'arborescence de tâches exécutera les tâches qu'elle contient et gérera les tâches terminées.

Lorsque l’arborescence de tâches est vide, c’est-à-dire qu’elle a été construite avec un constructeur par défaut, l’appel à start() n’a aucun effet et un message d’avertissement correspondant s’affiche.

Sinon, lorsque l’arborescence de 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’arborescence de tâches est lancée.

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

L’implémentation de l’arborescence de tâches repose sur la boucle d’événements en cours d’exécution. Assurez-vous qu’un objet ` QEventLoop`, ` QCoreApplication` ou l’une de ses sous-classes est en cours d’exécution (ou sur le point de l’être) lorsque vous appelez cette méthode.

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

[signal] void QTaskTree::started()

Ce signal est émis lors du lancement de l'arborescence des tâches. 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 enregistrée.

Voir également setRecipe() et progressMaximum().