QtTaskTree::QTaskTree Class

Dokumentation der Mitgliedsfunktionen

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

Konstruiert einen leeren Aufgabenbaum mit einer gegebenen parent. Verwenden Sie setRecipe(), um eine deklarative Beschreibung zu übergeben, wie der Aufgabenbaum die Aufgaben ausführen soll und wie er die beendeten Aufgaben behandeln soll.

Das Starten eines leeren Aufgabenbaums ist ein No-op und es wird eine entsprechende Warnmeldung ausgegeben.

Siehe auch setRecipe() und start().

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

Konstruiert einen Aufgabenbaum mit einer gegebenen recipe und parent. Nachdem der Aufgabenbaum gestartet wurde, führt er die in recipe enthaltenen Aufgaben aus und behandelt beendete Aufgaben entsprechend der übergebenen Beschreibung.

Siehe auch setRecipe() und start().

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

Zerstört den Aufgabenbaum.

Wenn der Aufgabenbaum läuft, während er zerstört wird, werden alle laufenden Aufgaben sofort abgebrochen. In diesem Fall werden keine Handler aufgerufen, auch nicht die Handler der Gruppen und Aufgaben oder onStorageDone()-Handler. Der Aufgabenbaum sendet auch keine Signale vom Destruktor aus, nicht einmal done() oder progressValueChanged() Signale. Auf dieses Verhalten kann man sich immer verlassen. Es ist völlig sicher, den laufenden Aufgabenbaum zu zerstören.

Es ist ein übliches Muster, den laufenden Task-Baum zu zerstören. Es ist garantiert, dass die Zerstörung schnell abläuft, ohne dass auf die Beendigung der aktuell laufenden Tasks gewartet werden muss, vorausgesetzt, die verwendeten Tasks implementieren ihre Destruktoren auf nicht-blockierende Weise.

Siehe auch cancel().

qsizetype QTaskTree::asyncCount() const

Gibt die aktuelle reale Anzahl asynchroner Aufrufketten zurück.

Der zurückgegebene Wert gibt an, wie oft die Kontrolle zur Ereignisschleife des Aufrufers zurückkehrt, während der Aufgabenbaum ausgeführt wird. Zu Beginn ist dieser Wert 0. Wenn die Ausführung des Aufgabenbaums vollständig synchron beendet wird, bleibt dieser Wert 0. Wenn der Aufgabenbaum asynchrone Aufgaben enthält, die während eines Aufrufs von start() erfolgreich gestartet werden, wird dieser Wert auf 1 erhöht, kurz bevor der Aufruf von start() beendet wird. Später, wenn eine asynchrone Aufgabe beendet ist und mögliche Fortsetzungen gestartet werden, wird dieser Wert erneut erhöht. Das Bumping wird fortgesetzt, bis der Aufgabenbaum beendet ist. Wenn der Aufgabenbaum das Signal done() ausgibt, wird das Bumping beendet. Das Signal asyncCountChanged() wird bei jedem Bumping dieses Wertes ausgegeben.

Siehe auch asyncCountChanged().

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

Dieses Signal wird ausgegeben, 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 gesendet und später bei jedem asyncCount()-Wertanstoß mit einem aktualisierten count -Wert gesendet. Jedes gesendete Signal (außer dem anfänglichen mit dem Wert 0) garantiert, dass der Task-Baum nach der Aussendung noch asynchron läuft.

Siehe auch asyncCount().

void QTaskTree::cancel()

Bricht die Ausführung des laufenden Aufgabenbaums ab.

Bricht alle laufenden Aufgaben sofort ab. Alle laufenden Tasks und Gruppen werden mit einem Fehler beendet, wobei ihre done-Handler mit DoneWith::Cancel aufgerufen werden. Die onStorageDone()-Handler der Speicher werden ebenfalls aufgerufen. Die progressValueChanged()-Signale werden ebenfalls gesendet. Auf dieses Verhalten kann man sich immer verlassen.

Die Funktion cancel() wird synchron ausgeführt, so dass nach einem Aufruf von cancel() alle laufenden Aufgaben beendet sind und der Baum bereits abgebrochen ist. Es ist garantiert, dass cancel() schnell ausgeführt wird, ohne blockierendes Warten auf die Beendigung der laufenden Tasks, vorausgesetzt, die verwendeten Tasks implementieren ihre Destruktoren auf nicht-blockierende Weise.

Wenn der Task-Baum leer ist, d.h. mit einem Standard-Konstruktor erstellt wurde, ist ein Aufruf von cancel() ein No-op und es wird eine 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 ausgegeben, wenn der Aufgabenbaum beendet ist, und übergibt die endgültige result der Ausführung. Der Aufgabenbaum ruft keinen Handler auf und gibt kein Signal mehr aus, nachdem dieses Signal ausgegeben wurde.

Siehe auch started().

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

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

bool QTaskTree::isRunning() const

Gibt true zurück, wenn der Aufgabenbaum gerade ausgeführt wird; andernfalls false.

Siehe auch start() und cancel().

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

Installiert einen Speicherplatz handler für die storage, um die endgültigen Daten dynamisch aus dem laufenden Aufgabenbaum abzurufen.

Die StorageHandler nimmt einen const Verweis auf die StorageStruct Instanz:

static QByteArray load(const QString &Dateiname) { ... }  Speicher<QByteArray> Speicher;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 die storage platziert ist, zerstört er eine StorageStruct Instanz. Unmittelbar vor der Zerstörung der StorageStruct Instanz und nachdem alle möglichen Handler aus dieser Gruppe aufgerufen wurden, ruft der Aufgabenbaum den übergebenen handler auf. Dies ermöglicht es, den endgültigen Inhalt des gegebenen Speichers dynamisch zu lesen und außerhalb des Aufgabenbaums weiter zu verarbeiten.

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 Speichereinrichtung handler für die storage, um die Anfangsdaten dynamisch an den laufenden Aufgabenbaum zu übergeben.

Die StorageHandler nimmt einen Verweis 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 Task-Baum eine Gruppe betritt, in der die storage platziert ist, wird eine StorageStruct Instanz erstellt, die innerhalb dieser Gruppe verwendet werden kann. Unmittelbar nach der Erstellung der StorageStruct Instanz und bevor ein Handler dieser Gruppe aufgerufen wird, ruft der Task-Baum die übergebene handler auf. Auf diese Weise kann der anfängliche Inhalt für den gegebenen Speicher dynamisch eingerichtet werden. Später, wenn ein Handler einer Gruppe aufgerufen wird, aktiviert der Aufgabenbaum den erstellten und initialisierten Speicher, so dass er in jedem Handler der Gruppe verfügbar ist.

Siehe auch onStorageDone().

qsizetype QTaskTree::progressMaximum() const

Gibt das Maximum 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 zeigt an, wie viele Aufgaben bereits abgeschlossen, abgebrochen oder übersprungen wurden, während der Aufgabenbaum läuft. Beim Start des Aufgabenbaums wird diese Zahl auf 0 gesetzt, beim Beenden des Aufgabenbaums ist diese Zahl immer gleich progressMaximum().

Siehe auch progressMaximum() und progressValueChanged().

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

Dieses Signal wird ausgegeben, wenn der laufende Aufgabenbaum einige Aufgaben beendet, abgebrochen oder übersprungen hat. Die value gibt die aktuelle Gesamtzahl der beendeten, abgebrochenen oder übersprungenen Aufgaben an. Wenn der Aufgabenbaum gestartet wird und nachdem das Signal started() ausgegeben wurde, wird dieses Signal mit einem anfänglichen value von 0 ausgegeben. Wenn der Aufgabenbaum kurz vor dem Ende steht und bevor das Signal done() ausgegeben wird, wird dieses Signal mit dem endgültigen value von progressMaximum() ausgegeben.

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 Task-Baum erfolgreich beendet wurde; andernfalls DoneWith::Error.

Siehe auch start().

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

Konstruiert einen temporären Aufgabenbaum unter Verwendung der übergebenen recipe und führt ihn blockierend aus.

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

Siehe auch start().

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

Das übergebene future wird für das Abhören des Abbruchereignisses verwendet. Wenn der Aufgabenbaum abgebrochen wird, storniert diese Methode die übergebene future.

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

Das übergebene future wird für das Abhören des Abbruchereignisses verwendet. Wenn der Aufgabenbaum abgebrochen wird, storniert diese Methode die übergebene future.

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

Setzt eine gegebene recipe für den Aufgabenbaum. Nachdem der Aufgabenbaum gestartet wurde, führt er die in recipe enthaltenen Aufgaben aus und behandelt beendete Aufgaben entsprechend 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ühren und beendete Aufgaben behandeln soll.

Wenn der Aufgabenbaum leer ist, d.h. mit einem Standardkonstruktor konstruiert wurde, ist ein Aufruf von start() ein No-op und die entsprechende Warnmeldung wird ausgegeben.

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

Andernfalls wird der Task-Baum gestartet.

Der gestartete Aufgabenbaum kann synchron beendet werden, z.B. wenn der Starthandler 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 Task-Tree-Implementierung stützt sich auf die laufende Ereignisschleife. Stellen Sie sicher, dass eine QEventLoop, QCoreApplication oder eine ihrer Unterklassen läuft (oder kurz davor ist), wenn Sie diese Methode aufrufen.

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

[signal] void QTaskTree::started()

Dieses Signal wird ausgesendet, wenn der Aufgabenbaum gestartet wird. Auf die Ausgabe dieses Signals folgt synchron das Signal progressValueChanged() mit einem Anfangswert von 0.

Siehe auch start() und done().

qsizetype QTaskTree::taskCount() const

Gibt die Anzahl der asynchronen Aufgaben zurück, die in dem gespeicherten Rezept enthalten sind.

Siehe auch setRecipe() und progressMaximum().