classe ara::exec::StateClient

L'interface ara::exec::StateClient permet au State Management de demander des changements d'état pour des groupes de fonctions auprès de l'Execution Management, afin de piloter l'exécution de processus assignés sur une Machine [SWS_EM_02278]. Lors de la création via Create(), un callback continuellement valide doit être enregistré pour les états indéfinis inattendus [SWS_EM_02276]. Outre des transitions d'état asynchrones, cette classe non copiable fournit des méthodes d'interrogation du résultat du démarrage de la Machine ainsi que d'analyse d'erreur lors d'erreurs d'exécution [SWS_EM_02279], [SWS_EM_02542].

plus ›

Contexte

La classe ara::exec::StateClient constitue l'interface de l'Execution Management par laquelle le State Management demande et pilote les transitions d'état pour des groupes de fonctions (Function Groups). Le State Management utilise ce client pendant toute la durée de fonctionnement d'une Machine afin de démarrer ou d'arrêter des processus de manière ciblée. L'intégrateur affecte des composants logiciels à certains états d'un groupe de fonctions. Si le State Management souhaite exécuter ces logiciels, il demande via le StateClient auprès de l'Execution Management le passage à l'état de groupe de fonctions concerné ; l'arrêt s'effectue de manière analogue par une transition vers un état dans lequel le logiciel ne doit pas être actif [SWS_EM_02278].

Diagramme de contexte : interaction entre State Management, StateClient et Execution Management. Sources : [SWS_EM_02276], [SWS_EM_02278]

Cycle de vie

Les instances de StateClient peuvent être créées soit via le constructeur nommé Create() [SWS_EM_02276] sous la forme d'un ara::core::Result<StateClient>, soit via le constructeur régulier StateClient() [SWS_EM_02561]. Ces deux voies de construction exigent impérativement un paramètre de callback undefinedStateCallback de type std::function<void(const ara::exec::ExecutionErrorEvent&)>. Ce callback est déclenché par la bibliothèque StateClient lorsqu'un groupe de fonctions passe de manière inattendue et sans demande préalable par SetState() dans un état indéfini. L'appelant doit s'assurer que ce callback reste appelable pendant toute la durée de vie de l'instance StateClient, ce qui est particulièrement pertinent lors de liaisons d'objets via std::bind [SWS_EM_02276], [SWS_EM_02561].

Les opérations de copie sont explicitement interdites pour StateClient : le constructeur de copie [SWS_EM_02565] ainsi que l'opérateur d'affectation par copie [SWS_EM_02568] sont tous deux supprimés (=delete). Un transfert de propriété est exclusivement possible par sémantique de déplacement via le constructeur de déplacement [SWS_EM_02566] et l'affectation par déplacement [SWS_EM_02567]. En matière de concurrence, les méthodes fonctionnelles telles que SetState(), GetExecutionError() et GetInitialMachineStateTransitionResult() ainsi que la création sont conçues pour être thread-safe [SWS_EM_02276], [SWS_EM_02278], [SWS_EM_02279], [SWS_EM_02542]. En revanche, les opérations de déplacement et le destructeur ~StateClient() ne sont pas thread-safe [SWS_EM_02277], [SWS_EM_02566], [SWS_EM_02567].

Parcours d'utilisation

Un cycle d'utilisation typique se divise en initialisation, interrogation du résultat de démarrage, changements d'état réguliers et surveillance des erreurs :

1. Création : le State Management instancie StateClient en spécifiant un callback de signalement d'erreurs valide via Create() [SWS_EM_02276].
2. Interroger le résultat initial du démarrage : avec GetInitialMachineStateTransitionResult(), le State Management demande le résultat de la transition d'état initiale vers l'état de startup [SWS_EM_02279]. Cette transition ayant lieu exactement une fois par cycle de vie de la Machine, le ara::core::Future<void> renvoyé reste stable et ne change plus jusqu'à un redémarrage.
3. Demander un changement d'état : au moyen de SetState(), State Management ordonne des transitions d'état asynchrones pour des groupes de fonctions individuels [SWS_EM_02278]. La méthode retourne immédiatement et fournit un ara::core::Future<void> pour interroger l'achèvement. Dès que la demande est parvenue à Execution Management, elle est exécutée indépendamment de la durée de vie ultérieure de l'instance appelante.
4. Analyser les états d'erreur : si un groupe de fonctions passe de manière inattendue dans un état indéfini, l'erreur d'exécution déclenchante peut être déterminée sous la forme d'un ara::exec::ExecutionErrorEvent via GetExecutionError() [SWS_EM_02542].

Diagramme de séquence : déroulement de la création, de l'interrogation de l'état initial, du changement d'état asynchrone et de l'analyse des erreurs. Sources : [SWS_EM_02276], [SWS_EM_02279], [SWS_EM_02278], [SWS_EM_02542]

Scénarios d'erreur

Les opérations de la classe communiquent les échecs via des codes d'erreur de ExecErrorDomain :

• ExecErrc::kNoCommunication : signale des perturbations de communication avec Execution Management, par exemple en cas de connexion IPC interrompue. Se produit lors de Create() [SWS_EM_02276], SetState() [SWS_EM_02278], GetInitialMachineStateTransitionResult() [SWS_EM_02279] ainsi que GetExecutionError() [SWS_EM_02542]. La récupération prévue consiste en un nouvel appel.
• ExecErrc::kInvalidArgument : est signalé par Create() et StateClient() si le callback transmis ne contient aucune fonction appelable [SWS_EM_02276], [SWS_EM_02561].
• ExecErrc::kOperationCanceled : indique pour SetState() qu'une transition en cours a été interrompue par une demande plus récente [SWS_EM_02278]. Pour GetInitialMachineStateTransitionResult(), cette erreur survient lorsque la transition de démarrage initiale a été interrompue, par exemple par une séquence de Machine-Update interrompue [SWS_EM_02279].
• ExecErrc::kInvalidTransition : la transition d'état demandée n'est pas autorisée, par exemple la transition vers l'état Off pour MachineFG, ou bien l'état n'existe plus après une mise à jour [SWS_EM_02278].
• ExecErrc::kInvalidMetaModelIdentifier : l'état transmis n'existe pas dans le manifeste traité ou le processus ne possède pas de mappage vers le groupe de fonctions concerné [SWS_EM_02278], [SWS_EM_02542]. Si cette erreur survient lors de GetInitialMachineStateTransitionResult(), il manque au processus le mappage vers MachineFG, ce qui indique un problème de configuration [SWS_EM_02279].
• ExecErrc::kOperationFailed : la transition a échoué [SWS_EM_02278]. Pour GetExecutionError(), le code indique que le groupe de fonctions ne se trouve pas dans un état indéfini et que le problème a probablement déjà été résolu [SWS_EM_02542].
• ExecErrc::kIntegrityOrAuthenticityCheckFailed et ExecErrc::kUnexpectedTermination : échecs spécifiques pendant SetState() à la suite de contrôles d'intégrité ayant échoué ou de terminaisons inattendues de processus pendant la transition [SWS_EM_02278].