Tasking::TaskTree Class

Detaljan opis

Koristite imenski prostor Tasking za izgradnju proširivih, deklarativnih stablastih struktura zadataka koje mogu sadržavati asinkrone zadatke, kao što su QProcess, NetworkQuery ili ConcurrentCall<ReturnType>. Strukture TaskTree omogućuju vam stvaranje sofisticirane mješavine paralelnog ili sekvencijalnog toka zadataka u obliku stabla i pokretanje u bilo kojem trenutku kasnije.

Koren elementa i zadaci

TaskTree ima obavezni korijenski element Group, koji može sadržavati bilo koji broj zadataka različitih vrsta, kao što su QProcessTask, NetworkQueryTask ili ConcurrentCallTask<ReturnType>:

using namespace Tasking;

const Group root {
    QProcessTask(...),
    NetworkQueryTask(...),
    ConcurrentCallTask<int>(...)
};

TaskTree *taskTree = new TaskTree(root);
connect(taskTree, &TaskTree::done, ...);  // finish handler
taskTree->start();

Gornje stablo zadataka ima element najviše razine tipa Group koji sadrži zadatke tipova QProcessTask, NetworkQueryTask i ConcurrentCallTask<int>. Nakon poziva metode taskTree->start(), zadaci se izvršavaju u nizu, počevši od QProcessTask-a. Kada se QProcessTask uspješno završi, pokreće se zadatak NetworkQueryTask. Na kraju, kada mrežna zadatka završi uspješno, pokreće se zadatak ConcurrentCallTask<int>.

Kada se posljednji aktivni zadatak uspješno završi, stablo zadataka smatra se uspješno izvršenim i signal done() se emitira s argumentom DoneWith::Success. Kada se zadatak završi s greškom, izvršavanje stabla zadataka se zaustavlja i preostali zadaci se preskaču. Stablo zadataka završava s greškom i šalje signal TaskTree::done() s argumentom DoneWith::Error.

Grupe

Roditelj grupe vidi je kao jedan zadatak. Kao i drugi zadaci, grupa se može pokrenuti i može završiti uspješno ili s pogreškom. Elementi grupe mogu se ugniježđivati kako bi se stvorila stablo struktura:

const Group root {
    Group {
        parallel,
        QProcessTask(...),
        ConcurrentCallTask<int>(...)
    },
    NetworkQueryTask(...)
};

Gornji primjer razlikuje se od prvog primjera po tome što korijenski element ima podgrupu koja sadrži QProcessTask i ConcurrentCallTask<int>. Podgrupa je sestrinski element NetworkQueryTask-a u korijenu. Podgrupa sadrži dodatni paralelni element koji nalaže svojoj Grupi da izvršava svoje zadatke paralelno.

Dakle, kada se pokrene gornje stablo, QProcessTask i ConcurrentCallTask<int> odmah se pokreću i izvršavaju se paralelno. Budući da korijenska grupa ne sadrži paralelni element, njezini se zadaci izravnih podređenih elemenata izvršavaju slijedom. Tako se NetworkQueryTask pokreće kada cijela podgrupa završi. Grupa se smatra završenom kada svi njezini zadaci završe. Redoslijed u kojem zadaci završavaju nije bitan.

Dakle, ovisno o tome koji zadatak traje dulje (QProcessTask ili ConcurrentCallTask<int>), mogu se dogoditi sljedeći scenariji:

Razlike između scenarija označene su podebljanim slovima. Tri točke znače da između prethodnog i sljedećeg događaja prolazi neodređeno vrijeme (zadatak ili zadaci se nastavljaju izvršavati). Nema točaka između događaja znači da se oni odvijaju sinkrono.

Predstavljeni scenariji pretpostavljaju da se svi zadaci uspješno izvršavaju. Ako zadatak tijekom izvršavanja zakaže, stablo zadataka završava s pogreškom. Posebno, kada QProcessTask završi s pogreškom dok se ConcurrentCallTask<int> još uvijek izvršava, ConcurrentCallTask<int> se automatski otkazuje, podskupina završava s pogreškom, NetworkQueryTask se preskače i stablo završava s pogreškom.

Vrste zadataka

Svaka vrsta zadatka povezana je sa svojom odgovarajućom klasom zadataka koja izvršava zadatak. Na primjer, QProcessTask unutar stabla zadataka povezan je s klasom QProcess koja izvršava proces. Povezani objekti automatski se stvaraju, pokreću i uništavaju isključivo od strane stabla zadataka u odgovarajućem trenutku.

Ako se korijenska grupa sastoji od pet uzastopnih zadataka QProcessTask, a stablo zadataka izvršava grupu, ono stvara instancu klase QProcess za prvi QProcessTask i pokreće ga. Ako se instanca klase QProcess uspješno završi, stablo zadataka je uništava i stvara novu instancu klase QProcess za drugi QProcessTask, i tako dalje. Ako se prvi zadatak završi s pogreškom, stablo zadataka prestaje stvarati instance klase QProcess, a korijenska grupa završava s pogreškom.

Sljedeća tablica prikazuje primjere vrsta zadataka i njihovih odgovarajućih klasa zadataka:

Obrađivači zadataka

Koristite rukovatelje zadataka za postavljanje zadatka za izvršavanje i omogućavanje čitanja izlaznih podataka iz zadatka kada se on završi uspješno ili s pogreškom.

Početni rukovatelj zadatka

Kada se stvori odgovarajući objekt klase zadatka i prije nego što se pokrene, stablo zadataka poziva opcionalno korisnikom osiguranog upravljača za postavljanje. Upravljač za postavljanje uvijek bi trebao uzeti referencu na povezani objekt klase zadatka:

const auto onSetup = [](QProcess &process) {
    process.setProgram("sleep");
    process.setArguments({"3"});
};
const Group root {
    QProcessTask(onSetup)
};

Možete izmijeniti proslijeđeni QProcess u setup handleru, kako bi stablo zadataka moglo pokrenuti proces prema vašoj konfiguraciji. Ne biste trebali pozvati process.start(); u setup handleru, jer ga stablo zadataka poziva kada je potrebno. Setup handler je neobavezan. Kada se koristi, mora biti prvi argument konstruktora zadatka.

Po želji, setup handler može vratiti SetupResult. Vraćeni SetupResult utječe na daljnje ponašanje pri pokretanju zadane zadatke. Moguće vrijednosti su:

Ovo je korisno za pokretanje zadatka samo kada je zadovoljena određena uvjetna, a podaci potrebni za procjenu tog uvjeta nisu poznati dok prethodno pokrenuti zadaci ne završe. Na taj način, upravljački program za postavljanje dinamički odlučuje hoće li normalno pokrenuti odgovarajući zadatak ili ga preskočiti i izvijestiti o uspjehu ili pogrešci. Za više informacija o razmjeni podataka između zadataka pogledajte Storage.

Rukovatelj dovršetka zadatka

Kada se pokrenuta zadatka završi, stablo zadataka poziva opcionalno navedeni rukovatelj završetka. Rukovatelj bi trebao primiti referencu na const povezani objekt klase zadatka:

const auto onSetup = [](QProcess&process) {
    process.setProgram("sleep");
    process.setArguments({"3"});
};
const auto onDone = [](const QProcess&process, DoneWith result) {
    if (result== DoneWith::Success)
        qDebug() << "Success" << process.cleanedStdOut();
   inače
        qDebug() << "Failure" << process.cleanedStdErr();
};
const Group root {
    QProcessTask(onSetup, onDone)
};

Rukovatelj događaja 'done' može prikupiti izlazne podatke iz QProcess-a i pohraniti ih za daljnju obradu ili izvršiti dodatne radnje.

Grupni rukovatelji

Slično upravljačima zadataka, upravljači grupa omogućuju vam postavljanje grupe za izvršavanje i primjenu dodatnih radnji kada cijela grupa završi uspješno ili s pogreškom.

Početni rukovatelj grupe

Drvo zadataka poziva rukovatelja početka grupe prije nego što pokrene podređene zadatke. Rukovatelj grupe ne prima nikakve argumente:

const auto onSetup = [] {
    qDebug() << "Entering the group";
};
const Group root {
    onGroupSetup(onSetup),
    QProcessTask(...)
};

Rukovatelj postavljanja grupe je neobavezan. Da biste definirali rukovatelj postavljanja grupe, dodajte element onGroupSetup() u grupu. Argument funkcije onGroupSetup() je korisnički rukovatelj. Ako u grupu dodate više od jednog elementa onGroupSetup(), tijekom izvođenja se pokreće assert koji uključuje poruku o pogrešci.

Poput rukovatelja početkom zadatka, rukovatelj početkom grupe može vratiti SetupResult. Vraćena vrijednost SetupResult utječe na ponašanje pri pokretanju cijele grupe. Ako ne navedete rukovatelja početkom grupe ili je njegov tip povrata void, zadano djelovanje grupe je SetupResult::Continue, tako da se svi zadaci pokreću normalno. Inače, kada rukovatelj početkom vrati SetupResult::StopWithSuccess ili SetupResult::StopWithError, zadaci se ne pokreću (preskaču se) i sama grupa prijavljuje uspjeh ili neuspjeh, ovisno o vraćenoj vrijednosti.

const Group root {
    onGroupSetup([] { qDebug() << "Root setup"; }),
    Group {
        onGroupSetup([] { qDebug() << "Group 1 setup"; return SetupResult::Continue; }),
        QProcessTask(...) // Process 1
    },
    Group {
        onGroupSetup([] { qDebug() << "Group 2 setup"; return SetupResult::StopWithSuccess; }),
        QProcessTask(...) // Process 2
    },
    Group {
        onGroupSetup([] { qDebug() << "Group 3 setup"; return SetupResult::StopWithError; }),
        QProcessTask(...) // Process 3
    },
    QProcessTask(...) // Process 4
};

U gornjem primjeru sve podgrupe korijenske grupe definiraju svoje rukovatelje postavljanja. Sljedeći scenarij pretpostavlja da se svi pokrenuti procesi završe uspješno:

Rukovatelj završetka grupe

Rukovatelj završetka grupe izvršava se nakon uspješnog ili neuspješnog izvršavanja njenih zadataka. Konačna vrijednost koju grupa prijavljuje ovisi o njezinom Workflow Policy u. Rukovatelj može poduzeti i druge potrebne radnje. Rukovatelj završetka definira se unutar elementa onGroupDone() grupe. Može primati neobavezni argument DoneWith, koji označava uspješno ili neuspješno izvršavanje:

const Group root {
    onGroupSetup([] { qDebug() << "Postavljanje korijena"; }),
    QProcessTask(...),
    onGroupDone([](DoneWith result) {
        if (result== DoneWith::Success)
            qDebug() << "Root finished with success";
       inače
            qDebug() << "Root finished with an error";
    })
};

Handler grupe je neobavezan. Ako u grupu dodate više od jednog onGroupDone()-a, tijekom izvođenja pokreće se assert koji uključuje poruku o pogrešci.

Ostali elementi grupe

Grupa može sadržavati i druge elemente koji opisuju tijek obrade, poput načina izvršavanja ili pravila tijeka rada. Također može sadržavati elemente za pohranu koji su odgovorni za prikupljanje i dijeljenje prilagođenih zajedničkih podataka prikupljenih tijekom izvršavanja grupe.

Način izvršavanja

Element načina izvršavanja u grupi određuje kako se pokreću izravni podzadaci grupe. Najčešći načini izvršavanja su sequential i parallel. Također je moguće odrediti ograničenje broja zadataka koji se izvršavaju paralelno pomoću funkcije parallelLimit().

U svim načinima izvršavanja grupa pokreće zadatke redoslijedom kojim se pojavljuju.

Ako je podgrupa također grupa, podgrupa pokreće svoje zadatke prema vlastitom načinu izvršavanja.

Pravilo tijeka rada

Element pravila tijeka rada u grupi određuje kako se grupa treba ponašati kada se završi bilo koji zadatak njezina izravnog podređenog člana. Za detaljan opis mogućih pravila pogledajte WorkflowPolicy.

Ako je podgrupa također grupa, podgrupa izvršava svoje zadatke u skladu sa svojom vlastitom politikom tijeka rada.

Pohrana

Koristite element Storage za razmjenu informacija između zadataka. Posebno u načinu sekvencijalne izvedbe, kada zadatak treba podatke iz drugog, već dovršenog zadatka prije nego što može započeti. Na primjer, stablo zadataka koje kopira podatke čitajući ih iz izvora i zapisujući ih na odredište moglo bi izgledati ovako:

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

static Group copyRecipe(const QString&source, const QString&destination)
{
    struct CopyStorage { // [1] prilagođena međuzadaćna struktura
        QByteArray content; // [2] prilagođeni međuzadaćnipodaci
    };

    // [3] instanca prilagođenog međuzadaćnog struktura kojom upravlja stablo zadataka
    const Storage<CopyStorage> storage;

    const auto onLoaderSetup = [source](ConcurrentCall<QByteArray> &async) {
        async.setConcurrentCallData(&load, source);
    };
    // [4] vrijeme izvršavanja: stablo zadataka aktivira instancu iz [7] prije pozivarukovatelja
    const auto onLoaderDone = [storage](const ConcurrentCall<QByteArray> &async) {
        storage->content = async.result(); // [5] učitavač sprema rezultat u pohranu
    };

    // [4] vrijeme izvođenja: stablo zadataka aktivira instancu iz [7] prije pozivanjarukovatelja
    const auto onSaverSetup = [storage, destination](ConcurrentCall<void> &async) {
        const QByteArray content = storage->content; // [6] spremač uzima podatke izpohr ane
        async.setConcurrentCallData(&save, destination, content);
    };
    const auto onSaverDone = [](const ConcurrentCall<void> &async) {
        qDebug() << "Save done successfully";
    };

    const Group root {
        // [7] runtime: stablo zadataka stvara instancu CopyStorage kada se uđe u root
        storage,
        ConcurrentCallTask<QByteArray>(onLoaderSetup, onLoaderDone, CallDone::OnSuccess),
        ConcurrentCallTask<void>(onSaverSetup, onSaverDone, CallDone::OnSuccess)
    };
    return root;
}

const QString source =...;
const QString destination =...;
TaskTree taskTree(copyRecipe(source, destination));
connect(&taskTree, &TaskTree::done,
        &taskTree, [](DoneWith result) {
    if (result== DoneWith::Success)
        qDebug() << "The copying finished successfully.";
});
tasktree.start();

U gornjem primjeru, podaci između zadataka sastoje se od varijable sadržaja QByteArray [2] obuhvaćene prilagođenom strukturom CopyStorage [1]. Ako se učitavanje uspješno završi, podaci se spremaju u varijablu CopyStorage::content [5]. Spremač zatim koristi tu varijablu za konfiguriranje zadatka spremanja [6].

Kako bi se omogućilo upravljanje strukturom CopyStorage u stablu zadataka, stvara se instanca strukture Storage<CopyStorage> [3]. Ako se kopija ovog objekta umeće kao podređeni element grupe [7], instanca strukture CopyStorage dinamički se stvara kada stablo zadataka uđe u tu grupu. Kada stablo zadataka napusti tu grupu, postojeća instanca strukture CopyStorage uništava se jer više nije potrebna.

Ako se istovremeno pokreće nekoliko stabala zadataka koja drže kopiju zajedničke instance strukture Storage<CopyStorage> (uključujući slučaj kada se stabla zadataka pokreću u različitim nitima), svako stablo zadataka sadrži svoju kopiju strukture CopyStorage.

Možete pristupiti strukturi CopyStorage iz bilo kojeg handler-a u grupi s objektom za pohranu. To uključuje sve handler-e svih potomskih zadataka te grupe. Da biste pristupili prilagođenoj strukturi u handler-u, proslijedite kopiju objekta Storage<CopyStorage> tom handler-u (na primjer, u lambda-zabravi) [4].

Kada stablo zadataka pozove rukovatelja u podstablu koje sadrži spremište [7], stablo zadataka aktivira vlastiti primjerak CopyStorage unutar objekta Storage<CopyStorage>. Stoga se strukturi CopyStorage može pristupiti samo unutar tijela rukovatelja. Za pristup trenutno aktivnom CopyStorage unutar Storage<CopyStorage>, upotrijebite metodu Storage::operator->(), Storage::operator*(), ili Storage::activeStorage().

Sljedeći popis sažima kako upotrijebiti objekt Storage u stablu zadataka:

1. Definirajte prilagođenu strukturu MyStorage s prilagođenim podacima [1], [2]
2. Stvorite instancu pohrane Storage<MyStorage> [3]
3. Proslijedite instancu Storage<MyStorage> u rukovatelje [4]
4. Pristupite instanci MyStorage u handlerima [5], [6]
5. Umetnite instancu Storage<MyStorage> u grupu [7]

Klasa TaskTree

TaskTree izvršava stablo asinkronih zadataka prema receptu opisanom od strane korijenskog elementa grupe.

Budući da je TaskTree također asinhroni zadatak, može biti dio drugog TaskTree-a. Da biste smjestili ugniježđeni TaskTree unutar drugog TaskTree-a, umetnite element TaskTreeTask u drugi element Group.

TaskTree tijekom izvođenja izvještava o napretku dovršenih zadataka. Vrijednost napretka povećava se kada se zadatak završi ili preskoči ili otkaže. Kada je TaskTree dovršen i emitira se signal TaskTree::done(), trenutna vrijednost napretka jednaka je maksimalnoj vrijednosti napretka. Maksimalni napredak jednak je ukupnom broju asinkronih zadataka u stablu. Ugniježđeni TaskTree računa se kao jedan zadatak, a njegovi podređeni zadaci se ne računaju u stablu najviše razine. Grupe same po sebi se ne računaju kao zadaci, ali se računaju njihovi zadaci. Zadaci grupe ' Sync ' nisu asinkroni, stoga se ne računaju kao zadaci.

Za postavljanje dodatnih početnih podataka za aktivno stablo, izmijenite instance pohrane u stablu prilikom njihova stvaranja instaliranjem rukovatelja za postavljanje pohrane:

Storage<CopyStorage> storage;
const Group root = ...; // storage placed inside root's group and inside handlers
TaskTree taskTree(root);
auto initStorage = [](CopyStorage &storage) {
    storage.content = "initial content";
};
taskTree.onStorageSetup(storage, initStorage);
taskTree.start();

Kada stablo zadataka u tijeku stvori instancu CopyStorage i prije nego što se pozove bilo koji handler unutar stabla, stablo zadataka poziva handler initStorage kako bi omogućilo postavljanje početnih podataka pohrane, jedinstvenih za ovo posebno izvođenje taskTree-a.

Slično tome, za prikupljanje dodatnih rezultatskih podataka iz aktivnog stabla, pročitajte ih iz instanci pohrane u stablu kada se one spremaju uništiti. Da biste to učinili, instalirajte rukovatelja za završetak pohrane (storage done handler):

Storage<CopyStorage> storage;
const Group root =...; // spremište postavljeno unutar root grupe i unutarhandlera
TaskTree taskTree(root);
auto collectStorage = [](const CopyStorage &storage) {
    qDebug() << "final content" << storage.content;
};
taskTree.onStorageDone(storage, collectStorage);
taskTree.start();

Kada se pokretno stablo zadataka sprema uništiti instancu spremnika ( CopyStorage ), stablo zadataka poziva rukovatelj collectStorage kako bi omogućilo čitanje konačnih podataka iz spremnika, jedinstvenih za ovu konkretnu izvedbu taskTree-a.

Prilagodnici zadataka

Za proširenje TaskTree-a novom vrstom zadatka implementirajte jednostavnu adapter klasu naslijeđenu od predloška klase TaskAdapter. Sljedeća klasa je adapter za jednokratni tajmer, koji se može smatrati novim asinkronim zadatkom:

class TimerTaskAdapter : public TaskAdapter<QTimer>
{
public:
    TimerTaskAdapter() {
        task()->setSingleShot(true);
        task()->setInterval(1000);
        connect(task(), &QTimer::timeout, this, [this] { emit done(DoneResult::Success); });
    }
private:
    void start() final { task()->start(); }
};

using TimerTask = CustomTask<TimerTaskAdapter>;

Prilagođeni adapter morate naslijediti od predloška klase TaskAdapter instanciranog s predloškom parametra klase koja implementira zadatak u tijeku. Gornji kôd koristi QTimer za pokretanje zadatka. Ta se klasa kasnije pojavljuje kao argument rukovateljima zadatka. Instanca ovog parametra klase automatski postaje član predloška TaskAdapter i dostupna je putem metode TaskAdapter::task(). Konstruktor klase TimerTaskAdapter početno konfigurira objekt QTimer i povezuje se sa signalom QTimer::timeout() (signal za prekid). Kada se signal aktivira, klasa TimerTaskAdapter emitira signal TaskInterface::done(DoneResult::Success) kako bi obavijestila stablo zadataka da je zadatak uspješno završen. Ako emitira signal TaskInterface::done(DoneResult::Error), zadatak je završen s greškom. Metoda TaskAdapter::start() pokreće tajmer.

Da bi QTimer bio dostupan unutar TaskTree-a pod imenom TimerTask, definirajte TimerTask kao alias za CustomTask<TimerTaskAdapter>. TimerTask postaje novi prilagođeni tip zadatka, koristeći TimerTaskAdapter.

Nova vrsta zadatka je sada registrirana i možete je koristiti u TaskTree:

const auto onSetup = [](QTimer &task) { task.setInterval(2000); };
const auto onDone = [] { qDebug() << "timer triggered"; };
const Group root {
    TimerTask(onSetup, onDone)
};

Kada se pokrene stablo zadataka koje sadrži korijen iz gornjeg primjera, ispisuje se poruka za otklanjanje pogrešaka unutar dvije sekunde, a zatim se uspješno završava.