QtFuture Namespace

Documentation de la fonction

template < typename Sender, typename Signal, typename = QtPrivate::EnableIfInvocable<Sender, Signal> > QFuture<QtFuture::ArgsType<Signal>> QtFuture::connect(Sender *sender, Signal signal)

Crée et renvoie un objet ` QFuture ` qui deviendra disponible lorsque l'objet ` sender ` émettra l'événement ` signal`. Si l'objet ` signal ` ne prend aucun argument, un objet ` QFuture` de type `<void>` est renvoyé. Si la méthode signal prend un seul argument, l’objet QFuture résultant sera renseigné avec la valeur de cet argument. Si la méthode signal prend plusieurs arguments, l’objet QFuture résultant sera renseigné avec un std::tuple contenant les valeurs des arguments du signal. Si l’objet sender est détruit avant que le signal signal ne soit émis, l’objet QFuture résultant sera annulé.

Prenons par exemple l’objet suivant :

class Object : public QObject
{
    Q_OBJECT
    //...
signals:
    void noArgSignal();
    void singleArgSignal(int value);
    void multipleArgs(int value1, double value2, const QString &value3);
};

Nous pouvons connecter ses signaux à des objets ` QFuture ` de la manière suivante :

Object object;
QFuture<void> voidFuture = QtFuture::connect(&object, &Object::noArgSignal);
QFuture<int> intFuture = QtFuture::connect(&object, &Object::singleArgSignal);

using Args = std::tuple<int, double, QString>;
QFuture<Args> tupleFuture = QtFuture::connect(&object, &Object::multipleArgs);

Nous pouvons également enchaîner des continuations qui s’exécuteront lorsqu’un signal est émis :

QtFuture::connect(&object, &Object::singleArgSignal).then([](int value) {
    // do something with the value
});

Vous pouvez également lancer la continuation dans un nouveau thread ou un pool de threads personnalisé à l’aide des politiques d’ QtFuture::Launch. Par exemple :

QtFuture::connect(&object, &Object::singleArgSignal).then(QtFuture::Launch::Async, [](int value) {
    // this will run in a new thread
});

Le fait de lever une exception depuis un slot appelé par la connexion signal-slot de Qt est considéré comme un comportement indéfini s’il n’est pas géré au sein du slot. Mais avec `QFuture::connect()`, vous pouvez lever et gérer des exceptions depuis les continuations :

QtFuture::connect(&object, &Object::singleArgSignal).then([](int value) {
    //...
    throw std::exception();
    //...
}).onFailed([](const std::exception &e) {
    // handle the exception
}).onFailed([] {
    // handle other exceptions
});

Voir également QFuture et QFuture::then().

[since 6.1] template <typename T = void> QFuture<T> QtFuture::makeExceptionalFuture(const QException &exception)

Crée et renvoie un objet ` QFuture ` contenant déjà une exception de type ` exception`.

QException e;
auto f = QtFuture::makeExceptionalFuture<int>(e);
...
try {
    f.result(); // throws QException
} catch (QException &) {
    // handle exception here
}

Cette fonction a été introduite dans Qt 6.1.

Voir également QFuture, QException, QtFuture::makeReadyVoidFuture() et QtFuture::makeReadyValueFuture().

[since 6.1] template <typename T = void> QFuture<T> QtFuture::makeExceptionalFuture(std::__exception_ptr::exception_ptr exception)

Crée et renvoie un objet ` QFuture ` contenant déjà une exception de type ` exception`.

struct TestException
{
};
...
auto exception = std::make_exception_ptr(TestException());
auto f = QtFuture::makeExceptionalFuture<int>(exception);
...
try {
    f.result(); // throws TestException
} catch (TestException &) {
    // handle exception here
}

Cette fonction a été introduite dans Qt 6.1.

Voir également QFuture, QException, QtFuture::makeReadyVoidFuture() et QtFuture::makeReadyValueFuture().

[since 6.6] template <typename Container> requires if_container_with_input_iterators<Container> QFuture<QtFuture::ContainedType<Container>> QtFuture::makeReadyRangeFuture(Container &&container)

Prend un conteneur d'entrée container et renvoie un QFuture contenant plusieurs résultats de type ContainedType initialisés à partir des valeurs de container.

const std::vector<int> values{1, 2, 3};
auto f = QtFuture::makeReadyRangeFuture(values);
    ...
const int count = f.resultCount(); // count == 3
const auto results = f.results(); // results == { 1, 2, 3 }

Contraintes

Ne participe à la résolution des surcharges que si Container dispose d’itérateurs d’entrée.

Cette fonction a été introduite dans Qt 6.6.

Voir également QFuture, QtFuture::makeReadyVoidFuture(), QtFuture::makeReadyValueFuture() et QtFuture::makeExceptionalFuture().

[since 6.6] template <typename ValueType> QFuture<ValueType> QtFuture::makeReadyRangeFuture(std::initializer_list<ValueType> values)

Renvoie une instance de ` QFuture ` contenant plusieurs résultats de type ` ValueType `, initialisés à partir de la liste d'initialisation d'entrée ` values`.

auto f = QtFuture::makeReadyRangeFuture({1, 2, 3});
    ...
const int count = f.resultCount(); // count == 3
const auto results = f.results(); // results == { 1, 2, 3 }

Cette fonction a été introduite dans Qt 6.6.

Voir également QFuture, QtFuture::makeReadyVoidFuture(), QtFuture::makeReadyValueFuture() et QtFuture::makeExceptionalFuture().

[since 6.6] template <typename T> QFuture<std::decay_t<T>> QtFuture::makeReadyValueFuture(T &&value)

Crée et renvoie un objet ` QFuture ` contenant déjà un résultat ` value`. L'objet ` QFuture ` renvoyé est de type `std::decay_t<T>`, où `T` n'est pas de type `void`. L'objet ` QFuture ` renvoyé sera déjà dans l'état « terminé ».

auto f = QtFuture::makeReadyValueFuture(std::make_unique<int>(42));
//...
const int result = *f.takeResult(); // result == 42

Cette fonction a été introduite dans Qt 6.6.

Voir également QFuture, QtFuture::makeReadyRangeFuture(), QtFuture::makeReadyVoidFuture() et QtFuture::makeExceptionalFuture().

[since 6.6] QFuture<void> QtFuture::makeReadyVoidFuture()

Crée et renvoie une instance de type ` QFuture` de type `void`. Une telle instance de type ` QFuture ` ne peut stocker aucun résultat. Elle permet de consulter l'état du calcul. L'instance de type ` QFuture ` renvoyée se trouvera déjà à l'état « terminé ».

auto f = QtFuture::makeReadyVoidFuture();
//...
const bool started = f.isStarted(); // started == true
const bool running = f.isRunning(); // running == false
const bool finished = f.isFinished(); // finished == true

Cette fonction a été introduite dans Qt 6.6.

Voir également QFuture, QFuture::isStarted(), QFuture::isRunning(), QFuture::isFinished(), QtFuture::makeReadyValueFuture(), QtFuture::makeReadyRangeFuture() et QtFuture::makeExceptionalFuture().

[since 6.3] template <typename OutputSequence, typename... Futures> QFuture<OutputSequence> QtFuture::whenAll(Futures &&... futures)

Renvoie un nouvel objet ` QFuture ` qui réussit lorsque tous les ` futures ` ayant pour objet des types arbitraires sont terminés. ` OutputSequence ` est une séquence de `futures` terminés. Le type de ses entrées est ` std::variant<Futures...>`. Pour chaque ` QFuture<T> ` passé à ` whenAll()`, l’entrée à la position correspondante dans ` OutputSequence ` sera un ` std::variant ` contenant ce ` QFuture<T>`, dans son état terminé. Si le type de ` OutputSequence ` n’est pas spécifié, les `futures` résultants seront renvoyés dans une ` QList ` de type ` std::variant<Futures...>`. Par exemple :

QFuture<int> intFuture /*...*/;
QFuture<QString> stringFuture /*...*/;
QFuture<void> voidFuture /*...*/;

using FuturesVariant = std::variant<QFuture<int>, QFuture<QString>, QFuture<void>>;

// whenAll has type QFuture<QList<FuturesVariant>>
auto whenAll = QtFuture::whenAll(intFuture, stringFuture, voidFuture);

// whenAllVector has type QFuture<std::vector<FuturesVariant>>
auto whenAllVector =
        QtFuture::whenAll<std::vector<FuturesVariant>>(intFuture, stringFuture, voidFuture);

Le « future » renvoyé s’achève toujours avec succès une fois que tous les « futures » spécifiés sont terminés. Peu importe que l’un de ces « futures » se termine par une erreur ou soit annulé. Vous pouvez utiliser ` .then() ` pour traiter les « futures » terminés une fois que le « future » renvoyé par ` whenAll() ` a abouti :

QFuture<int> intFuture /*...*/;
QFuture<QString> stringFuture /*...*/;
QFuture<void> voidFuture /*...*/;

using FuturesVariant = std::variant<QFuture<int>, QFuture<QString>, QFuture<void>>;

QtFuture::whenAll(intFuture, stringFuture, voidFuture)
        .then([](const QList<FuturesVariant> &results) {
            //...
            for (auto result : results)
            {
                // assuming handleResult() is overloaded based on the QFuture type
                std::visit([](auto &&future) { handleResult(future); }, result);
            }
            //...
        });

Cette fonction a été introduite dans Qt 6.3.

[since 6.3] template <typename OutputSequence, typename InputIt> QFuture<OutputSequence> QtFuture::whenAll(InputIt first, InputIt last)

Renvoie un nouvel objet ` QFuture ` qui réussit lorsque tous les `futures` de ` first ` à ` last ` sont terminés. ` first ` et ` last ` sont des itérateurs vers une séquence de `futures` de type ` T`. ` OutputSequence ` est une séquence contenant tous les `futures` terminés de ` first ` à ` last`, classés dans le même ordre que dans l’entrée. Si le type de ` OutputSequence ` n’est pas spécifié, les `futures` résultants seront renvoyés dans une ` QList ` de type ` QFuture<T>`. Par exemple :

QList<QFuture<int>> inputFutures {/*...*/};

// whenAll has type QFuture<QList<QFuture<int>>>
auto whenAll = QtFuture::whenAll(inputFutures.begin(), inputFutures.end());

// whenAllVector has type QFuture<std::vector<QFuture<int>>>
auto whenAllVector =
        QtFuture::whenAll<std::vector<QFuture<int>>>(inputFutures.begin(), inputFutures.end());

Si first est égal à last, cette fonction renvoie un « ready QFuture » contenant un « OutputSequence » vide.

Le future renvoyé s'achève toujours avec succès une fois que tous les futures spécifiés sont terminés. Peu importe que l'un de ces futures s'achève par une erreur ou soit annulé. Vous pouvez utiliser ` .then() ` pour traiter les futures terminés une fois que le future renvoyé par ` whenAll() ` a abouti :

QList<QFuture<int>> inputFutures {/*...*/};

QtFuture::whenAll(inputFutures.begin(), inputFutures.end())
        .then([](const QList<QFuture<int>> &results) {
            for (auto future : results) {
                if (future.isCanceled())
                {
                    // handle the cancellation (possibly due to an exception)
                }
                else
                {
                    // do something with the result
                }
            }
        });

Cette fonction a été introduite dans Qt 6.3.

[since 6.3] template <typename... Futures> QFuture<std::variant<std::decay_t<Futures>...>> QtFuture::whenAny(Futures &&... futures)

Renvoie un nouvel objet ` QFuture ` qui aboutit dès que l’un des ` futures ` est terminé. ` futures ` peut encapsuler des types arbitraires. Le `future` renvoyé encapsule la valeur de type ` std::variant<Futures...> `, qui à son tour encapsule le premier ` QFuture ` terminé issu de ` futures`. Vous pouvez utiliser `std::variant::index()` pour déterminer l’index du `future` dans la séquence des ` futures ` qui s’est terminé en premier.

Le « future » renvoyé s’achève toujours avec succès une fois que le premier « future » parmi ceux spécifiés s’est achevé. Peu importe que ce premier « future » se termine par une erreur ou soit annulé. Vous pouvez utiliser ` .then() ` pour traiter le résultat une fois que le « future » renvoyé par ` whenAny() ` a abouti :

QFuture<int> intFuture /*...*/;
QFuture<QString> stringFuture /*...*/;
QFuture<void> voidFuture /*...*/;

using FuturesVariant = std::variant<QFuture<int>, QFuture<QString>, QFuture<void>>;

QtFuture::whenAny(intFuture, stringFuture, voidFuture).then([](const FuturesVariant &result) {
    //...
    // assuming handleResult() is overloaded based on the QFuture type
    std::visit([](auto &&future) { handleResult(future); }, result);
    //...
});

Cette fonction a été introduite dans Qt 6.3.

[since 6.3] template <typename T, typename InputIt> QFuture<QtFuture::WhenAnyResult<T>> QtFuture::whenAny(InputIt first, InputIt last)

Renvoie un nouvel objet ` QFuture ` qui se résout avec succès dès qu’un des `futures` compris entre ` first ` et ` last ` est résolu. ` first ` et ` last ` sont des itérateurs sur une séquence de `futures` de type ` T`. Le `future` renvoyé contient une valeur de type ` QtFuture::WhenAnyResult<T> `, qui contient à son tour l’index du premier ` QFuture ` résolu ainsi que le ` QFuture ` lui-même. Si first est égal à last, cette fonction renvoie un QFuture prêt à l’emploi dont le champ index de la structure QtFuture::WhenAnyResult contient -1 et dont le champ future contient un QFuture<T> construit par défaut. Notez qu’un QFuture construit par défaut est un « future » terminé se trouvant dans un état « cancelled ».

Le « future » renvoyé s’achève toujours avec succès une fois que le premier « future » parmi ceux spécifiés s’est achevé. Peu importe que ce premier « future » s’achève avec une erreur ou soit annulé. Vous pouvez utiliser ` .then() ` pour traiter le résultat une fois que le « future » renvoyé par ` whenAny() ` a abouti :

QList<QFuture<int>> inputFutures /*...*/;

QtFuture::whenAny(inputFutures.begin(), inputFutures.end())
        .then([](const QtFuture::WhenAnyResult<int> &result) {
            qsizetype index = result.index;
            QFuture<int> future = result.future;
            //...
        });

Cette fonction a été introduite dans Qt 6.3.

Voir également QtFuture::WhenAnyResult.