klasse ara::exec::StateClient

De interface ara::exec::StateClient stelt State Management in staat om toestandswijzigingen voor functiegroepen aan te vragen bij Execution Management, om zo de uitvoering van toegewezen processen op een Machine te besturen [SWS_EM_02278]. Bij de aanmaak via Create() moet een continu geldige callback voor onverwachte ongedefinieerde toestanden worden geregistreerd [SWS_EM_02276]. Naast asynchrone toestandsovergangen biedt de niet-kopieerbare klasse methoden voor het opvragen van het opstartresultaat van de Machine en voor foutanalyse bij uitvoeringsfouten [SWS_EM_02279], [SWS_EM_02542].

meer ›

Context

De klasse ara::exec::StateClient vormt de interface van Execution Management waarmee State Management toestandsovergangen voor functiegroepen (Function Groups) aanvraagt en bestuurt. State Management gebruikt deze client gedurende de gehele bedrijfstijd van een Machine om processen gericht te starten of te beëindigen. De integrator wijst softwarecomponenten toe aan specifieke toestanden van een functiegroep. Als State Management deze software wil uitvoeren, verzoekt het via de StateClient bij Execution Management om de overgang naar de betreffende functiegroeptoestand; het stoppen gebeurt analoog door overgang naar een toestand waarin de software niet actief behoort te zijn [SWS_EM_02278].

Contextdiagram: samenspel tussen State Management, StateClient en Execution Management. Bronnen: [SWS_EM_02276], [SWS_EM_02278]

Levenscyclus

Instanties van StateClient kunnen worden aangemaakt via de benoemde constructor Create() [SWS_EM_02276] als ara::core::Result<StateClient> of via de reguliere constructor StateClient() [SWS_EM_02561]. Beide constructiepaden vereisen verplicht een callback-parameter undefinedStateCallback van het type std::function<void(const ara::exec::ExecutionErrorEvent&)>. Deze callback wordt door de StateClient-bibliotheek geactiveerd wanneer een functiegroep onverwacht en zonder voorafgaand verzoek door SetState() overgaat naar een ongedefinieerde toestand. De aanroeper moet ervoor zorgen dat deze callback gedurende de gehele levensduur van de StateClient-instantie aanroepbaar blijft, wat in het bijzonder relevant is bij objectbindingen via std::bind [SWS_EM_02276], [SWS_EM_02561].

Kopieerbewerkingen zijn voor StateClient expliciet uitgesloten: zowel de copy-constructor [SWS_EM_02565] als de copy-toewijzingsoperator [SWS_EM_02568] zijn verwijderd (=delete). Eigendomsoverdracht is uitsluitend mogelijk via move-semantiek met behulp van move-constructor [SWS_EM_02566] en move-toewijzing [SWS_EM_02567]. Met betrekking tot concurrency zijn de functionele methoden zoals SetState(), GetExecutionError() en GetInitialMachineStateTransitionResult() evenals de aanmaak thread-safe ontworpen [SWS_EM_02276], [SWS_EM_02278], [SWS_EM_02279], [SWS_EM_02542]. Daarentegen zijn de move-bewerkingen en de destructor ~StateClient() niet thread-safe [SWS_EM_02277], [SWS_EM_02566], [SWS_EM_02567].

Gebruikspad

Een typische applicatiecyclus is onderverdeeld in initialisatie, opvragen van het opstartresultaat, reguliere toestandswijzigingen en foutbewaking:

1. Aanmaak: State Management instantieert StateClient onder opgave van een geldige callback voor foutsignalering via Create() [SWS_EM_02276].
2. Initieel opstartresultaat opvragen: met GetInitialMachineStateTransitionResult() verzoekt State Management het resultaat van de initiële toestandsovergang naar de startup-toestand [SWS_EM_02279]. Omdat deze overgang exact één keer per levenscyclus van de Machine plaatsvindt, blijft de geleverde ara::core::Future<void> stabiel en verandert deze niet meer tot een herstart.
3. Toestandswijziging aanvragen: Met SetState() vraagt State Management asynchrone toestandsovergangen aan voor afzonderlijke functiegroepen [SWS_EM_02278]. De methode keert direct terug en levert een ara::core::Future<void> op om de voltooiing op te vragen. Zodra de opdracht bij Execution Management is binnengekomen, wordt deze onafhankelijk van de verdere levensduur van de aanroepende instantie uitgevoerd.
4. Fouttoestanden onderzoeken: Als een functiegroep onverwacht in een ongedefinieerde toestand terechtkomt, kan via GetExecutionError() de veroorzakende uitvoeringsfout in de vorm van een ara::exec::ExecutionErrorEvent worden bepaald [SWS_EM_02542].

Sequentiediagram: verloop van aanmaak, opvragen van de begintoestand, asynchrone toestandswijziging en foutanalyse. Bronnen: [SWS_EM_02276], [SWS_EM_02279], [SWS_EM_02278], [SWS_EM_02542]

Foutscenario's

De bewerkingen van de klasse communiceren fouten via foutcodes van ExecErrorDomain:

• ExecErrc::kNoCommunication: Signaleert communicatiestoringen naar Execution Management, bijvoorbeeld bij een verbroken IPC-verbinding. Treedt op bij Create() [SWS_EM_02276], SetState() [SWS_EM_02278], GetInitialMachineStateTransitionResult() [SWS_EM_02279] en GetExecutionError() [SWS_EM_02542]. Het beoogde herstel bestaat uit een herhaalde aanroep.
• ExecErrc::kInvalidArgument: Wordt door Create() en StateClient() gemeld als de meegegeven callback geen aanroepbare functie bevat [SWS_EM_02276], [SWS_EM_02561].
• ExecErrc::kOperationCanceled: Geeft bij SetState() aan dat een lopende overgang door een recentere aanvraag is afgebroken [SWS_EM_02278]. Bij GetInitialMachineStateTransitionResult() treedt deze fout op wanneer de initiële startovergang is afgebroken, bijvoorbeeld door een onderbroken machine-updatesequentie [SWS_EM_02279].
• ExecErrc::kInvalidTransition: De aangevraagde toestandsovergang is niet toegestaan, bijvoorbeeld de overgang naar de toestand Off voor MachineFG, of de toestand bestaat na een update niet meer [SWS_EM_02278].
• ExecErrc::kInvalidMetaModelIdentifier: De meegegeven toestand bestaat niet in het verwerkte manifest of het proces heeft geen mapping naar de desbetreffende functiegroep [SWS_EM_02278], [SWS_EM_02542]. Als deze fout optreedt bij GetInitialMachineStateTransitionResult(), ontbreekt bij het proces de mapping naar MachineFG, wat duidt op een configuratieprobleem [SWS_EM_02279].
• ExecErrc::kOperationFailed: De overgang is mislukt [SWS_EM_02278]. Bij GetExecutionError() geeft de code aan dat de functiegroep zich niet in een ongedefinieerde toestand bevindt en het probleem vermoedelijk al is verholpen [SWS_EM_02542].
• ExecErrc::kIntegrityOrAuthenticityCheckFailed en ExecErrc::kUnexpectedTermination: Specifieke mislukkingen tijdens SetState() als gevolg van mislukte integriteitscontroles of onverwachte procesbeëindigingen tijdens de transitie [SWS_EM_02278].