QtFuture Namespace

Funktion Dokumentation

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

Erzeugt und gibt ein QFuture zurück, das verfügbar wird, wenn sender das signal sendet. Wenn signal keine Argumente annimmt, wird ein QFuture<void> zurückgegeben. Wenn signal ein einzelnes Argument annimmt, wird das Ergebnis QFuture mit dem Argumentwert des Signals gefüllt. Wenn signal mehrere Argumente entgegennimmt, wird das Ergebnis QFuture mit std::tuple gefüllt, das die Werte der Argumente des Signals speichert. Wenn sender zerstört wird, bevor signal ausgesendet wird, wird das Ergebnis QFuture abgebrochen.

Nehmen wir zum Beispiel an, wir haben das folgende Objekt:

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

Wir können seine Signale auf folgende Weise mit QFuture Objekten verbinden:

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)

Wir können auch Fortsetzungen verketten, die ausgeführt werden, wenn ein Signal ausgegeben wird:

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

Sie können die Fortsetzung auch in einem neuen Thread oder einem benutzerdefinierten Thread-Pool unter Verwendung der QtFuture::Launch Richtlinien starten. Zum Beispiel:

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

Das Werfen einer Exception aus einem Slot, der von Qt's signal-slot connection aufgerufen wird, wird als undefiniertes Verhalten betrachtet, wenn es nicht innerhalb des Slots behandelt wird. Aber mit QFuture::connect() können Sie Exceptions aus den Continuations auslösen und behandeln:

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

Siehe auch QFuture und QFuture::then().

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

Erzeugt und gibt eine QFuture zurück, die bereits eine Exception exception hat.

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

Diese Funktion wurde in Qt 6.1 eingeführt.

Siehe auch QFuture, QException, QtFuture::makeReadyVoidFuture(), und QtFuture::makeReadyValueFuture().

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

Dies ist eine überladene Funktion.

Erzeugt und gibt eine QFuture zurück, die bereits eine Exception exception hat.

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
}

Diese Funktion wurde in Qt 6.1 eingeführt.

Siehe auch QFuture, QException, QtFuture::makeReadyVoidFuture(), und QtFuture::makeReadyValueFuture().

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

Dies ist eine überladene Funktion.

Nimmt einen Eingabecontainer container und gibt einen QFuture mit mehreren Ergebnissen vom Typ ContainedType zurück, die aus den Werten des container initialisiert wurden.

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 }

Diese Funktion wurde in Qt 6.6 eingeführt.

Siehe auch QFuture, QtFuture::makeReadyVoidFuture(), QtFuture::makeReadyValueFuture(), und QtFuture::makeExceptionalFuture().

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

Dies ist eine überladene Funktion.

Gibt ein QFuture mit mehreren Ergebnissen vom Typ ValueType zurück, die aus der Input-Initialisierungsliste values initialisiert wurden.

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

Diese Funktion wurde in Qt 6.6 eingeführt.

Siehe auch QFuture, QtFuture::makeReadyVoidFuture(), QtFuture::makeReadyValueFuture(), und QtFuture::makeExceptionalFuture().

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

Erzeugt und gibt ein QFuture zurück, das bereits ein Ergebnis value hat. Das zurückgegebene QFuture hat den Typ std::decay_t<T>, wobei T nicht void ist. Das zurückgegebene QFuture befindet sich bereits im fertigen Zustand.

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

Diese Funktion wurde in Qt 6.6 eingeführt.

Siehe auch QFuture, QtFuture::makeReadyRangeFuture(), QtFuture::makeReadyVoidFuture(), und QtFuture::makeExceptionalFuture().

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

Erzeugt ein void QFuture und gibt es zurück. Ein solches QFuture kann kein Ergebnis speichern. Man kann es verwenden, um den Zustand der Berechnung abzufragen. Das zurückgegebene QFuture wird sich bereits im fertigen Zustand befinden.

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

Diese Funktion wurde in Qt 6.6 eingeführt.

Siehe auch QFuture, QFuture::isStarted(), QFuture::isRunning(), QFuture::isFinished(), QtFuture::makeReadyValueFuture(), QtFuture::makeReadyRangeFuture(), und QtFuture::makeExceptionalFuture().

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

Gibt eine neue QFuture zurück, die erfolgreich ist, wenn alle futures Verpackungen beliebigen Typs abgeschlossen sind. OutputSequence ist eine Folge von abgeschlossenen Futures. Der Typ ihrer Einträge ist std::variant<Futures...>. Für jedes QFuture<T>, das an whenAll() übergeben wird, wird der Eintrag an der entsprechenden Position in OutputSequence ein std::variant sein, der dieses QFuture<T> in seinem abgeschlossenen Zustand enthält. Wird der Typ von OutputSequence nicht angegeben, werden die resultierenden Futures in einem QList von std::variant<Futures...> zurückgegeben. Beispiel:

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);

Der zurückgegebene Futures wird immer erfolgreich abgeschlossen, nachdem alle angegebenen Futures abgeschlossen wurden. Es spielt keine Rolle, ob einer dieser Futures mit einem Fehler abschließt oder abgebrochen wird. Sie können .then() verwenden, um die abgeschlossenen Futures zu verarbeiten, nachdem der von whenAll() zurückgegebene Future erfolgreich war:

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);
            }
            ...
        });

Diese Funktion wurde in Qt 6.3 eingeführt.

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

Gibt eine neue QFuture zurück, die erfolgreich ist, wenn alle Futures von first bis last abgeschlossen sind. first und last sind Iteratoren zu einer Sequenz von Futures vom Verpackungstyp T. OutputSequence ist eine Sequenz, die alle abgeschlossenen Futures von first bis last enthält, die in der gleichen Reihenfolge wie in der Eingabe erscheinen. Wenn der Typ von OutputSequence nicht angegeben wird, werden die resultierenden Futures in einer QList von QFuture<T> zurückgegeben. Zum Beispiel:

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());

Wenn first gleich last ist, gibt diese Funktion ein fertiges QFuture zurück, das ein leeres OutputSequence enthält.

Der zurückgegebene Future wird immer erfolgreich abgeschlossen, nachdem alle angegebenen Futures abgeschlossen wurden. Es spielt keine Rolle, ob einer dieser Futures mit einem Fehler abschließt oder abgebrochen wird. Sie können .then() verwenden, um die abgeschlossenen Futures zu verarbeiten, nachdem der von whenAll() zurückgegebene Future erfolgreich war:

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
            }
        });

Diese Funktion wurde in Qt 6.3 eingeführt.

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

Gibt einen neuen QFuture zurück, der erfolgreich ist, wenn einer der futures abgeschlossen ist. futures kann beliebige Typen verpacken. Der zurückgegebene Future verpackt den Wert des Typs std::variant<Futures...>, der wiederum den ersten abgeschlossenen QFuture von futures verpackt. Sie können std::variant::index() verwenden, um den Index des Futures in der Sequenz von futures herauszufinden, der zuerst abgeschlossen wurde.

Der zurückgegebene Future wird immer erfolgreich abgeschlossen, nachdem der erste Future aus den angegebenen Futures abgeschlossen wurde. Es spielt keine Rolle, ob der erste Future mit einem Fehler endet oder abgebrochen wird. Sie können .then() verwenden, um das Ergebnis zu verarbeiten, nachdem der von whenAny() zurückgegebene Future erfolgreich abgeschlossen wurde:

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);
    ...
});

Diese Funktion wurde in Qt 6.3 eingeführt.

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

Gibt eine neue QFuture zurück, die erfolgreich ist, wenn einer der Futures von first bis last abgeschlossen ist. first und last sind Iteratoren zu einer Folge von Futures, die vom Typ T sind. Der zurückgegebene Future verpackt einen Wert vom Typ QtFuture::WhenAnyResult<T>, der wiederum den Index des ersten abgeschlossenen QFuture und den QFuture selbst verpackt. Wenn first gleich last ist, gibt diese Funktion ein fertiges QFuture zurück, das -1 für das Feld index in der Struktur QtFuture::WhenAnyResult und ein standardmäßig konstruiertes QFuture<T> für das Feld future hat. Beachten Sie, dass ein standardmäßig konstruierter QFuture ein abgeschlossener Future in einem abgebrochenen Zustand ist.

Der zurückgegebene Future wird immer erfolgreich abgeschlossen, nachdem der erste Future aus den angegebenen Futures abgeschlossen wurde. Es spielt keine Rolle, ob der erste Future mit einem Fehler endet oder abgebrochen wird. Sie können .then() verwenden, um das Ergebnis zu verarbeiten, nachdem der von whenAny() zurückgegebene Future erfolgreich abgeschlossen wurde:

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;
            // ...
        });

Diese Funktion wurde in Qt 6.3 eingeführt.

Siehe auch QtFuture::WhenAnyResult.