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 QFuture qui deviendra disponible lorsque le sender émettra le signal. Si le signal ne prend aucun argument, un QFuture<void> est renvoyé. Si le signal prend un seul argument, le QFuture résultant sera rempli avec la valeur de l'argument du signal. Si signal prend plusieurs arguments, le résultat QFuture est rempli avec std::tuple stockant les valeurs des arguments du signal. Si le sender est détruit avant que le signal ne soit émis, le QFuture résultant sera annulé.

Par exemple, supposons que nous ayons 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 aux 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 à exécuter lorsqu'un signal est émis :

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

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

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

Lancer une exception à partir d'un slot invoqué par la connexion signal-slot de Qt est considéré comme un comportement non défini, s'il n'est pas géré dans le slot. Mais avec QFuture::connect(), vous pouvez lancer et gérer des exceptions à partir des 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 aussi QFuture et QFuture::then().

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

Crée et renvoie un QFuture qui a déjà une exception 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 aussi 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 QFuture qui a déjà une exception 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 aussi QFuture, QException, QtFuture::makeReadyVoidFuture(), et QtFuture::makeReadyValueFuture().

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

Prend un conteneur d'entrée container et renvoie un QFuture avec 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

Participe à la résolution des surcharges uniquement si Container possède des itérateurs en entrée.

Cette fonction a été introduite dans Qt 6.6.

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

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

Renvoie un QFuture avec plusieurs résultats de type ValueType initialisés à partir de la liste d'initialisateurs 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 aussi 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 QFuture qui a déjà un résultat value. Le QFuture retourné est de type std::decay_t<T>, où T n'est pas void. Le QFuture retourné sera déjà dans l'état fini.

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 aussi QFuture, QtFuture::makeReadyRangeFuture(), QtFuture::makeReadyVoidFuture(), et QtFuture::makeExceptionalFuture().

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

Crée et renvoie un void QFuture. Un tel QFuture ne peut stocker aucun résultat. On peut l'utiliser pour demander l'état du calcul. Le QFuture renvoyé sera déjà dans 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 aussi 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 nouveau QFuture qui réussit lorsque tous les types arbitraires d'emballage futures sont terminés. OutputSequence est une séquence de futurs 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ésultantes seront renvoyées dans un QList de 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 futur retourné se termine toujours avec succès après que tous les futurs spécifiés se soient terminés. Il n'y a pas d'importance si l'un de ces futurs se termine avec une erreur ou est annulé. Vous pouvez utiliser .then() pour traiter les futures terminés après que le future retourné par whenAll() ait réussi :

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 nouveau 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 d'emballages de futures de type T. OutputSequence est une séquence contenant tous les futures terminés de first à last, apparaissant dans le même ordre que dans l'entrée. Si le type de OutputSequence n'est pas spécifié, les contrats à terme résultants seront renvoyés dans un QList de 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 QFuture prêt à l'emploi qui contient un OutputSequence vide.

Le futur renvoyé se termine toujours avec succès après que tous les futurs spécifiés se soient terminés. Il n'y a pas d'importance si l'un de ces futurs se termine avec une erreur ou est annulé. Vous pouvez utiliser .then() pour traiter les futures terminés après que le future retourné par whenAll() ait réussi :

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 nouveau QFuture qui réussit lorsque l'un des futures se termine. futures peut emballer des types arbitraires. Le futur retourné empaquette la valeur du type std::variant<Futures...> qui, à son tour, empaquette le premier QFuture terminé à partir de futures. Vous pouvez utiliser std::variant::index() pour connaître l'index du futur dans la séquence de futures qui s'est terminé en premier.

Le futur retourné se termine toujours avec succès après que le premier futur des futurs spécifiés se soit terminé. Cela n'a pas d'importance si le premier futur se termine avec une erreur ou est annulé. Vous pouvez utiliser .then() pour traiter le résultat après que le futur retourné par whenAny() ait réussi :

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 nouveau QFuture qui réussit lorsque l'un des futurs de first à last s'achève. first et last sont des itérateurs vers une séquence de futurs emballant le type T. Le futur renvoyé contient une valeur de type QtFuture::WhenAnyResult<T> qui contient à son tour l'index du premier QFuture terminé et le QFuture lui-même. Si first est égal à last, cette fonction renvoie un QFuture prêt qui a -1 pour le champ index dans la structure QtFuture::WhenAnyResult et un QFuture<T> construit par défaut pour le champ future. Notez qu'un QFuture construit par défaut est un futur terminé dans un état annulé.

Le futur retourné s'achève toujours avec succès après que le premier futur des futurs spécifiés s'achève. Cela n'a pas d'importance si le premier futur se termine avec une erreur ou est annulé. Vous pouvez utiliser .then() pour traiter le résultat après que le futur retourné par whenAny() ait réussi :

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 aussi QtFuture::WhenAnyResult.