classe ara::exec::ExecutionClient

La classe ara::exec::ExecutionClient permet aux processus applicatifs de signaler de manière contraignante leur état d'exécution interne à l'Execution Management ([SWS_EM_02003]). Lors de l'initialisation, elle prend en charge en outre l'interception du signal SIGTERM et relaie celui-ci à un gestionnaire d'arrêt défini par l'utilisateur dans un thread d'arrière-plan ([SWS_EM_02562]). En tant qu'objet déplaçable uniquement (move-only), l'instance lie strictement le traitement du signal à son cycle de vie et rétablit l'état de signal antérieur lors de sa destruction. Les appelants doivent s'assurer que le callback enregistré reste invocable pendant toute la durée de vie de l'instance.

plus ›

Contexte

La classe ara::exec::ExecutionClient permet aux processus sur l'Adaptive Platform de signaler leur état d'exécution interne à l'Execution Management ([SWS_EM_02003]). Elle sert d'interface standardisée entre l'application en cours d'exécution et la gestion centrale des processus. En plus du relayage des transitions d'état, l'instance assume la responsabilité du traitement du signal du système d'exploitation SIGTERM ([SWS_EM_02562], [SWS_EM_02002]). Dès l'arrivée du signal, elle exécute un callback défini par l'utilisateur dans un thread d'arrière-plan distinct afin de permettre à l'application une terminaison ordonnée ([SWS_EM_02562]). Interprétation : le système d'exploitation ou l'Execution Management devrait transmettre le signal SIGTERM au processus lorsqu'un arrêt de l'unité d'exécution est demandé. Question Q-51eee947d01ae8b4 (ouverte)

Diagramme de contexte : interaction entre le processus applicatif, ExecutionClient, l'Execution Management et le mécanisme de signal. Sources : [SWS_EM_02003], [SWS_EM_02562], [SWS_EM_02002].

Cycle de vie

L'instanciation de ara::exec::ExecutionClient s'effectue au choix via la méthode fabrique statique Create ([SWS_EM_02562]) ou le constructeur standard ([SWS_EM_02560]). Alors que Create est sûre vis-à-vis des exceptions (noexcept) et renvoie le résultat encapsulé dans un ara::core::Result ([SWS_EM_02562]), le constructeur standard est déclaré comme noexcept(false) ([SWS_EM_02560]). Les deux voies de création attendent en paramètre un callback std::function<void()> invocable (terminationHandler). Ce callback doit rester valide et invocable pendant toute la durée de vie de l'instance ExecutionClient ([SWS_EM_02562], [SWS_EM_02560]).

En ce qui concerne les relations de propriété, la classe est conçue comme étant déplaçable uniquement (move-only) : le constructeur de copie ([SWS_EM_02563]) ainsi que l'opérateur d'assignation par copie ([SWS_EM_02564]) sont explicitement supprimés (delete). Un transfert d'instances est exclusivement possible via le constructeur de déplacement ([SWS_EM_02580]) et l'opérateur d'assignation par déplacement ([SWS_EM_02581]), qui sont tous deux sûrs vis-à-vis des exceptions (noexcept), mais non thread-safe. La méthode fabrique Create et le constructeur lui-même sont considérés comme thread-safe ([SWS_EM_02562], [SWS_EM_02560]).

Le destructeur ~ExecutionClient() est défini comme noexcept ([SWS_EM_02002]) et n'est pas thread-safe. Lors de la destruction de l'instance, la responsabilité du signal SIGTERM est à nouveau cédée : le destructeur réinitialise le gestionnaire de signal pour SIGTERM à l'état initial qui était actif avant l'instanciation ([SWS_EM_02002]).

Parcours d'utilisation

Le déroulement standard se divise en initialisation, transmission d'état et terminaison ordonnée :

• Création : au début de l'exécution du processus, l'instance est initialisée via Create, le gestionnaire d'arrêt étant transmis ([SWS_EM_02562]). Typiquement, ce gestionnaire définit un drapeau ou signale des primitives de synchronisation pour débloquer les threads en cours d'exécution.
• Notification d'état : dès que le processus est prêt, il signale son état d'exécution à l'Execution Management via ReportExecutionState ([SWS_EM_02003]). L'appel est thread-safe et peut être effectué depuis différents threads de travail.
• Réception du signal et terminaison : si un signal SIGTERM arrive pendant la durée d'exécution, ExecutionClient active le terminationHandler enregistré de manière asynchrone dans un thread d'arrière-plan ([SWS_EM_02562]). Le processus termine les tâches ouvertes de manière ordonnée.
• Destruction : lors de la sortie de la portée de validité, le destructeur rétablit la configuration de signal d'origine ([SWS_EM_02002]).

Diagramme de séquence : déroulement de la création jusqu'à la terminaison commandée par signal, en passant par la notification d'état. Sources : [SWS_EM_02562], [SWS_EM_02003], [SWS_EM_02002].

Scénarios d'erreur

Lors de l'utilisation de ExecutionClient, différentes situations d'erreur sont couvertes par des codes d'erreur issus de ara::exec::ExecErrc :

• ara::exec::ExecErrc::kInvalidArgument : survient lors de l'instanciation via Create ([SWS_EM_02562]) ou le constructeur standard ([SWS_EM_02560]) si l'objet terminationHandler transmis ne contient aucune fonction invocable. Le système applique une sémantique de rollback ; pour y remédier, un callable valide doit être transmis.
• ara::exec::ExecErrc::kNoCommunication : peut survenir aussi bien lors de la création ([SWS_EM_02562], [SWS_EM_02560]) que lors de ReportExecutionState ([SWS_EM_02003]) en présence d'une erreur de communication entre le processus applicatif et l'Execution Management (par ex. aucune confirmation de réception de la notification). Aucune sémantique de rollback ne s'applique ici ; une nouvelle tentative d'appel est prévue comme mesure de récupération.
• ara::exec::ExecErrc::kInvalidTransition : est renvoyé par ReportExecutionState ([SWS_EM_02003]) si un changement d'état non autorisé est demandé, par exemple une nouvelle notification d'un état déjà actif tel que kRunning. Étant donné que l'état a déjà été signalé, aucune nouvelle transmission n'est requise (sémantique de rollback).