klasse ara::exec::ExecutionClient

De klasse ara::exec::ExecutionClient dient ervoor dat applicatieprocessen hun interne uitvoeringstoestand bindend melden aan Execution Management ([SWS_EM_02003]). Bij de initialisatie neemt deze bovendien het afvangen van het SIGTERM-signaal over en stuurt dit door naar een door de gebruiker gedefinieerde beëindigingshandler in een achtergrondthread ([SWS_EM_02562]). Als move-only object bindt de instantie de signaalafhandeling strikt aan haar levenscyclus en herstelt bij vernietiging de eerdere signaaltoestand. Aanroepers moeten ervoor zorgen dat de geregistreerde callback gedurende de gehele levensduur van de instantie aanroepbaar blijft.

meer ›

Context

De klasse ara::exec::ExecutionClient dient ertoe dat processen op het Adaptive Platform hun interne uitvoeringstoestand melden aan Execution Management ([SWS_EM_02003]). Deze fungeert als gestandaardiseerde interface tussen de draaiende applicatie en het centrale procesbeheer. Naast het doorsturen van toestandsovergangen neemt de instantie de verantwoordelijkheid op zich voor de afhandeling van het besturingssysteemsignaal SIGTERM ([SWS_EM_02562], [SWS_EM_02002]). Bij ontvangst van het signaal voert deze een door de gebruiker gedefinieerde callback uit in een afzonderlijke achtergrondthread om de applicatie een ordentelijke beëindiging mogelijk te maken ([SWS_EM_02562]). Interpretatie: het besturingssysteem of Execution Management zal vermoedelijk het signaal SIGTERM naar het proces verzenden wanneer beëindiging van de uitvoeringseenheid wordt verzocht. Vraag Q-51eee947d01ae8b4 (open)

Contextdiagram: interactie tussen applicatieproces, ExecutionClient, Execution Management en signaalmechanisme. Bronnen: [SWS_EM_02003], [SWS_EM_02562], [SWS_EM_02002].

Levenscyclus

De instantiëring van ara::exec::ExecutionClient vindt naar keuze plaats via de statische factory-methode Create ([SWS_EM_02562]) of de reguliere constructor ([SWS_EM_02560]). Terwijl Create exception-safe (noexcept) is en het resultaat ingekapseld in een ara::core::Result retourneert ([SWS_EM_02562]), is de reguliere constructor gedeclareerd als noexcept(false) ([SWS_EM_02560]). Beide aanmaakpaden verwachten als parameter een aanroepbare std::function<void()>-callback (terminationHandler). Deze callback moet gedurende de gehele levensduur van de ExecutionClient-instantie geldig en aanroepbaar blijven ([SWS_EM_02562], [SWS_EM_02560]).

Wat betreft eigendomsverhoudingen is de klasse ontworpen als move-only: de copy-constructor ([SWS_EM_02563]) en de copy-assignment-operator ([SWS_EM_02564]) zijn expliciet verwijderd (delete). Overdracht van instanties is uitsluitend mogelijk via de move-constructor ([SWS_EM_02580]) en de move-assignment-operator ([SWS_EM_02581]), die beide exception-safe (noexcept), maar niet thread-safe zijn. De factory-methode Create en de constructor zelf gelden als thread-safe ([SWS_EM_02562], [SWS_EM_02560]).

De destructor ~ExecutionClient() is gedefinieerd als noexcept ([SWS_EM_02002]) en is niet thread-safe. Bij het vernietigen van de instantie wordt de verantwoordelijkheid voor het signaal SIGTERM weer afgestaan: de destructor zet de signaalhandler voor SIGTERM terug naar de oorspronkelijke toestand die actief was vóór de instantiëring ([SWS_EM_02002]).

Gebruikspad

Het reguliere verloop is onderverdeeld in initialisatie, toestandsoverdracht en ordentelijke beëindiging:

• Aanmaken: aan het begin van de proceslooptijd wordt de instantie geïnitialiseerd via Create, waarbij de beëindigingshandler wordt doorgegeven ([SWS_EM_02562]). Typisch stelt deze handler een flag in of signaleert synchronisatieprimitieven om draaiende threads te deblokkeren.
• Toestandsmelding: zodra het proces gereed is, meldt het zijn uitvoeringsstatus via ReportExecutionState aan Execution Management ([SWS_EM_02003]). De aanroep is thread-safe en kan vanuit verschillende worker-threads plaatsvinden.
• Signaalontvangst en beëindiging: arriveert tijdens de looptijd een SIGTERM-signaal, dan activeert ExecutionClient asynchroon de opgeslagen terminationHandler in een achtergrondthread ([SWS_EM_02562]). Het proces rondt openstaande taken ordentelijk af.
• Vernietiging: bij het verlaten van de scope herstelt de destructor de oorspronkelijke signaalconfiguratie ([SWS_EM_02002]).

Sequentiediagram: verloop van aanmaken via toestandsmelding tot signaalgestuurde beëindiging. Bronnen: [SWS_EM_02562], [SWS_EM_02003], [SWS_EM_02002].

Foutscenario's

Bij het gebruik van ExecutionClient worden verschillende foutsituaties gedekt door foutcodes uit ara::exec::ExecErrc:

• ara::exec::ExecErrc::kInvalidArgument: treedt op bij instantiëring via Create ([SWS_EM_02562]) of de reguliere constructor ([SWS_EM_02560]) als het doorgegeven terminationHandler-object geen aanroepbare functie bevat. Het systeem past rollback-semantiek toe; voor herstel moet een geldig callable worden doorgegeven.
• ara::exec::ExecErrc::kNoCommunication: kan zowel bij het aanmaken ([SWS_EM_02562], [SWS_EM_02560]) als bij ReportExecutionState ([SWS_EM_02003]) optreden wanneer er sprake is van een communicatiefout tussen het applicatieproces en Execution Management (bijv. geen bevestiging van de ontvangst van de melding). Hierbij geldt geen rollback-semantiek; als herstelmaatregel is een nieuwe aanroeppoging voorzien.
• ara::exec::ExecErrc::kInvalidTransition: Wordt geretourneerd door ReportExecutionState ([SWS_EM_02003]) als er een niet-toegestane toestandswijziging wordt aangevraagd, bijvoorbeeld het opnieuw melden van een reeds actieve toestand zoals kRunning. Aangezien de toestand al is gemeld, is er geen nieuwe verzending vereist (rollback-semantiek).