class ara::exec::StateClient

The interface ara::exec::StateClient enables State Management to request state transitions for function groups from Execution Management in order to control the execution of assigned processes on a Machine [SWS_EM_02278]. During creation via Create(), a continuously valid callback for unexpected undefined states must be registered [SWS_EM_02276]. In addition to asynchronous state transitions, the non-copyable class provides methods for querying the Machine startup result as well as for error analysis in the event of execution errors [SWS_EM_02279], [SWS_EM_02542].

more ›

Context

The class ara::exec::StateClient forms the interface of Execution Management through which State Management requests and controls state transitions for function groups (Function Groups). State Management uses this client throughout the operational lifetime of a Machine to start or stop processes in a targeted manner. The integrator assigns software components to specific states of a function group. If State Management wishes to execute this software, it requests the transition into the relevant function group state from Execution Management via the StateClient; stopping is performed analogously by transitioning into a state in which the software should not be active [SWS_EM_02278].

Context diagram: Interaction between State Management, StateClient, and Execution Management. Sources: [SWS_EM_02276], [SWS_EM_02278]

Lifecycle

Instances of StateClient can be created either via the named constructor Create() [SWS_EM_02276] as a ara::core::Result<StateClient> or via the regular constructor StateClient() [SWS_EM_02561]. Both construction paths strictly require a callback parameter undefinedStateCallback of type std::function<void(const ara::exec::ExecutionErrorEvent&)>. This callback is triggered by the StateClient library if a function group unexpectedly transitions into an undefined state without a prior request by SetState(). The caller must ensure that this callback remains callable throughout the entire lifetime of the StateClient instance, which is particularly relevant for object bindings via std::bind [SWS_EM_02276], [SWS_EM_02561].

Copy operations are explicitly prohibited for StateClient: both the copy constructor [SWS_EM_02565] and the copy assignment operator [SWS_EM_02568] are deleted (=delete). A transfer of ownership is possible exclusively via move semantics via move constructor [SWS_EM_02566] and move assignment [SWS_EM_02567]. With regard to concurrency, the business methods such as SetState(), GetExecutionError(), and GetInitialMachineStateTransitionResult() as well as creation are designed to be thread-safe [SWS_EM_02276], [SWS_EM_02278], [SWS_EM_02279], [SWS_EM_02542]. In contrast, the move operations and the destructor ~StateClient() are not thread-safe [SWS_EM_02277], [SWS_EM_02566], [SWS_EM_02567].

Usage Path

A typical application cycle is structured into initialization, querying the startup result, regular state transitions, and error monitoring:

1. Creation: State Management instantiates StateClient, specifying a valid error-signaling callback via Create() [SWS_EM_02276].
2. Query initial startup result: Using GetInitialMachineStateTransitionResult(), State Management requests the result of the initial state transition into the Startup state [SWS_EM_02279]. Because this transition occurs exactly once per lifecycle of the Machine, the returned ara::core::Future<void> remains stable and does not change until a restart.
3. Request state transition: Using SetState(), State Management requests asynchronous state transitions for individual function groups [SWS_EM_02278]. The method returns immediately and provides a ara::core::Future<void> to query completion. As soon as the request has been received by Execution Management, it is executed independently of the remaining lifetime of the calling instance.
4. Investigate error states: If a function group unexpectedly enters an undefined state, the triggering execution error can be determined via GetExecutionError() in the form of an ara::exec::ExecutionErrorEvent [SWS_EM_02542].

Sequence diagram: Flow of creation, initial state query, asynchronous state transition, and error analysis. Sources: [SWS_EM_02276], [SWS_EM_02279], [SWS_EM_02278], [SWS_EM_02542]

Error Scenarios

The operations of the class communicate failures via error codes of the ExecErrorDomain:

• ExecErrc::kNoCommunication: Signals communication disruptions to Execution Management, for example in the event of an interrupted IPC connection. Occurs with Create() [SWS_EM_02276], SetState() [SWS_EM_02278], GetInitialMachineStateTransitionResult() [SWS_EM_02279], and GetExecutionError() [SWS_EM_02542]. The intended recovery consists of calling again.
• ExecErrc::kInvalidArgument: Is reported by Create() and StateClient() if the passed callback does not contain a callable function [SWS_EM_02276], [SWS_EM_02561].
• ExecErrc::kOperationCanceled: Indicates at SetState() that an ongoing transition was cancelled by a newer request [SWS_EM_02278]. At GetInitialMachineStateTransitionResult(), this error occurs if the initial startup transition was cancelled, such as due to an interrupted machine update sequence [SWS_EM_02279].
• ExecErrc::kInvalidTransition: The requested state transition is invalid, for example the transition to the Off state for MachineFG, or the state no longer exists after an update [SWS_EM_02278].
• ExecErrc::kInvalidMetaModelIdentifier: The passed state does not exist in the processed manifest or the process has no mapping to the function group in question [SWS_EM_02278], [SWS_EM_02542]. If this error occurs at GetInitialMachineStateTransitionResult(), the process lacks the mapping to MachineFG, which indicates a configuration problem [SWS_EM_02279].
• ExecErrc::kOperationFailed: The transition has failed [SWS_EM_02278]. At GetExecutionError(), the code indicates that the function group is not in an undefined state and the problem has presumably already been resolved [SWS_EM_02542].
• ExecErrc::kIntegrityOrAuthenticityCheckFailed and ExecErrc::kUnexpectedTermination: Specific failures during SetState() as a result of failed integrity checks or unexpected process terminations during the transition [SWS_EM_02278].