class ara::exec::ExecutionClient

The class ara::exec::ExecutionClient serves application processes to bindingly report their internal execution state to Execution Management ([SWS_EM_02003]). During initialization, it also takes over intercepting the SIGTERM signal and forwards it to a user-defined termination handler in a background thread ([SWS_EM_02562]). As a move-only object, the instance strictly binds signal handling to its lifecycle and restores the previous signal state upon destruction. Callers must ensure that the registered callback remains invokable throughout the entire instance lifetime.

more ›

Context

The class ara::exec::ExecutionClient serves processes on the Adaptive Platform to report their internal execution state to Execution Management ([SWS_EM_02003]). It acts as a standardized interface between the running application and central process management. In addition to forwarding state transitions, the instance assumes responsibility for handling the operating system signal SIGTERM ([SWS_EM_02562], [SWS_EM_02002]). Upon arrival of the signal, it executes a user-defined callback in a separate background thread to allow the application an orderly termination ([SWS_EM_02562]). Interpretation: The operating system or Execution Management is likely to transmit the signal SIGTERM to the process when termination of the execution unit is requested. Question Q-51eee947d01ae8b4 (open)

Context diagram: Interaction between application process, ExecutionClient, Execution Management, and signal mechanism. Sources: [SWS_EM_02003], [SWS_EM_02562], [SWS_EM_02002].

Lifecycle

Instantiation of ara::exec::ExecutionClient takes place either via the static factory method Create ([SWS_EM_02562]) or the regular constructor ([SWS_EM_02560]). While Create is exception safe (noexcept) and returns the result encapsulated in an ara::core::Result ([SWS_EM_02562]), the regular constructor is declared as noexcept(false) ([SWS_EM_02560]). Both creation paths expect a callable std::function<void()> callback as a parameter (terminationHandler). This callback must remain valid and callable throughout the entire lifetime of the ExecutionClient instance ([SWS_EM_02562], [SWS_EM_02560]).

With regard to ownership, the class is designed as move-only: the copy constructor ([SWS_EM_02563]) and the copy assignment operator ([SWS_EM_02564]) are explicitly deleted (delete). Transfer of instances is exclusively possible via the move constructor ([SWS_EM_02580]) and the move assignment operator ([SWS_EM_02581]), both of which are exception safe (noexcept), but not thread-safe. The factory method Create and the constructor itself are considered thread-safe ([SWS_EM_02562], [SWS_EM_02560]).

The destructor ~ExecutionClient() is defined as noexcept ([SWS_EM_02002]) and is not thread-safe. When the instance is destroyed, responsibility for the signal SIGTERM is relinquished: the destructor resets the signal handler for SIGTERM to the original state that was active before instantiation ([SWS_EM_02002]).

Usage Path

The regular sequence is divided into initialization, state reporting, and orderly termination:

• Creation: At the start of the process runtime, the instance is initialized via Create, with the termination handler being passed ([SWS_EM_02562]). Typically, this handler sets a flag or signals synchronization primitives to unblock running threads.
• State reporting: As soon as the process is ready, it reports its execution state to Execution Management via ReportExecutionState ([SWS_EM_02003]). The call is thread-safe and can take place from various worker threads.
• Signal reception and termination: If an SIGTERM signal arrives during runtime, ExecutionClient activates the registered terminationHandler asynchronously in a background thread ([SWS_EM_02562]). The process completes open tasks in an orderly manner.
• Destruction: Upon leaving scope, the destructor restores the original signal configuration ([SWS_EM_02002]).

Sequence diagram: Sequence from creation through state reporting to signal-driven termination. Sources: [SWS_EM_02562], [SWS_EM_02003], [SWS_EM_02002].

Error Scenarios

When using ExecutionClient, different error conditions are covered by error codes from ara::exec::ExecErrc:

• ara::exec::ExecErrc::kInvalidArgument: Occurs during instantiation via Create ([SWS_EM_02562]) or the regular constructor ([SWS_EM_02560]) if the passed terminationHandler object does not contain a callable function. The system applies rollback semantics; to resolve this, a valid callable must be passed.
• ara::exec::ExecErrc::kNoCommunication: Can occur both during creation ([SWS_EM_02562], [SWS_EM_02560]) and during ReportExecutionState ([SWS_EM_02003]) if a communication error exists between the application process and Execution Management (e.g., no acknowledgment of message reception). No rollback semantics apply here; a retry attempt is intended as a recovery action.
• ara::exec::ExecErrc::kInvalidTransition: Returned by ReportExecutionState ([SWS_EM_02003]) if an impermissible state transition is requested, for example reporting an already active state again, such as kRunning. Since the state has already been reported, no retransmission is required (rollback semantics).