QFuture Class

Dokumentation der Member-Funktionen

QFuture::QFuture()

Erstellt eine leere, stornierte Future.

QFuture::QFuture(const QFuture<T> &other)

Erstellt eine Kopie von other.

Siehe auch operator=().

QFuture::~QFuture()

Zerstört die Zukunft.

Beachten Sie, dass dies weder auf die asynchrone Berechnung wartet noch diese abbricht. Verwenden Sie „ waitForFinished()“ oder „ QFutureSynchronizer “, wenn Sie sicherstellen möchten, dass die Berechnung abgeschlossen ist, bevor das Future zerstört wird.

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture::begin() const

Gibt einen konstanten Iterator im STL-Stil zurück, der auf das erste Ergebnis in der Zukunft verweist.

Siehe auch „ constBegin()“ und „ end()“.

void QFuture::cancel()

Bricht die durch dieses Future dargestellte asynchrone Berechnung ab. Beachten Sie, dass die Abbruchaktion asynchron erfolgt. Verwenden Sie „ waitForFinished()“ nach dem Aufruf von „cancel()“, wenn Sie einen synchronen Abbruch benötigen.

Auf ein abgebrochenes „Future“ kann weiterhin auf bereits verfügbare Ergebnisse zugegriffen werden, jedoch werden nach dem Aufruf dieser Funktion keine neuen Ergebnisse mehr verfügbar sein. Jedes „ QFutureWatcher “-Objekt, das dieses „Future“ überwacht, liefert bei einem abgebrochenen „Future“ keine „progress“- und „result ready“-Signale mehr.

Beachten Sie, dass nicht alle laufenden asynchronen Berechnungen abgebrochen werden können. Beispielsweise kann der von `QtConcurrent::run()` zurückgegebene Future nicht abgebrochen werden; der von `QtConcurrent::mappedReduced()` zurückgegebene Future hingegen schon.

Siehe auch ` cancelChain()`.

[since 6.10] void QFuture::cancelChain()

Bricht die gesamte Fortsetzungskette ab. Alle bereits abgeschlossenen Futures bleiben unverändert, und ihre Ergebnisse sind weiterhin verfügbar. Jede ausstehende Fortsetzung wird abgebrochen, und ihr ` onCanceled()`-Handler wird aufgerufen, sofern er in der Fortsetzungskette vorhanden ist.

auto f = QtConcurrent::run([] {/*...*/})
                .then([]{
                    // Then 1
                })
                .then([]{
                    // Then 2
                })
                .onCanceled([]{
                    // OnCanceled 1
                })
                .then([]{
                    // Then 3
                })
                .then([]{
                    // Then 4
                })
                .onCanceled([]{
                    // OnCanceled 2
                });
//...
f.cancelChain();

Wird im Beispiel die Kette abgebrochen, bevor die Fortsetzung ` Then 2 ` ausgeführt wird, werden sowohl der Abbruch-Handler ` OnCanceled 1 ` als auch der Handler ` OnCanceled 2 ` aufgerufen.

Wird die Kette nach „ Then 2 “, aber vor „ Then 4 “ abgebrochen, wird nur „ OnCanceled 2 “ aufgerufen.

Wenn eine der Fortsetzungen in der Kette eine asynchrone Berechnung ausführt und ein sie repräsentierendes ` QFuture ` zurückgibt, wird der Aufruf von ` cancelChain() ` nach dem Start dieser verschachtelten Berechnung nicht mehr in diese weitergeleitet. Der Grund dafür ist, dass der „Future“ erst dann in der Fortsetzungskette verfügbar ist, wenn der äußere „Future“ erfüllt ist; die Abbruchaktion kann jedoch bereits erfolgen, wenn sowohl der äußere als auch der verschachtelte „Future“ noch auf den Abschluss ihrer Berechnungen warten. In solchen Fällen muss der verschachtelte „Future“ explizit erfasst und abgebrochen werden.

QFuture<void> nested;
auto f = createFuture()
            .then([&]{
                nested = runNestedComputation();
                // do some other work
                return nested;
            })
            .unwrap()
            .then([]{
                // other continuation
            })
            .onCanceled([]{
                // handle cancellation
            });
//...
f.cancelChain();
nested.cancel();

In diesem Beispiel kann „ runNestedComputation() “, sofern es bereits ausgeführt wird, nur durch den Aufruf von ` nested.cancel()` abgebrochen werden.

Diese Funktion wurde in Qt 6.10 eingeführt.

Siehe auch ` cancel()`.

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture::constBegin() const

Gibt einen konstanten Iterator im STL-Stil zurück, der auf das erste Ergebnis in der Zukunft verweist.

Siehe auch ` begin()` und ` constEnd()`.

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture::constEnd() const

Gibt einen konstanten Iterator im STL-Stil zurück, der auf das imaginäre Ergebnis nach dem letzten Ergebnis in der Zukunft zeigt.

Siehe auch „ constBegin()“ und „ end()“.

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture::end() const

Gibt einen konstanten Iterator im STL-Stil zurück, der auf das imaginäre Ergebnis nach dem letzten Ergebnis in der Zukunft zeigt.

Siehe auch „ begin()“ und „ constEnd()“.

bool QFuture::isCanceled() const

Gibt „ true “ zurück, wenn die asynchrone Berechnung mit der Funktion „ cancel()“ abgebrochen wurde; andernfalls wird „ false “ zurückgegeben.

Beachten Sie, dass die Berechnung möglicherweise noch läuft, auch wenn diese Funktion „ true “ zurückgibt. Weitere Informationen finden Sie unter „ cancel()“.

bool QFuture::isFinished() const

Gibt „ true “ zurück, wenn die durch dieses Future dargestellte asynchrone Berechnung abgeschlossen ist; andernfalls wird „ false “ zurückgegeben.

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> bool QFuture::isResultReadyAt(int index) const

Gibt „ true “ zurück, wenn das Ergebnis unter index sofort verfügbar ist; andernfalls wird „ false “ zurückgegeben.

Siehe auch resultAt(), resultCount() und takeResult().

bool QFuture::isRunning() const

Gibt „ true “ zurück, wenn die durch diese Future dargestellte asynchrone Berechnung derzeit ausgeführt wird; andernfalls wird „ false “ zurückgegeben.

bool QFuture::isStarted() const

Gibt „ true “ zurück, wenn die durch diese Future dargestellte asynchrone Berechnung gestartet wurde; andernfalls wird „ false “ zurückgegeben.

[since 6.0] bool QFuture::isSuspended() const

Gibt „ true “ zurück, wenn eine Unterbrechung der asynchronen Berechnung angefordert wurde und diese aktiv ist, was bedeutet, dass keine weiteren Ergebnisse oder Fortschrittsänderungen mehr erwartet werden.

Diese Funktion wurde in Qt 6.0 eingeführt.

Siehe auch „ setSuspended()“, „ toggleSuspended()“ und „ isSuspending()“.

[since 6.0] bool QFuture::isSuspending() const

Gibt „ true “ zurück, wenn die asynchrone Berechnung mit der Funktion „ suspend()“ angehalten wurde, die Arbeit jedoch noch nicht angehalten ist und die Berechnung weiterhin läuft. Andernfalls wird „ false “ zurückgegeben.

Um zu überprüfen, ob die Aussetzung tatsächlich wirksam ist, verwenden Sie stattdessen ` isSuspended()`.

Diese Funktion wurde in Qt 6.0 eingeführt.

Siehe auch „ setSuspended()“, „ toggleSuspended()“ und „ isSuspended()“.

[since 6.0] bool QFuture::isValid() const

Gibt „ true “ zurück, wenn auf ein oder mehrere Ergebnisse von diesem „ QFuture “-Objekt zugegriffen werden kann bzw. diese abgerufen werden können. Gibt „ false “ zurück, wenn das zugehörige „ QPromise “ noch nicht gestartet wurde oder das Ergebnis bereits aus dem „Future“ abgerufen wurde.

Diese Funktion wurde in Qt 6.0 eingeführt.

Siehe auch takeResult(), result(), results(), resultAt(), isFinished() und isResultReadyAt().

[since 6.0] template <typename Function, typename = std::enable_if_t<std::is_invocable_r_v<T, Function>>> QFuture<T> QFuture::onCanceled(Function &&handler)

Fügt diesem Future einen Abbruch- handler hinzu. Der zurückgegebene Future verhält sich genau wie dieser Future (hat denselben Zustand und dasselbe Ergebnis), sofern dieser Future nicht abgebrochen wird. Der handler ist eine aufrufbare Funktion, die keine Argumente entgegennimmt und einen Wert des Typs zurückgibt, der von diesem Future verpackt wird. Nach dem Abbruch verpackt der zurückgegebene Future den von handler zurückgegebenen Wert.

Wird „ handler “ vor der Abbruchaktion angehängt, wird es in demselben Thread aufgerufen, der die Zukunft nach dem Abbruch als beendet meldet. Wird der Handler angehängt, nachdem diese Zukunft bereits abgebrochen wurde, wird er sofort in dem Thread aufgerufen, der „ onCanceled() “ ausführt. Daher kann der Handler nicht immer davon ausgehen, in welchem Thread er ausgeführt wird. Verwenden Sie die Überladung, die ein Kontext-Objekt entgegennimmt, wenn Sie steuern möchten, in welchem Thread der Handler aufgerufen wird.

Das folgende Beispiel zeigt, wie ein Abbruch-Handler angehängt wird:

QFuture<int> testFuture /*...*/;
auto resultFuture = testFuture.then([](int res) {
    // Block 1
    //...
    return 1;
}).then([](int res) {
    // Block 2
    //...
    return 2;
}).onCanceled([] {
    // Block 3
    //...
    return -1;
});

Wenn „ testFuture “ abgebrochen wird, wird „ Block 3 “ aufgerufen, und „ resultFuture “ liefert „ -1 “ als Ergebnis. Im Gegensatz zu „ testFuture “ befindet es sich nicht im Status „ Canceled “. Das bedeutet, dass Sie sein Ergebnis abrufen, ihm Fortsetzungen anhängen können und so weiter.

Beachten Sie außerdem, dass Sie die Kette von Fortsetzungen während ihrer Ausführung über das Future, das die Kette gestartet hat, abbrechen können. Angenommen, „ testFuture.cancel() “ wurde aufgerufen, während „ Block 1 “ bereits ausgeführt wird. Die nächste Fortsetzung erkennt, dass ein Abbruch angefordert wurde, sodass „ Block 2 “ übersprungen und der Abbruch-Handler (Block 3) aufgerufen wird.

Diese Funktion wurde in Qt 6.0 eingeführt.

Siehe auch ` then()` und ` onFailed()`.

[since 6.1] template <typename Function, typename = std::enable_if_t<std::is_invocable_r_v<T, Function>>> QFuture<T> QFuture::onCanceled(QObject *context, Function &&handler)

Weist diesem „Future“ einen Abbruch- handler zu, der aufgerufen wird, wenn der „Future“ abgebrochen wird. Der handler ist ein aufrufbares Objekt, das keine Argumente entgegennimmt. Er wird im Thread des context -Objekts aufgerufen. Dies kann nützlich sein, wenn der Abbruch in einem bestimmten Thread verarbeitet werden muss.

Wird das ` context ` zerstört, bevor die Kette abgeschlossen ist, wird der Future abgebrochen. Weitere Informationen finden Sie unter ` then()`.

Weitere Details zu ` handler` finden Sie in der Dokumentation der anderen Überladung.

Diese Funktion wurde in Qt 6.1 eingeführt.

Siehe auch „ then()“ und „ onFailed()“.

[since 6.0] template <typename Function, typename = std::enable_if_t<!QtPrivate::ArgResolver<Function>::HasExtraArgs>> QFuture<T> QFuture::onFailed(Function &&handler)

Fügt diesem Future einen Fehlerbehandler hinzu, um etwaige Ausnahmen zu behandeln. Der zurückgegebene Future verhält sich genau wie dieser Future (hat denselben Zustand und dasselbe Ergebnis), es sei denn, dieser Future schlägt mit einer Ausnahme fehl.

Der „ handler “ ist eine aufrufbare Funktion, die entweder kein Argument oder ein Argument entgegennimmt, um nach bestimmten Fehlertypen zu filtern, ähnlich wie bei der „catch“-Anweisung. Er gibt einen Wert des Typs zurück, der von diesem Future verpackt wird. Nach dem Fehler verpackt der zurückgegebene Future den von „ handler “ zurückgegebenen Wert.

Der Handler wird nur aufgerufen, wenn eine Ausnahme ausgelöst wird. Wird die Ausnahme ausgelöst, nachdem dieser Handler angehängt wurde, wird der Handler in dem Thread ausgeführt, der das Future infolge der Ausnahme als beendet meldet. Wird der Handler angehängt, nachdem dieses Future bereits fehlgeschlagen ist, wird er sofort in dem Thread aufgerufen, der „ onFailed() “ ausführt. Daher kann der Handler nicht immer davon ausgehen, in welchem Thread er ausgeführt wird. Verwenden Sie die Überladung, die ein Kontext-Objekt entgegennimmt, wenn Sie steuern möchten, in welchem Thread der Handler aufgerufen wird.

Das folgende Beispiel zeigt, wie man einen Fehler-Handler anfügt:

QFuture<int> future = someIntFuture;
auto resultFuture = future.then([](int res) {
    //...
    throw Error();
    //...
    return res;
}).onFailed([](const Error &e) {
    // Handle exceptions of type Error
    //...
    return -1;
}).onFailed([] {
    // Handle all other types of errors
    //...
    return -1;
});

auto result = resultFuture.result(); // result is -1

Sind mehrere Handler angehängt, wird der erste Handler aufgerufen, der mit dem Typ der ausgelösten Ausnahme übereinstimmt. Zum Beispiel:

QFuture<int> future = someIntFuture;
future.then([](int res) {
    //...
    throw std::runtime_error("message");
    //...
}).onFailed([](const std::exception &e) {
    // This handler will be invoked
    return -1;
}).onFailed([](const std::runtime_error &e) {
    // This handler won't be invoked, because of the handler above.
    return -1;
});

Wenn keiner der Handler mit dem Typ der ausgelösten Ausnahme übereinstimmt, wird die Ausnahme an das resultierende Future weitergeleitet:

QFuture<int> future = someIntFuture;
auto resultFuture = future.then([](int res) {
    //...
    throw Error("message");
    //...
    return res;
}).onFailed([](const std::exception &e) {
    // Won't be invoked
    return -1;
}).onFailed([](const QException &e) {
    // Won't be invoked
    return -1;
});

try {
    auto result = resultFuture.result();
} catch(QException &someException) {
    // Handle the exception
}

Diese Funktion wurde in Qt 6.0 eingeführt.

Siehe auch then() und onCanceled().

[since 6.1] template <typename Function, typename = std::enable_if_t<!QtPrivate::ArgResolver<Function>::HasExtraArgs>> QFuture<T> QFuture::onFailed(QObject *context, Function &&handler)

Fügt diesem Future einen Fehlerbehandler hinzu, um alle Ausnahmen zu behandeln, die der Future auslöst oder bereits ausgelöst hat. Gibt ein „ QFuture “ desselben Typs wie dieser Future zurück. Der Handler wird nur im Falle einer Ausnahme im Thread des „ context “-Objekts aufgerufen. Dies kann nützlich sein, wenn der Fehler in einem bestimmten Thread behandelt werden muss. Zum Beispiel:

// somewhere in the main thread
auto future = QtConcurrent::run([] {
    // This will run in a separate thread
    //...
    throw std::exception();
}).onFailed(this, [] {
    // Update UI elements
});

Der an „ QtConcurrent::run “ angehängte Fehlerhandler aktualisiert die UI-Elemente und kann nicht von einem Nicht-GUI-Thread aus aufgerufen werden. Daher wird „ this “ als Kontext für „ .onFailed() “ bereitgestellt, um sicherzustellen, dass der Aufruf im Hauptthread erfolgt.

Wird das ` context ` zerstört, bevor die Kette abgeschlossen ist, wird das `Future` abgebrochen. Weitere Informationen finden Sie unter ` then()`.

Weitere Details zu ` handler` finden Sie in der Dokumentation der anderen Überladung.

Diese Funktion wurde in Qt 6.1 eingeführt.

Siehe auch „ then “ () und „ onCanceled “ ().

int QFuture::progressMaximum() const

Gibt den Maximalwert von ` progressValue()` zurück.

Siehe auch „ progressValue()“ und „ progressMinimum()“.

int QFuture::progressMinimum() const

Gibt den Minimalwert von ` progressValue()` zurück.

Siehe auch „ progressValue()“ und „ progressMaximum()“.

QString QFuture::progressText() const

Gibt die (optionale) textuelle Darstellung des Fortschritts zurück, wie sie von der asynchronen Berechnung gemeldet wird.

Beachten Sie, dass nicht alle Berechnungen eine textuelle Darstellung des Fortschritts bereitstellen und diese Funktion daher möglicherweise eine leere Zeichenkette zurückgibt.

int QFuture::progressValue() const

Gibt den aktuellen Fortschrittswert zurück, der zwischen progressMinimum() und progressMaximum() liegt.

Siehe auch progressMinimum() und progressMaximum().

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFuture::result() const

Gibt das erste Ergebnis zurück, sobald es verfügbar ist. Wenn das Ergebnis nicht sofort verfügbar ist, wird diese Funktion blockiert und wartet, bis das Ergebnis verfügbar ist. Dies ist eine Komfortmethode zum Aufruf von „ resultAt(0)“. Beachten Sie, dass „ result() “ eine Kopie des intern gespeicherten Ergebnisses zurückgibt. Wenn „ T “ ein „move-only“-Typ ist oder Sie das Ergebnis nicht kopieren möchten, verwenden Sie stattdessen „ takeResult()“.

Siehe auch resultAt(), results() und takeResult().

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFuture::resultAt(int index) const

Gibt das zukünftige Ergebnis von ` index ` zurück. Wenn das Ergebnis nicht sofort verfügbar ist, wird diese Funktion blockiert und wartet, bis das Ergebnis verfügbar ist.

Siehe auch result(), results(), takeResult() und resultCount().

int QFuture::resultCount() const

Gibt die Anzahl der in diesem Future verfügbaren fortlaufenden Ergebnisse zurück. Die tatsächliche Anzahl der gespeicherten Ergebnisse kann aufgrund von Lücken in der Ergebnismenge von diesem Wert abweichen. Es ist stets sicher, die Ergebnisse von 0 bis resultCount() durchzulaufen.

Siehe auch result(), resultAt(), results() und takeResult().

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QList<T> QFuture::results() const

Gibt alle Ergebnisse des Futures zurück. Sind die Ergebnisse nicht sofort verfügbar, wird diese Funktion blockiert und wartet, bis sie verfügbar sind. Beachten Sie, dass „ results() “ eine Kopie der intern gespeicherten Ergebnisse zurückgibt. Das Abrufen aller Ergebnisse eines „move-only“-Typs T wird derzeit nicht unterstützt. Sie können jedoch weiterhin mithilfe von Iteratoren im STL-Stil oder schreibgeschützten Iteratoren im Java-Stil durch die Liste der „move-only“-Ergebnisse iterieren.

Siehe auch result(), resultAt(), takeResult(), resultCount() und isValid().

void QFuture::resume()

Setzt die durch `future()` dargestellte asynchrone Berechnung fort. Dies ist eine Komfortmethode, die lediglich ` setSuspended(false)` aufruft.

Siehe auch ` suspend()`.

[since 6.0] void QFuture::setSuspended(bool suspend)

Wenn „ suspend “ wahr ist, unterbricht diese Funktion die durch „future()“ dargestellte asynchrone Berechnung. Ist die Berechnung bereits unterbrochen, führt diese Funktion keine Aktion aus. „ QFutureWatcher “ stellt die Ausgabe von Fortschritts- und Ergebnis-Signalen nicht sofort ein, wenn die Zukunft unterbrochen wird. Zum Zeitpunkt der Unterbrechung können noch Berechnungen im Gange sein, die nicht gestoppt werden können. Signale für solche Berechnungen werden weiterhin ausgegeben.

Ist ` suspend ` falsch, setzt diese Funktion die asynchrone Berechnung fort. Wurde die Berechnung zuvor nicht angehalten, führt diese Funktion keine Aktion aus.

Beachten Sie, dass nicht alle Berechnungen angehalten werden können. Beispielsweise kann der von `QtConcurrent::run()` zurückgegebene ` QFuture ` nicht angehalten werden; der von `QtConcurrent::mappedReduced()` zurückgegebene ` QFuture ` hingegen schon.

Diese Funktion wurde in Qt 6.0 eingeführt.

Siehe auch „ isSuspended()“, „ suspend()“, „ resume()“ und „ toggleSuspended()“.

[since 6.0] void QFuture::suspend()

Setzt die durch diese Future dargestellte asynchrone Berechnung aus. Hierbei handelt es sich um eine Komfortmethode, die lediglich ` setSuspended(true)` aufruft.

Diese Funktion wurde in Qt 6.0 eingeführt.

Siehe auch ` resume()`.

[since 6.0] template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFuture::takeResult()

Rufen Sie diese Funktion nur auf, wenn ` isValid()` den Wert ` true` zurückgibt; andernfalls ist das Verhalten undefiniert. Diese Funktion entnimmt (verschiebt) das erste Ergebnis aus dem Objekt ` QFuture `, sofern nur ein Ergebnis erwartet wird. Sollten weitere Ergebnisse vorhanden sein, werden diese nach Entnahme des ersten Ergebnisses verworfen. Ist das Ergebnis nicht sofort verfügbar, blockiert diese Funktion und wartet, bis das Ergebnis verfügbar ist. „ QFuture “ versucht, nach Möglichkeit die Move-Semantik zu verwenden, und greift auf die Kopierkonstruktion zurück, wenn der Typ nicht verschiebbar ist. Nachdem das Ergebnis entnommen wurde, wird „ isValid()“ als „ false “ ausgewertet.

Diese Funktion wurde in Qt 6.0 eingeführt.

Siehe auch result(), results(), resultAt() und isValid().

[since 6.0] template <typename Function> QFuture<QFuture<T>::ResultType<Function>> QFuture::then(Function &&function)

Fügt diesem Future eine Fortsetzung hinzu, wodurch bei Bedarf mehrere asynchrone Berechnungen unter Verwendung der „ Sync “-Richtlinie verkettet werden können. „ function “ ist eine aufrufbare Funktion, die ein Argument des Typs entgegennimmt, der von diesem Future verpackt wird, sofern dieser ein Ergebnis liefert (also kein „ QFuture<void>“ ist). Andernfalls nimmt sie keine Argumente entgegen. Diese Methode gibt ein neues „ QFuture “ zurück, das einen Wert des Typs enthält, der von „ function “ zurückgegeben wird. Das zurückgegebene „Future“ befindet sich in einem nicht initialisierten Zustand, bis die angehängte Fortsetzung aufgerufen wird oder bis dieses „Future“ fehlschlägt oder abgebrochen wird.

Sie können mehrere Operationen wie folgt verketten:

QFuture<int> future = ...;
future.then([](int res1){ ... }).then([](int res2){ ... })...

Oder:

QFuture<void> future = ...;
future.then([](){ ... }).then([](){ ... })...

Die Fortsetzung kann auch ein Argument vom Typ „ QFuture “ (anstelle ihres Werts) entgegennehmen, das den vorherigen Future repräsentiert. Dies kann nützlich sein, wenn beispielsweise „ QFuture “ mehrere Ergebnisse liefert und der Benutzer innerhalb der Fortsetzung darauf zugreifen möchte. Oder wenn der Benutzer die Ausnahme des vorherigen Futures innerhalb der Fortsetzung behandeln muss, um die Kette mehrerer Fortsetzungen nicht zu unterbrechen. Zum Beispiel:

QFuture<int> future = someIntFuture;
    future.then([](QFuture<int> f) {
        try {
            //...
            auto result = f.result();
            //...
        } catch (QException &e) {
            // handle the exception
        }
    }).then([](){/*...*/});

Wenn die vorherige Future eine Ausnahme auslöst und diese innerhalb der Fortsetzung nicht abgefangen wird, wird die Ausnahme an die Fortsetzungs-Future weitergeleitet, damit der Aufrufer sie abfangen kann:

QFuture<int> future = someIntFuture;
auto continuation = future.then([](int res1){ /*...*/ return res1; }).then([](int res2){ /*...*/ return res2; })/*...*/;
//...
// future throws an exception
try {
    auto result = continuation.result();
} catch (QException &e) {
    // handle the exception
}

In diesem Fall wird die gesamte Kette von Fortsetzungen unterbrochen.

Diese Funktion wurde in Qt 6.0 eingeführt.

Siehe auch „ onFailed()“ und „ onCanceled()“.

[since 6.1] template <typename Function> QFuture<QFuture<T>::ResultType<Function>> QFuture::then(QObject *context, Function &&function)

Fügt diesem „Future“ eine Fortsetzung hinzu, wodurch bei Bedarf mehrere asynchrone Berechnungen verkettet werden können. Sobald die durch diesen „Future“ dargestellte asynchrone Berechnung abgeschlossen ist, wird die Methode ` function ` im Thread des Objekts ` context ` aufgerufen. Dies kann nützlich sein, wenn die Fortsetzung in einem bestimmten Thread aufgerufen werden soll. Zum Beispiel:

// somewhere in the main thread
auto future = QtConcurrent::run([] {
    // This will run in a separate thread
    //...
}).then(this, [] {
    // Update UI elements
});

Die an „ QtConcurrent::run “ angehängte Fortsetzung aktualisiert die UI-Elemente und kann nicht von einem Nicht-GUI-Thread aus aufgerufen werden. Daher wird „ this “ als Kontext für „ .then() “ bereitgestellt, um sicherzustellen, dass die Fortsetzung im Hauptthread aufgerufen wird.

Die folgenden Kontinuitäten werden ebenfalls aus demselben Kontext aufgerufen, sofern kein anderer Kontext oder keine andere Startrichtlinie angegeben ist:

auto future = QtConcurrent::run([] {
    //...
}).then(this, [] {
    // Update UI elements
}).then([] {
    // This will also run in the main thread
});

Dies liegt daran, dass „ .then() “ standardmäßig aus demselben Thread aufgerufen wird wie die vorherige Funktion.

Beachten Sie jedoch, dass die Fortsetzung, wenn sie angehängt wird, nachdem diese Future bereits beendet ist, sofort in dem Thread aufgerufen wird, der ` then()` ausführt:

QObject *context /*...*/;
auto future = cachedResultsReady ? QtFuture::makeReadyVoidFuture()
                                : QtConcurrent::run([] { /* compute result */});
auto continuation = future.then(context, [] {
    // Runs in the context's thread
}).then([] {
    // May or may not run in the context's thread
});

Wenn im obigen Beispiel ` cachedResultsReady ` ` true` ist und ein bereiter Future zurückgegeben wird, ist es möglich, dass der erste ` .then() ` beendet ist, bevor der zweite angehängt wird. In diesem Fall wird er im aktuellen Thread abgearbeitet. Übergeben Sie daher im Zweifelsfall den Kontext explizit.

Wird der „ context “ zerstört, bevor die Kette abgeschlossen ist, wird das Future abgebrochen. Dies bedeutet, dass ein Abbruch-Handler möglicherweise aufgerufen wird, wenn der „ context “ nicht mehr gültig ist. Um dies zu verhindern, erfassen Sie das „ context “ als „ QPointer “:

QObject *context /*...*/;
QFuture<Result> future /*...*/;
auto continuation = future.then(context, [context](Result result) {
                            // ...
                        }).onCanceled([context = QPointer(context)] {
                            if (!context)
                                return;  // context was destroyed already
                            // handle cancellation
                        });

Wenn das Kontext-Objekt zerstört wird, erfolgt die Abbruchbehandlung sofort. Vorherige Futures in der Kette werden nicht abgebrochen und laufen weiter, bis sie abgeschlossen sind.

Diese Funktion wurde in Qt 6.1 eingeführt.

Siehe auch ` onFailed()` und ` onCanceled()`.

[since 6.0] template <typename Function> QFuture<QFuture<T>::ResultType<Function>> QFuture::then(QThreadPool *pool, Function &&function)

Fügt diesem „Future“ eine Fortsetzung hinzu, wodurch bei Bedarf mehrere asynchrone Berechnungen verkettet werden können. Sobald die durch diesen „Future“ dargestellte asynchrone Berechnung abgeschlossen ist, wird „ function “ unter „ pool “ eingeplant.

Diese Funktion wurde in Qt 6.0 eingeführt.

Siehe auch „ onFailed()“ und „ onCanceled()“.

[since 6.0] template <typename Function> QFuture<QFuture<T>::ResultType<Function>> QFuture::then(QtFuture::Launch policy, Function &&function)

Fügt diesem „Future“ eine Fortsetzung hinzu, wodurch mehrere asynchrone Berechnungen verkettet werden können. Wenn die durch diesen „Future“ dargestellte asynchrone Berechnung abgeschlossen ist, wird ` function ` gemäß der angegebenen Start policy` aufgerufen. Es wird ein neues ` QFuture ` zurückgegeben, das das Ergebnis der Fortsetzung darstellt.

Je nach der „ policy “ wird die Fortsetzung im selben Thread wie dieses „Future“, in einem neuen Thread oder unter Übernahme der Ausführungsrichtlinie und des Thread-Pools dieses „Future“ aufgerufen. Wenn keine Ausführungsrichtlinie angegeben ist (siehe die Überladung, die nur ein aufrufbares Objekt akzeptiert), wird die „ Sync “-Richtlinie verwendet.

Im folgenden Beispiel werden beide Fortsetzungen in einem neuen Thread (jedoch im selben Thread) aufgerufen.

QFuture<int> future = ...;
future.then(QtFuture::Launch::Async, [](int res){ ... }).then([](int res2){ ... });

Im folgenden Beispiel werden beide Fortsetzungen in neuen Threads unter Verwendung desselben Thread-Pools aufgerufen.

QFuture<int> future = ...;
future.then(QtFuture::Launch::Async, [](int res){ ... })
      .then(QtFuture::Launch::Inherit, [](int res2){ ... });

Weitere Details zu „ function “ finden Sie in der Dokumentation der anderen Überladung.

Diese Funktion wurde in Qt 6.0 eingeführt.

Siehe auch „ onFailed()“ und „ onCanceled()“.

[since 6.0] void QFuture::toggleSuspended()

Schaltet den angehaltenen Zustand der asynchronen Berechnung um. Mit anderen Worten: Wenn die Berechnung gerade angehalten wird oder angehalten ist, wird sie durch den Aufruf dieser Funktion fortgesetzt; wenn die Berechnung läuft, wird sie angehalten. Dies ist eine Komfortmethode zum Aufruf von ` setSuspended(!(isSuspending() || isSuspended())).

Diese Funktion wurde in Qt 6.0 eingeführt.

Siehe auch setSuspended(), suspend() und resume().

[since 6.4] template <typename U> QFuture<U> QFuture::unwrap()

Entpackt das innere Future aus diesem „ QFuture<T> “, wobei „ T “ ein Future vom Typ „ QFuture<U> “ ist, d. h., dieses Future hat den Typ „ QFuture<QFuture<U>> “. Beispiel:

QFuture<QFuture<int>> outerFuture /*...*/;
QFuture<int> unwrappedFuture = outerFuture.unwrap();

unwrappedFuture wird erfüllt, sobald die in outerFuture verschachtelte innere Future erfüllt ist, und zwar mit demselben Ergebnis oder derselben Ausnahme und in demselben Thread, der die innere Future als abgeschlossen meldet. Wird die innere Future abgebrochen, wird auch unwrappedFuture abgebrochen.

Dies ist besonders nützlich, wenn mehrere Berechnungen verkettet werden und eine davon ein ` QFuture ` als Ergebnistyp zurückgibt. Nehmen wir zum Beispiel an, wir möchten mehrere Bilder von einer URL herunterladen, die Bilder skalieren und sie mithilfe von `QtConcurrent::mappedReduced()` zu einem einzigen Bild zusammenführen. Wir könnten etwa Folgendes schreiben:

auto downloadImages = [] (const QUrl &url) {
    QList<QImage> images;
    //...
    return images;
};

auto processImages = [scale, reduceImages](const QList<QImage> &images) {
    return QtConcurrent::mappedReduced(images, scale, reduceImages);
};

auto show = [](const QImage &image) { /*...*/ };

auto future = QtConcurrent::run(downloadImages, url)
            .then(processImages)
            .unwrap()
            .then(show);

Hier gibt ` QtConcurrent::mappedReduced() ` ein ` QFuture<QImage>` zurück, sodass ` .then(processImages) ` ein ` QFuture<QFuture<QImage>>` zurückgibt. Da ` show() ` ein ` QImage ` als Argument benötigt, kann das Ergebnis von ` .then(processImages) ` nicht direkt an diese Funktion übergeben werden. Wir müssen ` .unwrap()` aufrufen, das das Ergebnis des inneren Futures abruft, sobald es bereit ist, und es an die nächste Fortsetzung weiterleitet.

Bei mehrfacher Verschachtelung gelangt „ .unwrap() “ bis zur innersten Ebene:

QFuture<QFuture<QFuture<int>>> outerFuture;
QFuture<int> unwrappedFuture = outerFuture.unwrap();

Diese Funktion wurde in Qt 6.4 eingeführt.

void QFuture::waitForFinished()

Wartet, bis die asynchrone Berechnung abgeschlossen ist (einschließlich der mit ` cancel()` aufgerufenen Berechnungen), d. h. bis ` isFinished()` den Wert ` true` zurückgibt.

QFuture<T> &QFuture::operator=(const QFuture<T> &other)

Weist dieser Future die Funktion „ other “ zu und gibt einen Verweis auf diese Future zurück.