class ara::shwa::TaskHandler

The class ara::shwa::TaskHandler serves to execute tasks on accelerator hardware via queue submissions [AP_SWS_SHWA_01203]. New instances are created thread-safely via the static factory method Create(), which returns errors in ara::core::Result [AP_SWS_SHWA_01202]. Via SingleTask as well as ParallelFor, individual or data-parallel computational steps can be transmitted to the target device. While instantiation is thread-safe, task submissions are not thread-safe and require external synchronization in the case of concurrent access.

more ›

Context

The class ara::shwa::TaskHandler is part of the module for hardware acceleration (final) as a final class (shwa) within the AUTOSAR Adaptive Platform. It acts as the central interface for transmitting and executing computational tasks on a selected target device (Device). Within the software architecture, the class assumes the mediator role between the utilizing software component and the underlying execution infrastructure.

Interaction primarily takes place between two system partners: the calling application and the selected hardware accelerator or its task queue. Computational operations defined on the application side are accepted via the interfaces of ara::shwa::TaskHandler and forwarded to the device as queue submissions [AP_SWS_SHWA_01203]. This enables both the processing of individual computational steps and data-parallel processing patterns [AP_SWS_SHWA_01204]. Interpretation: The class is likely to encapsulate the device-specific queues, allowing application components to drive accelerator resources without being coupled to hardware-near details. Question (open)

Lifecycle

The lifecycle of an instance of ara::shwa::TaskHandler is controlled via a strict factory pattern. Instantiation occurs exclusively via the static factory method Create() [AP_SWS_SHWA_01202]. Because the class is declared as final, specialization via inheritance is precluded. The created object is returned wrapped in a ara::core::Result<TaskHandler>, requiring the success of initialization to be explicitly verified [AP_SWS_SHWA_01202].

Regarding concurrency and thread safety, the class exhibits differentiated properties:

• Instantiation: Invoking the static method Create() is thread-safe (thread-safe) [AP_SWS_SHWA_01202]. Multiple threads can thus concurrently create new handler instances via the factory path.
• Task submission: The methods for transmitting work tasks, SingleTask [AP_SWS_SHWA_01203] and ParallelFor [AP_SWS_SHWA_01204], are explicitly specified as not thread-safe (not thread-safe). Consequently, a single instance of TaskHandler must not be accessed uncoordinatedly from multiple threads simultaneously; synchronization is the responsibility of the caller.
• Exception safety: All methods of the interface are declared as noexcept and guarantee exception safety (exception safe) [AP_SWS_SHWA_01202], [AP_SWS_SHWA_01203], [AP_SWS_SHWA_01204]. For Create(), rollback semantics (rollback_semantics) also apply if initialization fails [AP_SWS_SHWA_01202].

Ownership remains with the utilizing component, which holds and destroys the instance once no further queue submissions are required.

Usage Path

The typical flow is divided into the phases of creation, job configuration, and task transmission. First, the application requests a new instance via ara::shwa::TaskHandler::Create() [AP_SWS_SHWA_01202]. After successful validation of the ara::core::Result, the object is ready for work tasks.

Subsequently, the application decides on the appropriate transmission method based on the processing pattern:

• For individual computational tasks, SingleTask(cfg) is called, which queues the task function passed as a parameter into the queue of the selected target device [AP_SWS_SHWA_01203].
• For data-parallel processing patterns, the function template ParallelFor(bufferSize, cfg) is available [AP_SWS_SHWA_01204]. In this case, in addition to the configuration, the buffer size (bufferSize) is passed to control parallel execution across multiple data elements on the accelerator device.

Interpretation: The template parameter T is likely to represent a callable function, a lambda, or a corresponding task configuration that encapsulates the computational logic to be executed on the device. Question Q-2fca8604440b44e9 (open)

Sequence diagram: Interaction chain from instantiation to task submission into the device queue. Sources: [AP_SWS_SHWA_01202], [AP_SWS_SHWA_01203], [AP_SWS_SHWA_01204]

Error Scenarios

Error handling in ara::shwa::TaskHandler follows the exceptionless paradigm (noexcept) of the Adaptive Platform.

Error states occur primarily during instantiation:

• The factory method Create() reports failures via the error channel in the return value ara::core::Result [AP_SWS_SHWA_01202].
• As a concrete error identifier, ShwaErrorCode::kRuntime is defined, signaling general runtime errors during object creation [AP_SWS_SHWA_01202]. The specified rollback semantics ensure that no partially initialized states or resource leaks occur in the event of a failure [AP_SWS_SHWA_01202].

The calls SingleTask [AP_SWS_SHWA_01203] and ParallelFor [AP_SWS_SHWA_01204] provide no return value (void) and throw no exceptions. Callers must therefore ensure that the handler instance is valid and that accesses with concurrent threads are externally synchronized.