类 ara::shwa::TaskHandler

类 ara::shwa::TaskHandler 用于通过队列提交在加速器硬件上执行任务 [AP_SWS_SHWA_01203]。新实例通过静态工厂方法 Create() 以线程安全的方式创建，该方法在 ara::core::Result 中返回错误 [AP_SWS_SHWA_01202]。通过 SingleTask 以及 ParallelFor，可以将单个或数据并行计算步骤传递到目标设备。虽然实例化是线程安全的，但任务提交不是线程安全的，并且在并发访问时需要外部同步。

更多 ›

上下文

类 ara::shwa::TaskHandler 作为 final 类（final），是 AUTOSAR Adaptive Platform 内硬件加速模块（shwa）的一部分。它充当在选定目标设备（Device）上传递和执行计算任务的核心接口。在软件架构中，该类承担应用软件组件与底层执行基础设施之间的中介角色。

交互主要在两个系统伙伴之间进行：调用方应用程序与选定的硬件加速器或其任务队列。应用端定义的计算操作通过 ara::shwa::TaskHandler 的接口接收，并作为队列提交转发到 Device [AP_SWS_SHWA_01203]。这既支持处理单个计算步骤，也支持数据并行处理模式 [AP_SWS_SHWA_01204]。解释：该类应该封装特定于设备的队列，从而使应用程序组件能够控制加速器资源，而无需绑定到底层硬件细节。 问题 (未决)

生命周期

ara::shwa::TaskHandler 实例的生命周期通过严格的工厂模式进行控制。实例化仅通过静态工厂方法 Create() [AP_SWS_SHWA_01202] 进行。由于该类被声明为 final，因此排除了通过继承进行特化的可能性。创建的对象打包在 ara::core::Result<TaskHandler> 中返回，因此必须显式检查初始化是否成功 [AP_SWS_SHWA_01202]。

在并发性和线程安全性方面，该类表现出不同的特性：

• 实例化：静态方法 Create() 的调用是线程安全的（thread-safe）[AP_SWS_SHWA_01202]。因此，多个线程可以通过工厂路径并发创建新的处理程序实例。
• 任务提交：用于传递工作任务的方法 SingleTask [AP_SWS_SHWA_01203] 和 ParallelFor [AP_SWS_SHWA_01204] 明确指定为非线程安全（not thread-safe）。因此，不得在未经协调的情况下从多个线程同时访问 TaskHandler 的单个实例；同步由调用方负责。
• 异常安全性：该接口的所有方法均声明为 noexcept 并保证异常安全性（exception safe）[AP_SWS_SHWA_01202]、[AP_SWS_SHWA_01203]、[AP_SWS_SHWA_01204]。如果初始化失败，Create() 还会应用回滚语义（rollback_semantics）[AP_SWS_SHWA_01202]。

所有权仍保留在应用组件中，该组件持有该实例，并在不再需要进一步的队列提交时将其销毁。

使用路径

典型流程分为创建、任务配置和任务提交阶段。首先，应用程序通过 ara::shwa::TaskHandler::Create() 请求一个新实例 [AP_SWS_SHWA_01202]。在成功验证 ara::core::Result 后，该对象便准备好接收工作任务。

随后，应用程序根据处理模式决定合适的提交方法：

• 对于单个计算任务，调用 SingleTask(cfg)，从而将作为参数传递的 Task 函数排入选定目标设备的队列中 [AP_SWS_SHWA_01203]。
• 对于数据并行处理模式，可使用函数模板 ParallelFor(bufferSize, cfg) [AP_SWS_SHWA_01204]。此处除了配置之外，还会传递缓冲区大小（bufferSize），以控制加速器设备上跨多个数据元素的并行处理。

解释：模板参数 T 应该表示一个可调用函数、Lambda 或相应的任务配置，用于封装在 Device 上执行的计算逻辑。 问题 Q-2fca8604440b44e9 (未决)

时序图：从实例化到向设备队列提交任务的交互链。来源：[AP_SWS_SHWA_01202]、[AP_SWS_SHWA_01203]、[AP_SWS_SHWA_01204]

错误场景

ara::shwa::TaskHandler 中的错误处理遵循 Adaptive Platform 的无异常范式（noexcept）。

错误状态主要在实例化期间发生：

• 工厂方法 Create() 通过返回值 ara::core::Result [AP_SWS_SHWA_01202] 中的错误通道报告失败。
• 具体错误标识符定义为 ShwaErrorCode::kRuntime，用于指示对象创建期间的常规运行时错误 [AP_SWS_SHWA_01202]。通过规定的回滚语义，确保在发生失败时不会产生部分初始化的状态或资源泄漏 [AP_SWS_SHWA_01202]。

调用 SingleTask [AP_SWS_SHWA_01203] 和 ParallelFor [AP_SWS_SHWA_01204] 不提供返回值（void）且不引发异常。因此，调用方必须确保处理程序实例有效，并在存在并发线程时对访问进行外部同步。