Tâche simultanée

QtConcurrent::task fournit une interface alternative pour exécuter une tâche dans un thread séparé. La valeur de retour de la fonction est disponible via l'API QFuture.

Si vous souhaitez simplement exécuter une fonction dans un thread séparé sans ajuster aucun paramètre, utilisez QtConcurrent::run car cela vous permet d'écrire moins de code. L'API QtConcurrent::task est conçue pour les cas où vous devez effectuer des configurations supplémentaires.

Cette fonction fait partie du Qt Concurrent cadre.

Optimiser les inclusions

Si vous incluez l'en-tête <QtConcurrent>, l'ensemble du module Qt Concurrent et l'ensemble du module Qt Core seront inclus, ce qui peut augmenter les temps de compilation et la taille des binaires. Pour utiliser la fonction QtConcurrent::task(), vous pouvez inclure un en-tête plus spécifique :

#include <QtConcurrentTask>

Fluent interface

La fonction QtConcurrent::task renvoie une instance d'une classe auxiliaire appelée QtConcurrent::QTaskBuilder. Normalement, vous n'avez pas besoin de créer manuellement une instance de cette classe. Le site QtConcurrent::QTaskBuilder fournit une interface permettant d'ajuster différents paramètres de tâches à la manière d'une chaîne. Cette approche est connue sous le nom d'interface fluide.

Vous pouvez simplement définir les paramètres dont vous avez besoin et lancer une tâche. Pour finaliser la configuration d'une tâche, vous devez invoquer QtConcurrent::QTaskBuilder::spawn. Cette fonction est non bloquante (c'est-à-dire qu'elle renvoie immédiatement un objet futur), mais il n'est pas garanti que la tâche démarre immédiatement. Vous pouvez utiliser les classes QFuture et QFutureWatcher pour surveiller l'état de la tâche.

Voir plus d'exemples et d'explications ci-dessous.

Exécution d'une tâche dans un autre thread

Pour exécuter une fonction dans un autre thread, utilisez QtConcurrent::QTaskBuilder::spawn:

QtConcurrent::task([]{ qDebug("Hello, world!"); }).spawn();

Cela exécutera une fonction lambda dans un thread séparé obtenu à partir de la classe par défaut QThreadPool.

Transmission d'arguments à la tâche

L'invocation d'une fonction avec des arguments se fait en les passant à QtConcurrent::QTaskBuilder::withArguments:

auto task = [](const QString &s){ qDebug() << ("Hello, " + s); };
QtConcurrent::task(std::move(task))
    .withArguments("world!")
    .spawn();

Une copie de chaque argument est effectuée au moment où QtConcurrent::QTaskBuilder::withArguments est appelé, et ces valeurs sont transmises au thread lorsqu'il commence à exécuter la tâche. Les modifications apportées aux arguments après l'appel à QtConcurrent::QTaskBuilder::withArguments ne sont pas visibles par le thread.

Si vous souhaitez exécuter une fonction qui accepte des arguments par référence, vous devez utiliser les fonctions auxiliaires std::ref/cref. Ces fonctions créent des enveloppes fines autour des arguments passés :

QString s("Hello, ");
QtConcurrent::task([](QString &s){ s.append("world!"); })
    .withArguments(std::ref(s))
    .spawn();

Assurez-vous que tous les objets enveloppés vivent suffisamment longtemps. Il est possible d'obtenir un comportement indéfini si une tâche survit à l'objet enveloppé par std::ref/cref.

Renvoi des valeurs de la tâche

Vous pouvez obtenir le résultat d'une tâche avec l'API QFuture:

auto future = QtConcurrent::task([]{ return 42; }).spawn();
auto result = future.result(); // result == 42

Notez que QFuture::result() est un appel bloquant, il attend que le résultat soit disponible. Utilisez QFutureWatcher pour recevoir une notification lorsque l'exécution de la tâche est terminée et que le résultat est disponible.

Si vous souhaitez transmettre un résultat à une autre tâche asynchrone, vous pouvez utiliser QFuture::then() pour créer une chaîne de tâches dépendantes. Voir la documentation QFuture pour plus de détails.

Fonctionnalités supplémentaires de l'API

Utilisation de différents types d'objets appelables

À proprement parler, vous pouvez utiliser n'importe quel type de tâches et d'arguments satisfaisant aux conditions suivantes :

std::is_invocable_v<std::decay_t<Task>, std::decay_t<Args>...>

Vous pouvez utiliser une fonction libre :

QVariant value(42);
auto result = QtConcurrent::task([](const QVariant &var){return qvariant_cast<int>(var);})
                  .withArguments(value)
                  .spawn()
                  .result(); // result == 42

Vous pouvez utiliser une fonction membre :

QString result("Hello, world!");

QtConcurrent::task(&QString::chop)
    .withArguments(&result, 8)
    .spawn()
    .waitForFinished(); // result == "Hello"

Vous pouvez utiliser un objet appelable avec un opérateur() :

auto result = QtConcurrent::task(std::plus<int>())
                  .withArguments(40, 2)
                  .spawn()
                  .result() // result == 42

Si vous souhaitez utiliser un objet appelable existant, vous devez soit le copier/déplacer vers QtConcurrent::task, soit l'envelopper avec std::ref/cref :

struct CallableWithState
{
    void operator()(int newState) { state = newState; }

    // ...
};

// ...

CallableWithState object;

QtConcurrent::task(std::ref(object))
   .withArguments(42)
   .spawn()
   .waitForFinished(); // The object's state is set to 42

Utilisation d'un pool de threads personnalisé

Vous pouvez spécifier un pool de threads personnalisé :

QThreadPool pool;
QtConcurrent::task([]{ return 42; }).onThreadPool(pool).spawn();

Définition de la priorité d'une tâche

Vous pouvez définir la priorité d'une tâche :

QtConcurrent::task([]{ return 42; }).withPriority(10).spawn();

Si vous n'avez pas besoin d'un objet future, vous pouvez appeler QtConcurrent::QTaskBuilder::spawn(QtConcurrent::FutureResult::Ignore) :

QtConcurrent::task([]{ qDebug("Hello, world!"); }).spawn(FutureResult::Ignore);

Vous pouvez accéder à l'objet promise associé à la tâche en définissant un argument supplémentaire de type QPromise<T> & à l'intérieur de la fonction. Cet argument supplémentaire doit être le premier argument passé à la fonction, et comme en mode Concurrent Run With Promise, la fonction est censée renvoyer le type void. La communication des résultats est effectuée par l'intermédiaire de l'API QPromise:

void increment(QPromise<int> &promise, int i)
{
    promise.addResult(i + 1);
}

int result = QtConcurrent::task(&increment).withArguments(10).spawn().result(); // result == 11