ara::exec

Overview

The Execution Management Functional Cluster controls process lifecycle and Function Group state transitions. This page specifies the public API of the ara::exec namespace — execution state reporting, Function Group state control, and the associated error domain — organized by header file.

Library · Headers · Linking

• Library: lib/libpara_exec.so
• CMake: find_package(para-exec) → para::exec
• Standard headers: include/ara/exec/
• Runtime daemon: bin/EM

1 Header: ara/exec/exec_error_domain.h

1.1 Non-Member Types

1.1.1 Enumeration: ExecErrc

Kind:	enumeration
Header file:	#include "ara/exec/exec_error_domain.h"
Forwarding header file:	#include "ara/exec/exec_fwd.h"
Scope:	namespace ara::exec
Symbol:	ExecErrc
Underlying type:	ara::core::ErrorDomain::CodeType
Syntax:	enum class ExecErrc : ara::core::ErrorDomain::CodeType {...};
Values:	kNoCommunication	= 3
		Communication error occurred, e.g. request cannot be send or result cannot be retrieved
	kInvalidMetaModelIdentifier	= 4
		Wrong meta model identifier passed to a function
	kOperationCanceled	= 5
		Transition to the requested Function Group state was canceled by a newer request
	kOperationFailed	= 6
		Requested operation could not be performed, e.g. Function Group state transition cannot be finished because kRunning was not reported on time
	kInvalidTransition	= 9
		Invalid transition (e.g. Process attempted to report kRunning, when it was already in a Running Process State)
	kIntegrityOrAuthenticityCheckFailed	= 14
		Integrity or authenticity check for a Process to be spawned in the requested Function Group state failed
	kUnexpectedTermination	= 15
		Abnormal Termination during a Function Group State transition occurred
	kInvalidArgument	= 16
		Passed argument doesn't appear to be valid.
Description:	Defines an enumeration class for the Execution Management error codes.
Notes:	If a ara::exec::ExecErrc::kNoCommunication occurs at Execution Management or State Management level (or communication between both), the system may need to enter an Unrecoverable State. The internal mechanisms can detect this issue in the moment that a communication attempt occurs. This is not the case for applications that are using the interface of the ara::exec::ExecutionClient or ara::exec::StateClient - they eventually get a communication error in the moment of the API use, i.e. possibly after the actual error occurrence. However, this is not problematic as the recovery options are limited from a client side viewpoint.

1.2 Non-Member Functions

1.2.1 Other

1.2.1.1 GetExecErrorDomain

Kind:	function
Header file:	#include "ara/exec/exec_error_domain.h"
Scope:	namespace ara::exec
Syntax:	const ara::core::ErrorDomain & GetExecErrorDomain () noexcept;
Return value:	const ara::core::ErrorDomain &	Return a reference to the global ExecErrorDomain object.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	Returns a reference to the global ExecErrorDomain object.

1.2.1.2 MakeErrorCode

Kind:	function
Header file:	#include "ara/exec/exec_error_domain.h"
Scope:	namespace ara::exec
Syntax:	ara::core::ErrorCode MakeErrorCode (ara::exec::ExecErrc code, ara::core::ErrorDomain::SupportDataType data) noexcept;
Parameters (in):	code	Error code number.
	data	Vendor defined data associated with the error.
Return value:	ara::core::ErrorCode	An ErrorCode object.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	Creates an instance of ErrorCode.

1.3 Class: ExecErrorDomain

Kind:	class
Header file:	#include "ara/exec/exec_error_domain.h"
Forwarding header file:	#include "ara/exec/exec_fwd.h"
Scope:	namespace ara::exec
Symbol:	ExecErrorDomain
Base class:	ara::core::ErrorDomain
Syntax:	class ExecErrorDomain final : public ara::core::ErrorDomain {...};
Description:	Defines a class representing the Execution Management error domain.

1.3.1 Public Member Functions

1.3.1.1 Special Member Functions

1.3.1.1.1 Default Constructor

Kind:	function
Header file:	#include "ara/exec/exec_error_domain.h"
Scope:	ara::exec::ExecErrorDomain
Syntax:	ExecErrorDomain () noexcept;
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	Constructs a new ExecErrorDomain object.

1.3.1.2 Member Functions

1.3.1.2.1 Message

Kind:	function
Header file:	#include "ara/exec/exec_error_domain.h"
Scope:	ara::exec::ExecErrorDomain
Syntax:	const char * Message (CodeType errorCode) const noexcept override;
Parameters (in):	errorCode	The error code number.
Return value:	const char *	The message associated with the error code.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	Returns the message associated with errorCode.

1.3.1.2.2 Name

Kind:	function
Header file:	#include "ara/exec/exec_error_domain.h"
Scope:	ara::exec::ExecErrorDomain
Syntax:	const char * Name () const noexcept override;
Return value:	const char *	As per ara::exec::ExecErrorDomain in
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	Returns a string constant associated with ExecErrorDomain.

1.3.1.2.3 ThrowAsException

Kind:	function
Header file:	#include "ara/exec/exec_error_domain.h"
Scope:	ara::exec::ExecErrorDomain
Syntax:	void ThrowAsException (const ara::core::ErrorCode &errorCode) const noexcept(false) override;
Parameters (in):	errorCode	The error to throw.
Return value:	None
Exception Safety:	not exception safe
Thread Safety:	thread-safe
Description:	Creates a new instance of ExecException from errorCode and throws it as a C++ exception. As per , this function does not participate in overload resolution when C++ exceptions are disabled in the compiler toolchain.

1.4 Class: ExecException

Kind:	class
Header file:	#include "ara/exec/exec_error_domain.h"
Forwarding header file:	#include "ara/exec/exec_fwd.h"
Scope:	namespace ara::exec
Symbol:	ExecException
Base class:	ara::core::Exception
Syntax:	class ExecException final : public ara::core::Exception {...};
Description:	Defines a class for exceptions to be thrown by the Execution Management.

1.4.1 Public Member Functions

1.4.1.1 Constructors

1.4.1.1.1 ExecException

Kind:	function
Header file:	#include "ara/exec/exec_error_domain.h"
Scope:	ara::exec::ExecException
Syntax:	explicit ExecException (ara::core::ErrorCode errorCode) noexcept;
Parameters (in):	errorCode	The error code.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	Constructs a new ExecException object containing an error code.

2 Header: ara/exec/execution_client.h

2.1 Non-Member Types

2.1.1 Enumeration: ExecutionState

Kind:	enumeration
Header file:	#include "ara/exec/execution_client.h"
Forwarding header file:	#include "ara/exec/exec_fwd.h"
Scope:	namespace ara::exec
Symbol:	ExecutionState
Underlying type:	std::uint32_t
Syntax:	enum class ExecutionState : std::uint32_t {...};
Values:	kRunning	= 0
		After a Process has been started by Execution Management, it reports ExecutionState kRunning.
Description:	Defines the internal states of a Process. Scoped enumeration of uint32_t. Please note that ara::exec::ExecutionState includes only states reportable by the Process to Execution Management and therefore does not include enumerations e.g. the "Initializing" state mentioned in Figure 7.2 and Figure 7.12, which are an implied states for Execution Management. The Initializing state starts when Process is first scheduled (so no code executed yet) and ends when ara::exec::ExecutionState::kRunning is reported (). The Terminating state starts when termination is requested by Execution Management and ends when the Process terminates (). For the reasons mentioned, Execution Management assumes that Process is in initializing state until ara::exec::ExecutionState::kRunning will be reported by it.

2.2 Class: ExecutionClient

Kind:	class
Header file:	#include "ara/exec/execution_client.h"
Forwarding header file:	#include "ara/exec/exec_fwd.h"
Scope:	namespace ara::exec
Symbol:	ExecutionClient
Syntax:	class ExecutionClient final {...};
Description:	The ara::exec::ExecutionClient API provides the functionality for a Process to report its Execution State to the Execution Management.
Notes:	To eventually implement the Named Constructor Idiom, the developer may either make the default constructor private or delete it and define a non-default constructor.

2.2.1 Public Member Functions

2.2.1.1 Special Member Functions

2.2.1.1.1 Move Constructor

Kind:	function
Header file:	#include "ara/exec/execution_client.h"
Scope:	ara::exec::ExecutionClient
Syntax:	ExecutionClient (ExecutionClient &&rval) noexcept;
Parameters (in):	rval	reference to move
Exception Safety:	exception safe
Thread Safety:	not thread-safe
Description:	Intentional use of move constructor for ExecutionClient.

2.2.1.1.2 Copy Constructor

Kind:	function
Header file:	#include "ara/exec/execution_client.h"
Scope:	ara::exec::ExecutionClient
Syntax:	ExecutionClient (const ExecutionClient &)=delete;
Description:	Suppress default copy construction for ExecutionClient.

2.2.1.1.3 Copy Assignment Operator

Kind:	function
Header file:	#include "ara/exec/execution_client.h"
Scope:	ara::exec::ExecutionClient
Syntax:	ara::exec::ExecutionClient & operator= (const ara::exec::ExecutionClient &)=delete;
Description:	Suppress default copy assignment for ExecutionClient.

2.2.1.1.4 Move Assignment Operator

Kind:	function
Header file:	#include "ara/exec/execution_client.h"
Scope:	ara::exec::ExecutionClient
Syntax:	ara::exec::ExecutionClient & operator= (ara::exec::ExecutionClient &&rval) noexcept;
Parameters (in):	rval	reference to move
Return value:	ExecutionClient &	the new reference
Exception Safety:	exception safe
Thread Safety:	not thread-safe
Description:	Intentional use of move assignment for ExecutionClient.

2.2.1.1.5 Destructor

Kind:	function
Header file:	#include "ara/exec/execution_client.h"
Scope:	ara::exec::ExecutionClient
Syntax:	~ExecutionClient() noexcept;
Exception Safety:	exception safe
Thread Safety:	not thread-safe
Description:	noexcept destructor
Notes:	Since ExecutionClient overtake the responsibility for handling SIGTERM signal, it should reset SIGTERM handler back to its original value, when destructor is called.

2.2.1.2 Constructors

2.2.1.2.1 ExecutionClient

Kind:	function
Header file:	#include "ara/exec/execution_client.h"
Scope:	ara::exec::ExecutionClient
Syntax:	ExecutionClient (std::function< void()> terminationHandler) noexcept(false);
Parameters (in):	terminationHandler	Callback which is called if ExecutionClient receives SIGTERM signal. The callback is executed in a background thread. A typical implementation of this callback will set a global flag (and potentially unblock other threads) to perform a graceful termination. Lifetime: it is expected that terminationHandler remains callable, during entire lifetime of the ExecutionClient instance. This is especially important if, terminationHandler is bound to an instance of a class (e.g. using std::bind).
Exception Safety:	not exception safe
Thread Safety:	thread-safe
Errors:	ara::exec::ExecErrc::kNoCommunication	no_rollback_semantics
		Communication error occurred. Recovery: try again
	ara::exec::ExecErrc::kInvalidArgument	rollback_semantics
		Given terminationHandler doesn't contain a callable function. Recovery: change argument
Description:	Regular constructor for ExecutionClient.

2.2.1.3 Member Functions

2.2.1.3.1 Create

Kind:	function
Header file:	#include "ara/exec/execution_client.h"
Scope:	ara::exec::ExecutionClient
Syntax:	static ara::core::Result< ara::exec::ExecutionClient > Create (std::function< void()> terminationHandler) noexcept;
Parameters (in):	terminationHandler	Callback which is called if ExecutionClient receives SIGTERM signal. The callback is executed in a background thread. A typical implementation of this callback will set a global flag (and potentially unblock other threads) to perform a graceful termination. Lifetime: it is expected that terminationHandler remains callable, during entire lifetime of the ExecutionClient instance. This is especially important if, terminationHandler is bound to an instance of a class (e.g. using std::bind).
Return value:	ara::core::Result< ExecutionClient >	a result that contains either a ExecutionClient object or an error.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Errors:	ara::exec::ExecErrc::kNoCommunication	no_rollback_semantics
		Communication error occurred. Recovery: try again
	ara::exec::ExecErrc::kInvalidArgument	rollback_semantics
		Given terminationHandler doesn't contain a callable function. Recovery: change argument
Description:	Named constructor for ExecutionClient.
Notes:	This named constructor may call a constructor defined by the developer.

2.2.1.3.2 ReportExecutionState

Kind:	function
Header file:	#include "ara/exec/execution_client.h"
Scope:	ara::exec::ExecutionClient
Syntax:	ara::core::Result< void > ReportExecutionState (ara::exec::ExecutionState state) noexcept;
Parameters (in):	state	Value representing the current Process state, that should be reported.
Return value:	ara::core::Result< void >	An instance of ara::core::Result. The instance holds an ErrorCode containing either one of the specified errors or a void-value.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Errors:	ara::exec::ExecErrc::kNoCommunication	no_rollback_semantics
		Communication error between Application and Execution Management, e.g. unable to get confirmation that report was received. Recovery: try again
	ara::exec::ExecErrc::kInvalidTransition	rollback_semantics
		Invalid transition request (e.g. to Running when already in Running state). Recovery: Already reported kRunning, no need to do it again
Description:	Interface for a Process to report its internal state to Execution Management.

3 Header: ara/exec/execution_error_event.h

3.1 Non-Member Types

3.1.1 Type Alias: ExecutionError

Kind:	type alias
Header file:	#include "ara/exec/execution_error_event.h"
Scope:	namespace ara::exec
Symbol:	ExecutionError
Syntax:	using ExecutionError = std::uint32_t;
Description:	Represents the execution error.

3.2 Struct: ExecutionErrorEvent

Kind:	struct
Header file:	#include "ara/exec/execution_error_event.h"
Forwarding header file:	#include "ara/exec/exec_fwd.h"
Scope:	namespace ara::exec
Symbol:	ExecutionErrorEvent
Syntax:	struct ExecutionErrorEvent final {...};
Description:	Represents an execution error event which happens in a Function Group.

3.2.1 Public Member Variables

3.2.1.1 executionError

Kind:	variable
Header file:	#include "ara/exec/execution_error_event.h"
Scope:	ara::exec::ExecutionErrorEvent
Symbol:	executionError
Type:	ExecutionError
Syntax:	ExecutionError executionError;
Description:	The execution error of the Process which unexpectedly terminated .

3.2.1.2 functionGroup

Kind:	variable
Header file:	#include "ara/exec/execution_error_event.h"
Scope:	ara::exec::ExecutionErrorEvent
Symbol:	functionGroup
Type:	FunctionGroup
Syntax:	FunctionGroup functionGroup;
Description:	The function group in which the error occurred .

4 Header: ara/exec/function_group.h

4.1 Class: FunctionGroup

Kind:	class
Header file:	#include "ara/exec/function_group.h"
Forwarding header file:	#include "ara/exec/exec_fwd.h"
Scope:	namespace ara::exec
Symbol:	FunctionGroup
Syntax:	class FunctionGroup final {...};
Description:	Class representing Function Group defined in meta-model (ARXML). An instance of this class will represent Function Group defined inside meta-model (ARXML). This class is intended to be an implementation specific representation, of information inside meta-model. Once created based on ARXML path, its internal value stays bounded to it for entire lifetime of a object.

4.1.1 Public Member Functions

4.1.1.1 Special Member Functions

4.1.1.1.1 Copy Constructor

Kind:	function
Header file:	#include "ara/exec/function_group.h"
Scope:	ara::exec::FunctionGroup
Syntax:	FunctionGroup (const FunctionGroup &other)=delete;
Description:	Copy constructor.
Notes:	To prevent problems with resource allocations during copy operation, this class is non-copyable.

4.1.1.1.2 Move Constructor

Kind:	function
Header file:	#include "ara/exec/function_group.h"
Scope:	ara::exec::FunctionGroup
Syntax:	FunctionGroup (FunctionGroup &&other) noexcept;
Parameters (in):	other	FunctionGroup instance to move to a newly constructed object.
Exception Safety:	exception safe
Thread Safety:	not thread-safe
Description:	Move constructor.

4.1.1.1.3 Default Constructor

Kind:	function
Header file:	#include "ara/exec/function_group.h"
Scope:	ara::exec::FunctionGroup
Syntax:	FunctionGroup ()=delete;
Description:	Default constructor.
Notes:	Default constructor is deleted in favour of regular constructor.

4.1.1.1.4 Copy Assignment Operator

Kind:	function
Header file:	#include "ara/exec/function_group.h"
Scope:	ara::exec::FunctionGroup
Syntax:	ara::exec::FunctionGroup & operator= (const ara::exec::FunctionGroup &other)=delete;
Description:	Copy assignment operator.
Notes:	To prevent problems with resource allocations during copy operation, this class is non-copyable.

4.1.1.1.5 Move Assignment Operator

Kind:	function
Header file:	#include "ara/exec/function_group.h"
Scope:	ara::exec::FunctionGroup
Syntax:	ara::exec::FunctionGroup & operator= (ara::exec::FunctionGroup &&other) noexcept;
Parameters (in):	other	FunctionGroup instance to move to this object.
Return value:	FunctionGroup &	reference to the object on which the move assignment operator was invoked
Exception Safety:	exception safe
Thread Safety:	not thread-safe
Description:	Move assignment operator.

4.1.1.1.6 Destructor

Kind:	function
Header file:	#include "ara/exec/function_group.h"
Scope:	ara::exec::FunctionGroup
Syntax:	~FunctionGroup() noexcept;
Exception Safety:	exception safe
Thread Safety:	not thread-safe
Description:	Destructor of the FunctionGroup instance.

4.1.1.2 Constructors

4.1.1.2.1 FunctionGroup

Kind:	function
Header file:	#include "ara/exec/function_group.h"
Scope:	ara::exec::FunctionGroup
Syntax:	FunctionGroup (const ara::core::InstanceSpecifier &instance) noexcept;
Parameters (in):	instance	instance specifier to the RPortPrototype of a StateClientInterface.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	Creates an instance of FunctionGroup.

4.1.1.3 Member Functions

4.1.1.3.1 operator!=

Kind:	function
Header file:	#include "ara/exec/function_group.h"
Scope:	ara::exec::FunctionGroup
Syntax:	bool operator!= (const ara::exec::FunctionGroup &other) const noexcept;
Parameters (in):	other	FunctionGroup instance to compare this one with.
Return value:	bool	false in case both FunctionGroups are representing exactly the same meta-model element, true otherwise.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	uneq operator to compare with other FunctionGroup instance.

4.1.1.3.2 operator==

Kind:	function
Header file:	#include "ara/exec/function_group.h"
Scope:	ara::exec::FunctionGroup
Syntax:	bool operator== (const ara::exec::FunctionGroup &other) const noexcept;
Parameters (in):	other	FunctionGroup instance to compare this one with.
Return value:	bool	true in case both FunctionGroups are representing exactly the same meta-model element, false otherwise.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	eq operator to compare with other FunctionGroup instance.

5 Header: ara/exec/function_group_state.h

5.1 Class: FunctionGroupState

Kind:	class
Header file:	#include "ara/exec/function_group_state.h"
Forwarding header file:	#include "ara/exec/exec_fwd.h"
Scope:	namespace ara::exec
Symbol:	FunctionGroupState
Syntax:	class FunctionGroupState final {...};
Description:	Class representing Function Group State defined in meta-model (ARXML). An instance of this class will represent Function Group State defined inside meta-model (ARXML). This class is intended to be an implementation specific representation, of information inside meta-model. Once created based on ARXML path, its internal value stays bounded to it for entire lifetime of a object.

5.1.1 Public Member Functions

5.1.1.1 Special Member Functions

5.1.1.1.1 Move Constructor

Kind:	function
Header file:	#include "ara/exec/function_group_state.h"
Scope:	ara::exec::FunctionGroupState
Syntax:	FunctionGroupState (FunctionGroupState &&other) noexcept;
Parameters (in):	other	FunctionGroupState instance to be moved to a newly constructed object.
Exception Safety:	exception safe
Thread Safety:	not thread-safe
Description:	Move constructor.

5.1.1.1.2 Copy Constructor

Kind:	function
Header file:	#include "ara/exec/function_group_state.h"
Scope:	ara::exec::FunctionGroupState
Syntax:	FunctionGroupState (const FunctionGroupState &other) noexcept;
Parameters (in):	other	FunctionGroupState instance to be copied
Exception Safety:	exception safe
Thread Safety:	not thread-safe
Description:	Copy constructor.

5.1.1.1.3 Copy Assignment Operator

Kind:	function
Header file:	#include "ara/exec/function_group_state.h"
Scope:	ara::exec::FunctionGroupState
Syntax:	ara::exec::FunctionGroupState & operator= (const ara::exec::FunctionGroupState &other) & noexcept;
Parameters (in):	other	FunctionGroupState instance to be copied
Return value:	FunctionGroupState &	reference to the object on which the copy assignment operator was invoked
Exception Safety:	exception safe
Thread Safety:	not thread-safe
Description:	Copy assignment operator.

5.1.1.1.4 Move Assignment Operator

Kind:	function
Header file:	#include "ara/exec/function_group_state.h"
Scope:	ara::exec::FunctionGroupState
Syntax:	ara::exec::FunctionGroupState & operator= (ara::exec::FunctionGroupState &&other) & noexcept;
Parameters (in):	other	FunctionGroupState instance to move to this object.
Return value:	FunctionGroupState &	reference to the object on which the move assignment operator was invoked
Exception Safety:	exception safe
Thread Safety:	not thread-safe
Description:	Move assignment operator.

5.1.1.1.5 Destructor

Kind:	function
Header file:	#include "ara/exec/function_group_state.h"
Scope:	ara::exec::FunctionGroupState
Syntax:	~FunctionGroupState() noexcept;
Exception Safety:	exception safe
Thread Safety:	not thread-safe
Description:	Destructor of the FunctionGroupState instance.

5.1.1.2 Constructors

5.1.1.2.1 FunctionGroupState

Kind:	function
Header file:	#include "ara/exec/function_group_state.h"
Scope:	ara::exec::FunctionGroupState
Syntax:	FunctionGroupState (const ara::exec::FunctionGroup &functionGroup, ara::core::StringView state) noexcept;
Parameters (in):	functionGroup	the FunctionGroup instance the state shall be connected with.
	state	short name of the ModeDeclaration which represents the Function Group State.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	Creates an instance of FunctionGroupState.

5.1.1.3 Member Functions

5.1.1.3.1 operator!=

Kind:	function
Header file:	#include "ara/exec/function_group_state.h"
Scope:	ara::exec::FunctionGroupState
Syntax:	bool operator!= (const ara::exec::FunctionGroupState &other) const noexcept;
Parameters (in):	other	FunctionGroupState instance to compare this one with.
Return value:	bool	false in case both FunctionGroupStates are representing exactly the same meta-model element, true otherwise.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	uneq operator to compare with other FunctionGroupState instance.

5.1.1.3.2 operator==

Kind:	function
Header file:	#include "ara/exec/function_group_state.h"
Scope:	ara::exec::FunctionGroupState
Syntax:	bool operator== (const ara::exec::FunctionGroupState &other) const noexcept;
Parameters (in):	other	FunctionGroupState instance to compare this one with.
Return value:	bool	true in case both FunctionGroupStates are representing exactly the same meta-model element, false otherwise.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	eq operator to compare with other FunctionGroupState instance.

6 Header: ara/exec/state_client.h

6.1 Class: StateClient

Kind:	class
Header file:	#include "ara/exec/state_client.h"
Forwarding header file:	#include "ara/exec/exec_fwd.h"
Scope:	namespace ara::exec
Symbol:	StateClient
Syntax:	class StateClient final {...};
Description:	ara::exec::StateClient is an interface of Execution Management that is used by State Management to request transitions between Function Group States or to perform other related operations. Class used to perform Function Group state management operation needed during lifetime of a Machine. State Management during its own lifetime will need to start and stop software, that is intended to run on a Machine managed by it. This can be achieved by performing state transition of a Function Group to which required software is assigned. Integrator will assign software to run in a particular state (of Function Group) and State Management can start it, by requesting Execution Management to perform state transition (of this Function Group) to the mentioned state. Execution Management will then start mentioned software and report transition result back to State Management. Please note that stopping software can be done in similar way (i.e. Function Group state transition, to a state in which software is not configured to be run).
Notes:	ara::exec::StateClient opens communication channel to Execution Management (e.g. POSIX FIFO). Each Process that intends to perform state management, should create an instance of this class and it should have rights to use it. To eventually implement the Named Constructor Idiom, the developer may either make the default constructor private or delete it and define a non-default constructor.

6.1.1 Public Member Functions

6.1.1.1 Special Member Functions

6.1.1.1.1 Copy Constructor

Kind:	function
Header file:	#include "ara/exec/state_client.h"
Scope:	ara::exec::StateClient
Syntax:	StateClient (const StateClient &)=delete;
Description:	Suppress default copy construction for StateClient.

6.1.1.1.2 Move Constructor

Kind:	function
Header file:	#include "ara/exec/state_client.h"
Scope:	ara::exec::StateClient
Syntax:	StateClient (StateClient &&rval) noexcept;
Parameters (in):	rval	reference to move
Exception Safety:	exception safe
Thread Safety:	not thread-safe
Description:	Intentional use of move constructor for StateClient.

6.1.1.1.3 Copy Assignment Operator

Kind:	function
Header file:	#include "ara/exec/state_client.h"
Scope:	ara::exec::StateClient
Syntax:	ara::exec::StateClient & operator= (const ara::exec::StateClient &)=delete;
Description:	Suppress default copy assignment for StateClient.

6.1.1.1.4 Move Assignment Operator

Kind:	function
Header file:	#include "ara/exec/state_client.h"
Scope:	ara::exec::StateClient
Syntax:	ara::exec::StateClient & operator= (ara::exec::StateClient &&rval) noexcept;
Parameters (in):	rval	reference to move
Return value:	StateClient &	the new reference
Exception Safety:	exception safe
Thread Safety:	not thread-safe
Description:	Intentional use of move assignment for StateClient.

6.1.1.1.5 Destructor

Kind:	function
Header file:	#include "ara/exec/state_client.h"
Scope:	ara::exec::StateClient
Syntax:	~StateClient() noexcept;
Exception Safety:	exception safe
Thread Safety:	not thread-safe
Description:	noexcept destructor

6.1.1.2 Constructors

6.1.1.2.1 StateClient

Kind:	function
Header file:	#include "ara/exec/state_client.h"
Scope:	ara::exec::StateClient
Syntax:	StateClient (std::function< void(const ara::exec::ExecutionErrorEvent &)> undefinedStateCallback) noexcept(false);
Parameters (in):	undefinedStateCallback	callback to be invoked by StateClient library if a FunctionGroup changes its state unexpectedly to an Undefined Function Group State, i.e. without previous request by SetState(). The affected FunctionGroup and ExecutionError is provided as an argument to the callback in form of ExecutionErrorEvent Lifetime: it is expected that undefinedStateCallback remains callable, during entire lifetime of the StateClient instance. This is especially important if, undefinedStateCallback is bound to an instance of a class (e.g. using std::bind).
Exception Safety:	not exception safe
Thread Safety:	thread-safe
Errors:	ara::exec::ExecErrc::kNoCommunication	no_rollback_semantics
		Communication error occurred. Recovery: try again
	ara::exec::ExecErrc::kInvalidArgument	rollback_semantics
		Given undefinedStateCallback doesn't contain a callable function. Recovery: change argument
Description:	Regular constructor for StateClient.

6.1.1.3 Member Functions

6.1.1.3.1 Create

Kind:	function
Header file:	#include "ara/exec/state_client.h"
Scope:	ara::exec::StateClient
Syntax:	static ara::core::Result< ara::exec::StateClient > Create (std::function< void(const ara::exec::ExecutionErrorEvent &)> undefinedStateCallback) noexcept;
Parameters (in):	undefinedStateCallback	callback to be invoked by StateClient library if a FunctionGroup changes its state unexpectedly to an Undefined Function Group State, i.e. without previous request by SetState(). The affected FunctionGroup and ExecutionError is provided as an argument to the callback in form of ExecutionErrorEvent. Lifetime: it is expected that undefinedStateCallback remains callable, during entire lifetime of the StateClient instance. This is especially important if, undefinedStateCallback is bound to an instance of a class (e.g. using std::bind).
Return value:	ara::core::Result< StateClient >	a result that contains either a StateClient object or an error.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Errors:	ara::exec::ExecErrc::kNoCommunication	no_rollback_semantics
		Communication error occurred. Recovery: try again
	ara::exec::ExecErrc::kInvalidArgument	rollback_semantics
		Given undefinedStateCallback doesn't contain a callable function. Recovery: change argument
Description:	Named constructor for StateClient.
Notes:	This named constructor may call a private constructor defined by the developer.

6.1.1.3.2 GetExecutionError

Kind:	function
Header file:	#include "ara/exec/state_client.h"
Scope:	ara::exec::StateClient
Syntax:	ara::core::Result< ara::exec::ExecutionErrorEvent > GetExecutionError (const ara::exec::FunctionGroupState &functionGroupState) noexcept;
Parameters (in):	functionGroupState	Function Group State of interest.
Return value:	ara::core::Result< ara::exec::ExecutionErrorEvent >	The execution error which changed the Function Group of the given Function Group State to an Undefined Function Group State.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Errors:	ara::exec::ExecErrc::kOperationFailed	rollback_semantics
		The Function Group of the given Function Group State is not in an Undefined Function Group State. Recovery: Function should only be called, if the given function group is in an undefined function group state. The problem has likely already been resolved.
	ara::exec::ExecErrc::kNoCommunication	rollback_semantics
		if StateClient can't communicate with Execution Management (e.g. IPC link is down). Recovery: Call function again
	ara::exec::ExecErrc::kInvalidMetaModelIdentifier	rollback_semantics
		The given Function Group State couldn't be found in the Processed Manifest or Process does not have a mapping to the Function Group of the given Function Group State. Recovery: Call function with a different argument
Description:	Returns the execution error which changed the Function Group of the given Function Group State to an Undefined Function Group State. This function will return with error and will not return an ExecutionErrorEvent object, if the Function Group is in a defined Function Group state again.

6.1.1.3.3 GetInitialMachineStateTransitionResult

Kind:	function
Header file:	#include "ara/exec/state_client.h"
Scope:	ara::exec::StateClient
Syntax:	ara::core::Future< void > GetInitialMachineStateTransitionResult () const noexcept;
Return value:	ara::core::Future< void >	void if requested transition is successful, otherwise it returns ExecErrorDomain error.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Errors:	ara::exec::ExecErrc::kOperationCanceled	rollback_semantics
		StateManagement may decide to cancel transition and start specific startup sequence. This could happen for number of reasons and one of them could be interrupted Machine update sequence. Recovery: Call SetState again with initial state
	ara::exec::ExecErrc::kOperationFailed	rollback_semantics
		if transition to the requested Function Group state failed. Recovery: Call SetState again with initial state
	ara::exec::ExecErrc::kNoCommunication	rollback_semantics
		if StateClient can't communicate with Execution Management (e.g. IPC link is down). Recovery: Call function again
	ara::exec::ExecErrc::kInvalidMetaModelIdentifier	rollback_semantics
		Process does not have a mapping to MachineFG. Recovery: Indicates configuration problem (should never happen)
Description:	Method to retrieve result of Machine State initial transition to Startup state.
Notes:	This method allows State Management to retrieve the result of a transition specified by and . Please note that this transition happens once per machine life cycle, thus the result delivered by this method shall not change (unless machine is started again). Please note that concerns about returned ara::core::Future from ara::exec::StateClient::SetState() apply for ara::exec::StateClient::GetInitialMachineStateTransitionResult().

6.1.1.3.4 SetState

Kind:	function
Header file:	#include "ara/exec/state_client.h"
Scope:	ara::exec::StateClient
Syntax:	ara::core::Future< void > SetState (const ara::exec::FunctionGroupState &state) const noexcept;
Parameters (in):	state	representing meta-model definition of a state inside a specific Function Group. Execution Management will perform state transition from the current state to the state identified by this parameter.
Return value:	ara::core::Future< void >	void if requested transition is successful, otherwise it returns ExecErrorDomain error.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Errors:	ara::exec::ExecErrc::kOperationCanceled	no_rollback_semantics
		if transition to the requested Function Group state was cancelled by a newer request. Recovery: Try again (error is informative, does not indicate a problem)
	ara::exec::ExecErrc::kOperationFailed	no_rollback_semantics
		if transition to the requested Function Group state failed. Recovery: Try transition to another state
	ara::exec::ExecErrc::kNoCommunication	no_rollback_semantics
		if StateClient can't communicate with Execution Management (e.g. IPC link is down). Rovery: Try again
	ara::exec::ExecErrc::kInvalidTransition	rollback_semantics
		if transition to the requested state is prohibited (e.g. Off state for MachineFG) or the requested Function Group State is invalid (e.g. does not exist anymore after a software update). Recovery: Eventually try transition to another state
	ara::exec::ExecErrc::kIntegrityOrAuthenticityCheckFailed	no_rollback_semantics
		if an integrity or authenticity check failed during state transition. Recovery: transition to another state
	ara::exec::ExecErrc::kUnexpectedTermination	no_rollback_semantics
		One of the processes terminated in an unexpected way during the state transition. Recovery: transition to another state
	ara::exec::ExecErrc::kInvalidMetaModelIdentifier	rollback_semantics
		The given Function Group State couldn't be found in the Processed Manifest or Process does not have a mapping to the Function Group of the requested Function Group State. Recovery: transition to another state
Description:	Method to request state transition for a single Function Group. This method will request Execution Management to perform state transition and return immediately. Returned ara::core::Future can be used to determine result of requested transition.
Notes:	Asynchronous nature of ara::exec::StateClient::SetState() makes the returned ara::core::Future dependable on lifetime of the instance from which it was received. It is expected that once state change request is received by Execution Management, it will be processed independently of lifetime of the instance from which it was requested. Please note that the qualified short names representing Function Groups and Function Group States could be quite long. They can be replaced by implementation specific data types to speed up any checks that have to be performed by the ara::exec::StateClient::SetState() method. This is enabled by the ara::exec::FunctionGroupState data-type.

See also

• Execution state reporting example: Build with CMake — main.cpp
• Function Group state/manifest: Function Group configuration, Execution configuration