QtFuture Namespace

Funktionsdokumentation

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, sobald der ` sender ` das ` signal` ausgibt. Wenn der ` signal ` keine Argumente entgegennimmt, wird ein ` QFuture<void>` zurückgegeben. Wenn die Funktion „ signal “ ein einzelnes Argument entgegennimmt, wird das resultierende „ QFuture “ mit dem Wert des Signalarguments gefüllt. Wenn die Funktion „ signal “ mehrere Argumente entgegennimmt, wird das resultierende „ QFuture “ mit einem „std::tuple“ gefüllt, das die Werte der Signalargumente enthält. Wenn das „ sender “ zerstört wird, bevor das „ signal “ ausgelöst wird, wird das resultierende „ QFuture “ abgebrochen.

Nehmen wir zum Beispiel an, wir hätten 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 wie folgt mit „ QFuture “-Objekten verknüpfen:

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 Continuations verketten, die ausgeführt werden sollen, wenn ein Signal ausgelöst 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 mithilfe von „ 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 Auslösen einer Ausnahme aus einem Slot, der über die Signal-Slot-Verbindung von Qt aufgerufen wird, gilt als undefiniertes Verhalten, wenn es nicht innerhalb des Slots abgefangen wird. Mit `QFuture::connect()` können Sie jedoch Ausnahmen aus den Continuations auslösen und abfangen:

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)

Erstellt und gibt ein ` QFuture ` zurück, das bereits über einen Ausnahmep exception` verfügt.

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)

Erzeugt und gibt einen ` QFuture ` zurück, der bereits eine Ausnahme ` exception` enthält.

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> requires if_container_with_input_iterators<Container> QFuture<QtFuture::ContainedType<Container>> QtFuture::makeReadyRangeFuture(Container &&container)

Nimmt einen Eingabecontainer „ container “ entgegen und gibt einen „ QFuture “ mit mehreren Ergebnissen vom Typ „ ContainedType “ zurück, die anhand der Werte von „ container “ initialisiert werden.

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 }

Einschränkungen

Nimmt nur dann an der Überladungsauflösung teil, wenn der ` Container ` Eingabeiteratoren besitzt.

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)

Gibt ein ` QFuture ` mit mehreren Ergebnissen vom Typ ` ValueType ` zurück, die anhand der Eingabe-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` enthält. Der zurückgegebene ` QFuture ` hat den Typ `std::decay_t<T>`, wobei `T` nicht `void` ist. Der zurückgegebene ` QFuture ` befindet sich bereits im abgeschlossenen 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 und gibt ein `void QFuture` zurück. Ein solches ` QFuture ` kann kein Ergebnis speichern. Man kann es verwenden, um den Status der Berechnung abzufragen. Das zurückgegebene ` QFuture ` befindet sich bereits im abgeschlossenen Zustand.

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 ein neues ` QFuture ` zurück, das erfolgreich ist, wenn alle ` futures `-Verpackungen beliebiger Typen abgeschlossen sind. ` OutputSequence ` ist eine Sequenz abgeschlossener Futures. Der Typ ihrer Einträge ist ` std::variant<Futures...>`. Für jedes an ` whenAll()` übergebene ` QFuture<T> ` ist der Eintrag an der entsprechenden Position in ` OutputSequence ` ein ` std::variant `, der diesen ` QFuture<T>` in seinem abgeschlossenen Zustand enthält. Wenn der Typ von ` OutputSequence ` nicht angegeben ist, werden die resultierenden Futures in einem ` QList ` vom Typ ` std::variant<Futures...>` zurückgegeben. Zum 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 Future wird immer erfolgreich abgeschlossen, nachdem alle angegebenen Futures abgeschlossen sind. Es spielt keine Rolle, ob einer dieser Futures mit einem Fehler endet oder abgebrochen wird. Mit ` .then() ` können Sie die abgeschlossenen Futures verarbeiten, nachdem der von ` whenAll() ` 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::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 ein neues „ QFuture “ zurück, das erfolgreich ist, sobald alle Futures von first bis last abgeschlossen sind. first und last sind Iteratoren für eine Sequenz von Futures vom Typ T. OutputSequence ist eine Sequenz, die alle abgeschlossenen Futures von first bis last enthält, wobei diese in derselben Reihenfolge wie in der Eingabe erscheinen. Wenn der Typ von OutputSequence nicht angegeben ist, werden die resultierenden Futures in einem QList vom Typ QFuture<T> zurückgegeben. 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 sind. Es spielt keine Rolle, ob einer dieser Futures mit einem Fehler endet oder abgebrochen wird. Sie können ` .then() ` verwenden, um die abgeschlossenen Futures zu verarbeiten, nachdem der von ` whenAll() ` zurückgegebene Future erfolgreich abgeschlossen wurde:

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 ein neues ` QFuture ` zurück, das erfolgreich ist, sobald eines der ` futures ` abgeschlossen ist. ` futures ` kann beliebige Typen verpacken. Das zurückgegebene `Future` verpackt den Wert vom Typ ` std::variant<Futures...> `, der wiederum das erste abgeschlossene ` QFuture ` aus ` futures` verpackt. Mit `std::variant::index()` können Sie den Index des `Future` in der Sequenz von ` futures ` ermitteln, das als erstes abgeschlossen wurde.

Der zurückgegebene Future wird immer erfolgreich abgeschlossen, nachdem der erste Future aus den angegebenen Futures abgeschlossen ist. Dabei spielt es keine Rolle, ob der erste Future mit einem Fehler endet oder abgebrochen wird. Mit ` .then() ` können Sie das Ergebnis 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 ein neues „ QFuture “ zurück, das erfolgreich ist, sobald eines der Futures von „ first “ bis „ last “ abgeschlossen ist. „ first “ und „ last “ sind Iteratoren für eine Folge von Futures vom Typ „ T “. Das zurückgegebene Future enthält einen Wert vom Typ „ QtFuture::WhenAnyResult<T> “, der wiederum den Index des ersten abgeschlossenen „ QFuture “ sowie das „ QFuture “ selbst enthält. Wenn „ first “ gleich „ last “ ist, gibt diese Funktion ein bereites „ 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 “ enthält. Beachten Sie, dass ein standardmäßig konstruiertes „ QFuture “ ein abgeschlossener Future im Status „cancelled“ ist.

Der zurückgegebene Future wird immer erfolgreich abgeschlossen, sobald der erste Future aus den angegebenen Futures abgeschlossen ist. Dabei spielt es keine Rolle, ob der erste Future mit einem Fehler abgeschlossen oder abgebrochen wird. Mit „ .then() “ können Sie das Ergebnis 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.