Olekumasinad

Vaata Markdownina Muuda teenuses GitHub Dokumentatsioon: 2cc7b2b

Olekumasinad ja töövood lahendavad erinevaid probleeme.

Töövoog vastab küsimusele „milline töö järgmisena käivitatakse?”. Olekumasin vastab küsimusele „millises olekus see objekt on ja millised sündmused on sellest olekust alates lubatud?”. See erinevus on oluline siis, kui loodav objekt pole lihtsalt sammude jada, vaid pikaealine üksus, mis reageerib aja jooksul välisele sisendile, näiteks agendi seanss, vestluslõim, ülevaatuse elutsükkel, pilet või kinnitamisvoog.

Kiire näide

PHP

use Queuety\Enums\StateMachineStatus;
use Queuety\Queuety;

$machine_id = Queuety::machine( 'agent_session' )
    ->version( 'agent-session.v1' )
    ->state( 'awaiting_user' )
    ->on( 'user_message', 'planning' )
    ->state( 'planning' )
    ->action( PlanSessionAction::class )
    ->on( 'planned', 'awaiting_review' )
    ->state( 'awaiting_review' )
    ->on( 'approve', 'completed', ReviewApprovedGuard::class )
    ->on( 'reject', 'awaiting_user' )
    ->state( 'completed', StateMachineStatus::Completed )
    ->dispatch( [ 'thread_id' => 42 ] );

Queuety::machine_event(
    $machine_id,
    'user_message',
    [ 'message' => 'Find competitors for this product' ]
);

Queuety::machine_event(
    $machine_id,
    'approve',
    [ 'approved' => true, 'reviewer' => 'editor@example.com' ]
);

See masin alustab olekus awaiting_user, liigub kasutaja sõnumi saabumisel olekusse planning, laseb järjekorda lisatud toimingul väljastada planned ning ootab seejärel olekus awaiting_review, kuni väline kinnitus seansi lõpetab. Oluline pole üksnes koodi süntaks. Oluline on see, et elutsükkel on selgesõnaline, kontrollitav ja sündmustepõhine.

Kuidas masin töötab

Masinainstantsi käivitamisel salvestab Queuety praeguse oleku nime, avaliku olekuandmestiku, definitsiooni versiooni ja räsi, praeguse oleku jaoks lubatud sissetulevad sündmused ning püsiva sündmuste ajajoone.

Kui masin siseneb olekusse, millel on action(), lisab Queuety järjekorda olekusse sisenemise töö. See toiming võib lihtsalt avalikku olekut värskendada ja jätta masina järgmist sündmust ootama või väljastada _event ning soovi korral _event_payload, et käivitada kohe järgmine üleminek. Kui olekul pole toimingut ega lõppoleku staatust, jääb masin lihtsalt ootama väliseid sündmusi, mis saadetakse Queuety::machine_event() abil.

Töövoogude ja olekumasinate valimine

Kasuta töövoogu, kui käivitus põhineb peamiselt sammudel: hangi andmed, töötle iga üksus, oota, koosta tulemus, lõpeta. See mudel sobib hästi siis, kui algus ja lõpp on selged ning peamine küsimus on, milline töö järgmisena käivitada.

Kasuta olekumasinat, kui lubatud käitumine sõltub elutsükli praegusest etapist. See sobib paremini siis, kui sündmused võivad saabuda eri järjekorras, objekt võib kaua olemas olla või vajad elutsükli selgesõnalist kontrollimist olekute awaiting_user, planning, running_agents, awaiting_review ja completed kaudu.

Kuidas need kaks koos toimivad

Need kaks põhikomponenti toimivad kõige paremini koos, mitte teineteisega konkureerides. Olekutoiming võib käivitada töövoo, kui üleminek nõuab mahukamat täitmist, ning töövoog võib töö lõppedes masinale sündmuse saata. Nii juhib olekumasin elutsüklit, samal ajal kui töövood teevad mahuka või rangelt struktureeritud töö.

Ehitaja ülesehitus

StateMachineBuilder jääb meelega väikeseks. initial() ja state() määravad elutsükli olekugraafi. action() seob järjekorras oleva töö ühe olekuga. on() määrab, millised sündmused võivad masina järgmisse olekusse viia. on_queue(), with_priority() ja max_attempts() määravad, kuidas olekutoiminguid täidetakse, samal ajal kui version() ja idempotency_key() lisavad püsivad käivituse metaandmed. dispatch() loob masina instantsi.

Olekutoimingud võivad pakkuda ka valikulist meetodit config(), kasutades samu ressursipoliitika võtmeid nagu töövoo sammud ja käsitlejad. Nii saab kuluka olekuülemineku paigutada jagatud samaaegsusrühma või lisada sellele suurema kulukaalu, kui toiming tarbib tavalisest sammust rohkem eelarvet.

Laiemat ressursimudelit kirjeldab Ressursihaldus.

Lepingud

Olekusse sisenemise toimingud rakendavad liidest Queuety\Contracts\StateAction:

PHP

namespace Queuety\Contracts;

interface StateAction {
    public function handle( array $state, ?string $event = null, array $event_payload = [], array $payload = [] ): array|string;
}

$payload on toimingu definitsiooni struktureeritud andmestik; kui toiming määrati lihtsa klassinimena, on see tühi. Queuety loob toiminguid new $class() abil, seega peab toiminguklassi konstruktori saama käivitada nõutavate argumentideta.

Olekutoimingud võivad määratleda ka valikulise meetodi config() parameetritega concurrency_group, concurrency_limit ja cost_units, kui järjekorras olev sisenemistoiming peab osalema töötajate vastuvõtus, kaalutud järjekorra või teenusepakkuja eelarve haldamises ning muudes ressursipoliitikates.

Üleminekuvalvurid rakendavad liidest Queuety\Contracts\StateGuard:

PHP

namespace Queuety\Contracts;

interface StateGuard {
    public function allows( array $state, array $event_payload, string $event, array $payload = [] ): bool;
}

Kontrollimise API-d

Kasuta töötavate masinate kontrollimiseks fassaadi:

PHP

$status   = Queuety::machine_status( $machine_id );
$machines = Queuety::list_machines();
$events   = Queuety::machine_timeline( $machine_id );
$trace    = Queuety::machine_trace( $machine_id );
$state    = Queuety::machine_state_at( $machine_id, $event_id );

Olekumasinatel pole WP-CLI käske: wp queuety workflow ... hõlmab ainult töövooge. Kasuta neid PHP API-sid, näiteks wp eval kaudu, et masinaid käsurealt kontrollida.

Need API-d annavad teada praeguse oleku nime, elutsükli staatuse, avaliku oleku, saadaolevad sündmused, definitsiooni metaandmed, täieliku üleminekute ajajoone ning siluri kasutajaliideste jaoks normaliseeritud jäljepaketi. Masinate loendi ridadel on definitsiooni versioon, definitsiooni räsi ja idempotentsusvõti, et loendivaated saaksid kuvada lähte- ja käituskeskkonna versiooni ilma iga masinat eraldi laadimata. Jäljepakett sisaldab rühmitatud olekuid, toorsündmusi, seotud toimingutöid, logisid, artefaktiviiteid, tükiviiteid, käsitleja sisendit ja väljundit, olekut enne ja pärast, konteksti, ajastusi ning struktureeritud vigu.

Agendiseansid

Olekumasinad on eriti kasulikud agendisüsteemides, mis toimivad pigem seansside kui konveieritena. Seanssi, mis liigub läbi olekute awaiting_user, planning, running_agents, awaiting_review ja completed, on tavaliselt lihtsam mõista selgesõnalise elutsüklina kui ühe väga pika töövoo definitsioonina, kus on palju ootamisi ja tagasihüppeid.