类 ara::exec::ExecutionClient

类 ara::exec::ExecutionClient 用于应用程序进程向 Execution Management 具有约束力地报告其内部执行状态（[SWS_EM_02003]）。在初始化时，它还负责拦截 SIGTERM 信号，并将其转发给后台线程中的自定义终止 Handler（[SWS_EM_02562]）。作为仅移动（Move-only）对象，该实例将其生命周期与信号处理严格绑定，并在销毁时恢复先前的信号状态。调用方必须确保注册的回调在整个实例生命周期内保持可调用状态。

更多 ›

上下文

类 ara::exec::ExecutionClient 用于 Adaptive Platform 上的进程向 Execution Management 报告其内部执行状态（[SWS_EM_02003]）。它充当正在运行的应用程序与中央进程管理之间的标准化接口。除了转发状态转换外，该实例还负责处理操作系统信号 SIGTERM（[SWS_EM_02562]、[SWS_EM_02002]）。在信号到达时，它会在单独的后台线程中执行用户定义的回调，以便应用程序进行有序终止（[SWS_EM_02562]）。解释：当请求终止执行单元时，操作系统或 Execution Management 可能会将信号 SIGTERM 发送给进程。 问题 Q-51eee947d01ae8b4 (未决)

上下文图：应用程序进程、ExecutionClient、Execution Management 与信号机制之间的交互。来源：[SWS_EM_02003]、[SWS_EM_02562]、[SWS_EM_02002]。

生命周期

ara::exec::ExecutionClient 的实例化可以选择通过静态工厂方法 Create（[SWS_EM_02562]）或常规构造函数（[SWS_EM_02560]）进行。虽然 Create 是异常安全的（noexcept）并将结果封装在 ara::core::Result 中返回（[SWS_EM_02562]），但常规构造函数声明为 noexcept(false)（[SWS_EM_02560]）。这两种创建路径都需要一个可调用的 std::function<void()> 回调作为参数（terminationHandler）。该回调必须在 ExecutionClient 实例的整个生命周期内保持有效且可调用（[SWS_EM_02562]、[SWS_EM_02560]）。

在所有权方面，该类被设计为仅移动（Move-only）：拷贝构造函数（[SWS_EM_02563]）和拷贝赋值运算符（[SWS_EM_02564]）已被显式删除（delete）。实例的转移只能通过移动构造函数（[SWS_EM_02580]）和移动赋值运算符（[SWS_EM_02581]）进行，这两者均是异常安全的（noexcept），但不是线程安全的。工厂方法 Create 和构造函数本身被视为线程安全的（[SWS_EM_02562]、[SWS_EM_02560]）。

析构函数 ~ExecutionClient() 定义为 noexcept（[SWS_EM_02002]）且不是线程安全的。在销毁实例时，对信号 SIGTERM 的责任将被重新移交：析构函数将 SIGTERM 的信号 Handler 重置为实例化之前处于活动状态的原始状态（[SWS_EM_02002]）。

使用路径

常规流程分为初始化、状态传输和有序终止：

• 创建：在进程运行时间开始时，通过 Create 初始化实例，并传入终止 Handler（[SWS_EM_02562]）。通常，该 Handler 会设置标志或向同步原语发出信号，以解除正在运行的线程的阻塞。
• 状态报告：一旦进程就绪，它就会通过 ReportExecutionState 向 Execution Management 报告其执行状态（[SWS_EM_02003]）。该调用是线程安全的，可以从不同的工作线程中发起。
• 信号接收与终止：如果在运行期间到达 SIGTERM 信号，ExecutionClient 会在后台线程中异步激活所保存的 terminationHandler（[SWS_EM_02562]）。进程有序完成未决任务。
• 销毁：离开作用域时，析构函数恢复原始信号配置（[SWS_EM_02002]）。

时序图：从创建、状态报告到信号驱动终止的流程。来源：[SWS_EM_02562]、[SWS_EM_02003]、[SWS_EM_02002]。

错误场景

使用 ExecutionClient 时，不同的错误情况由来自 ara::exec::ExecErrc 的错误代码覆盖：

• ara::exec::ExecErrc::kInvalidArgument：如果传入的 terminationHandler 对象不包含可调用函数，则在通过 Create（[SWS_EM_02562]）或常规构造函数（[SWS_EM_02560]）实例化时发生。系统应用回滚语义；若要修复，必须传入有效的 Callable。
• ara::exec::ExecErrc::kNoCommunication：在应用程序进程与 Execution Management 之间存在通信错误时（例如未确认消息接收），无论在创建（[SWS_EM_02562]、[SWS_EM_02560]）还是在 ReportExecutionState（[SWS_EM_02003]）时都可能发生。此处不适用回滚语义；作为恢复措施，应重新尝试调用。
• ara::exec::ExecErrc::kInvalidTransition：如果请求了不允许的状态转换，例如重新报告已处于活动状态的状态（如 kRunning），则由 ReportExecutionState（[SWS_EM_02003]）返回。由于该状态已被报告，因此无需重新传输（回滚语义）。