QtTaskTree::QTaskTree Class

Dokumentation der Mitgliedsfunktionen

[explicit] QTaskTree::QTaskTree(QObject *parent)

Erstellt einen leeren Aufgabenbaum mit einem angegebenen „ parent “. Verwenden Sie „ setRecipe()“, um eine deklarative Beschreibung zu übergeben, wie der Aufgabenbaum die Aufgaben ausführen und wie er mit den abgeschlossenen Aufgaben verfahren soll.

Das Starten eines leeren Aufgabenbaums hat keine Auswirkung, und es wird eine entsprechende Warnmeldung ausgegeben.

Siehe auch ` setRecipe()` und ` start()`.

[explicit] QTaskTree::QTaskTree(const QtTaskTree::Group &recipe, QObject *parent = nullptr)

Erstellt einen Aufgabenbaum mit den angegebenen Parametern „ recipe “ und „ parent “. Nachdem der Aufgabenbaum gestartet wurde, führt er die in „ recipe “ enthaltenen Aufgaben aus und verarbeitet abgeschlossene Aufgaben gemäß der übergebenen Beschreibung.

Siehe auch setRecipe() und start().

[override virtual noexcept] QTaskTree::~QTaskTree()

Löst den Aufgabenbaum auf.

Wenn der Aufgabenbaum während seiner Zerstörung noch läuft, bricht er alle laufenden Aufgaben sofort ab. In diesem Fall werden keine Handler aufgerufen, nicht einmal die „done“-Handler der Gruppen und Aufgaben oder die „ onStorageDone()“-Handler. Der Aufgabenbaum sendet vom Destruktor aus auch keine Signale aus, nicht einmal „ done()“- oder „ progressValueChanged()“-Signale. Auf dieses Verhalten kann man sich stets verlassen. Es ist vollkommen sicher, den laufenden Aufgabenbaum zu zerstören.

Es ist ein gängiges Muster, den laufenden Aufgabenbaum zu zerstören. Es ist garantiert, dass die Zerstörung schnell abläuft, ohne dass auf den Abschluss der aktuell laufenden Aufgaben gewartet werden muss, vorausgesetzt, die verwendeten Aufgaben implementieren ihre Destruktoren auf nicht blockierende Weise.

Siehe auch ` cancel()`.

qsizetype QTaskTree::asyncCount() const

Gibt die aktuelle tatsächliche Anzahl der asynchronen Aufrufketten zurück.

Der zurückgegebene Wert gibt an, wie oft die Steuerung während der Ausführung des Aufgabenbaums zur Ereignisschleife des Aufrufers zurückkehrt. Anfangs ist dieser Wert „ 0 “. Wenn die Ausführung des Aufgabenbaums vollständig synchron abgeschlossen wird, bleibt dieser Wert bei „ 0 “. Enthält der Aufgabenbaum asynchrone Aufgaben, die während eines Aufrufs von ` start()` erfolgreich gestartet wurden, wird dieser Wert kurz vor Beendigung des Aufrufs von ` start()` auf „ 1 “ erhöht. Später, wenn eine asynchrone Aufgabe beendet wird und eventuelle Fortsetzungen gestartet werden, wird dieser Wert erneut erhöht. Die Erhöhung wird fortgesetzt, bis der Aufgabenbaum beendet ist. Wenn der Aufgabenbaum das Signal „ done()“ aussendet, wird die Erhöhung beendet. Bei jeder Erhöhung dieses Werts wird das Signal „ asyncCountChanged()“ ausgesendet.

Siehe auch „ asyncCountChanged()“.

[signal] void QTaskTree::asyncCountChanged(qsizetype count)

Dieses Signal wird ausgelöst, wenn der laufende Aufgabenbaum im Begriff ist, die Kontrolle an die Ereignisschleife des Aufrufers zurückzugeben. Beim Start des Aufgabenbaums wird dieses Signal mit dem Wert „ count “ von „ 0 “ ausgelöst und später bei jeder Erhöhung des Werts von „ asyncCount()“ mit einem aktualisierten Wert von „ count “ ausgelöst. Jedes gesendete Signal (mit Ausnahme des ersten mit dem Wert „ 0 “) garantiert, dass der Aufgabenbaum nach der Aussendung weiterhin asynchron läuft.

Siehe auch asyncCount().

void QTaskTree::cancel()

Bricht die Ausführung des laufenden Aufgabenbaums ab.

Alle laufenden Aufgaben werden sofort abgebrochen. Alle laufenden Aufgaben und Gruppen werden mit einem Fehler beendet, wobei ihre „done“-Handler mit ` DoneWith::Cancel` aufgerufen werden. Die ` onStorageDone()`-Handler der Speicher werden ebenfalls aufgerufen. Außerdem werden die Signale ` progressValueChanged()` gesendet. Auf dieses Verhalten kann man sich stets verlassen.

Die Funktion `cancel()` wird synchron ausgeführt, sodass nach einem Aufruf von `cancel()` alle laufenden Aufgaben beendet sind und der Baum bereits abgebrochen ist. Es ist gewährleistet, dass `cancel()` schnell ausgeführt wird, ohne dass auf den Abschluss der aktuell laufenden Aufgaben gewartet werden muss, vorausgesetzt, die verwendeten Aufgaben implementieren ihre Destruktoren auf nicht blockierende Weise.

Ist der Aufgabenbaum leer, d. h. mit einem Standardkonstruktor erstellt, hat ein Aufruf von `cancel()` keine Auswirkung und es wird die entsprechende Warnmeldung ausgegeben.

Andernfalls, wenn der Aufgabenbaum nicht gestartet wurde, wird ein Aufruf von `cancel()` ignoriert.

Siehe auch ` ~QTaskTree()`.

[signal] void QTaskTree::done(QtTaskTree::DoneWith result)

Dieses Signal wird ausgelöst, wenn der Aufgabenbaum beendet ist, und übergibt den letzten „ result “ der Ausführung. Der Aufgabenbaum ruft nach dem Auslösen dieses Signals weder einen Handler auf noch löst er weitere Signale aus.

Siehe auch ` started()`.

[override virtual protected] bool QTaskTree::event(QEvent *event)

Implementiert: QObject::event(QEvent *e).

bool QTaskTree::isRunning() const

Gibt „ true “ zurück, wenn der Aufgabenbaum derzeit ausgeführt wird; andernfalls wird „ false “ zurückgegeben.

Siehe auch start() und cancel().

template <typename StorageStruct, typename Handler> void QTaskTree::onStorageDone(const QtTaskTree::Storage<StorageStruct> &storage, Handler &&handler)

Installiert eine Speicherlösung nach dem Prinzip „ handler “ für den „ storage “, um die endgültigen Daten dynamisch aus dem laufenden Aufgabenbaum abzurufen.

Der StorageHandler benötigt eine const -Referenz auf die StorageStruct -Instanz:

static QByteArray load(const QString&fileName) {... }

Storage<QByteArray> storage;

const auto onLoaderSetup = [](QThreadFunction<QByteArray> &task) {
    task.setThreadFunctionData(&load, "foo.txt");
};
const auto onLoaderDone = [storage](const QThreadFunction<QByteArray> &task) {
    *storage = task.result();
};

const Group root {
    storage,
    QThreadFunctionTask(onLoaderSetup, onLoaderDone, CallDoneFlag::OnSuccess)
};

QTaskTree taskTree(root);
auto collectStorage = [](const QByteArray&storage){
    qDebug() << "final content" << storage;
};
taskTree.onStorageDone(storage, collectStorage);
taskTree.start();

Wenn der laufende Aufgabenbaum im Begriff ist, eine „ Group “ zu verlassen, in der sich der „ storage “ befindet, zerstört er eine „ StorageStruct “-Instanz. Unmittelbar bevor die „ StorageStruct “-Instanz zerstört wird und nachdem alle möglichen Handler dieser Gruppe aufgerufen wurden, ruft der Aufgabenbaum die übergebene „ handler “ auf. Dies ermöglicht es, den endgültigen Inhalt des angegebenen Speichers dynamisch auszulesen und außerhalb des Aufgabenbaums weiterzuverarbeiten.

Dieser Handler wird auch aufgerufen, wenn der laufende Baum abgebrochen wird. Er wird jedoch nicht aufgerufen, wenn der laufende Baum zerstört wird.

Siehe auch „ onStorageSetup()“.

template <typename StorageStruct, typename Handler> void QTaskTree::onStorageSetup(const QtTaskTree::Storage<StorageStruct> &storage, Handler &&handler)

Installiert eine Speicher handler, damit die „ storage “ die Anfangsdaten dynamisch an den laufenden Aufgabenbaum weitergeben kann.

Der „ StorageHandler “ erhält eine Referenz auf die „ StorageStruct “-Instanz:

static void save(const QString &fileName, const QByteArray &array) { ... }

Storage<QByteArray> storage;

const auto onSaverSetup = [storage](QThreadFunction<QByteArray> &task) {
    task.setThreadFunctionData(&save, "foo.txt", *storage);
};

const Group root {
    storage,
    QThreadFunctionTask(onSaverSetup)
};

QTaskTree taskTree(root);
auto initStorage = [](QByteArray &storage){
    storage = "initial content";
};
taskTree.onStorageSetup(storage, initStorage);
taskTree.start();

Wenn der laufende Aufgabenbaum eine Gruppe betritt, in der sich der „ storage “ befindet, erstellt er eine „ StorageStruct “-Instanz, die innerhalb dieser Gruppe einsatzbereit ist. Unmittelbar nach der Erstellung der „ StorageStruct “-Instanz und bevor ein Handler dieser Gruppe aufgerufen wird, ruft der Aufgabenbaum die übergebene Funktion ` handler` auf. Dies ermöglicht die dynamische Einrichtung der Anfangsdaten für den angegebenen Speicher. Später, wenn ein Handler einer Gruppe aufgerufen wird, aktiviert der Aufgabenbaum den erstellten und initialisierten Speicher, sodass er innerhalb des Handlers jeder Gruppe verfügbar ist.

Siehe auch „ onStorageDone()“.

qsizetype QTaskTree::progressMaximum() const

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

Siehe auch ` progressValue()`.

qsizetype QTaskTree::progressValue() const

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

Die zurückgegebene Zahl gibt an, wie viele Aufgaben während der Ausführung des Aufgab baums bereits abgeschlossen, abgebrochen oder übersprungen wurden. Beim Start des Aufgab baums wird diese Zahl auf 0 gesetzt. Nach Abschluss des Aufgab baums entspricht diese Zahl immer progressMaximum().

Siehe auch progressMaximum() und progressValueChanged().

[signal] void QTaskTree::progressValueChanged(qsizetype value)

Dieses Signal wird ausgelöst, wenn der ausgeführte Aufgabenbaum beendet, abgebrochen oder einige Aufgaben übersprungen wurden. Das Signal „ value “ gibt die aktuelle Gesamtzahl der abgeschlossenen, abgebrochenen oder übersprungenen Aufgaben an. Wenn der Aufgabenbaum gestartet wird und nachdem das Signal „ started()“ ausgelöst wurde, wird dieses Signal mit einem anfänglichen Wert „ value “ von „ 0 “ ausgelöst. Wenn der Aufgabenbaum kurz vor dem Abschluss steht und bevor das Signal „ done()“ ausgelöst wird, wird dieses Signal mit dem endgültigen Wert „ value “ von „ progressMaximum()“ ausgelöst.

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

QtTaskTree::DoneWith QTaskTree::runBlocking()

Führt eine lokale Ereignisschleife mit „ QEventLoop::ExcludeUserInputEvents “ aus und startet den Aufgabenbaum.

Gibt „ DoneWith::Success “ zurück, wenn der Aufgabenbaum erfolgreich abgeschlossen wurde; andernfalls wird „ DoneWith::Error “ zurückgegeben.

Siehe auch ` start()`.

[static] QtTaskTree::DoneWith QTaskTree::runBlocking(const QtTaskTree::Group &recipe)

Erstellt einen temporären Aufgabenbaum unter Verwendung des übergebenen ` recipe ` und führt ihn blockierend aus.

Gibt ` DoneWith::Success ` zurück, wenn der Aufgabenbaum erfolgreich abgeschlossen wurde; andernfalls wird ` DoneWith::Error` zurückgegeben.

Siehe auch ` start()`.

QtTaskTree::DoneWith QTaskTree::runBlocking(const QFuture<void> &future)

Das übergebene ` future ` wird zum Abhören des „cancel“-Ereignisses verwendet. Wenn der Aufgabenbaum abgebrochen wird, bricht diese Methode die übergebene ` future` ab.

[static] QtTaskTree::DoneWith QTaskTree::runBlocking(const QtTaskTree::Group &recipe, const QFuture<void> &future)

Der übergebene ` future ` wird zum Abhören des Abbruch-Ereignisses verwendet. Wenn der Aufgabenbaum abgebrochen wird, bricht diese Methode die übergebene ` future` ab.

void QTaskTree::setRecipe(const QtTaskTree::Group &recipe)

Legt eine bestimmte „ recipe “ für den Aufgabenbaum fest. Nachdem der Aufgabenbaum gestartet wurde, führt er die in der „ recipe “ enthaltenen Aufgaben aus und verarbeitet abgeschlossene Aufgaben gemäß der übergebenen Beschreibung.

Siehe auch ` QTaskTree(const QtTaskTree::Group &recipe, QObject *parent = nullptr)` und ` start()`.

void QTaskTree::start()

Startet den Aufgabenbaum.

Verwenden Sie ` setRecipe()` oder den Konstruktor, um die deklarative Beschreibung festzulegen, nach der der Aufgabenbaum die enthaltenen Aufgaben ausführt und abgeschlossene Aufgaben verarbeitet.

Ist der Aufgabenbaum leer, d. h. wurde er mit einem Standardkonstruktor erstellt, hat ein Aufruf von `start()` keine Auswirkung, und es wird die entsprechende Warnmeldung ausgegeben.

Andernfalls, wenn der Aufgabenbaum bereits läuft, wird ein Aufruf von start() ignoriert und die entsprechende Warnmeldung ausgegeben.

Andernfalls wird der Aufgabenbaum gestartet.

Der gestartete Aufgabenbaum kann synchron beendet werden, beispielsweise wenn der Start-Handler der Hauptgruppe ` SetupResult::StopWithError` zurückgibt. Aus diesem Grund sollte die Verbindung zum `done`-Signal vor dem Aufruf von `start()` hergestellt werden. Verwenden Sie ` isRunning()`, um festzustellen, ob der Aufgabenbaum nach einem Aufruf von `start()` noch läuft.

Die Implementierung des Aufgabenbaums stützt sich auf die laufende Ereignisschleife. Stellen Sie sicher, dass beim Aufruf dieser Methode ein ` QEventLoop`, ` QCoreApplication` oder eine ihrer Unterklassen läuft (oder kurz vor dem Start steht).

Siehe auch QTaskTree(const QtTaskTree::Group &recipe, QObject *parent = nullptr), setRecipe(), isRunning() und cancel().

[signal] void QTaskTree::started()

Dieses Signal wird beim Start des Aufgabenbaums ausgelöst. Auf die Auslösung dieses Signals folgt synchron das Signal „ progressValueChanged()“ mit dem Anfangswert „ 0 “.

Siehe auch „ start()“ und „ done()“.

qsizetype QTaskTree::taskCount() const

Gibt die Anzahl der im gespeicherten Rezept enthaltenen asynchronen Aufgaben zurück.

Siehe auch ` setRecipe()` und ` progressMaximum()`.