class ara::shwa::DeviceSelector

The abstract class ara::shwa::DeviceSelector defines a strategy interface for evaluating and selecting target devices in subsystem shwa. Via SelectDevice(), it enables the direct determination of an optimal device, as well as the comparative evaluation of individual candidate devices via operator() [AP_SWS_SHWA_00403], [AP_SWS_SHWA_00404]. The virtual default destructor guarantees the safe destruction of derived strategy instances. Key constraints include that invocations are not thread-safe and that no automatic rollback semantics apply in the event of failures.

more ›

Context

In module shwa, class ara::shwa::DeviceSelector provides an abstract interface to select or evaluate hardware or functional devices (Device) based on a specific selection strategy. It serves as a decoupling layer between a higher-level control application and the concrete selection methods. Participating interaction partners include the calling application, the concrete implementation of the selection strategy, and the target objects of type Device. The interface defines two central operations: direct selection of a device via SelectDevice() [AP_SWS_SHWA_00403], and comparative individual evaluation of a device via the function call operator operator() [AP_SWS_SHWA_00404].

Context diagram: Embedding of DeviceSelector between application and device targets. Sources: [AP_SWS_SHWA_00403], [AP_SWS_SHWA_00404]

Lifecycle

As an abstract base class with pure virtual methods, DeviceSelector cannot be instantiated directly. Concrete selection strategies are likely implemented as derived classes and created by the application component. Question Q-4e22b2e57ef141e9 (open) Managing ownership is typically the responsibility of the application, for example via smart pointers such as std::unique_ptr<DeviceSelector>. For clean polymorphic destruction of specialized classes, the interface declares a virtual default destructor ~DeviceSelector() [AP_SWS_SHWA_00402]. This is explicitly designated as noexcept, thereby satisfying the requirements for exception safety (exception safe) when destructing the instances [AP_SWS_SHWA_00402].

Regarding concurrency and state transitions, the interface operations are classified as not thread-safe (not thread-safe) [AP_SWS_SHWA_00403], [AP_SWS_SHWA_00404]. Although the member functions are annotated with const, concurrent accesses to the same instance from different threads must not take place without external synchronization. In addition, the specification does not provide for automatic rollback for failed calls (no_rollback_semantics) [AP_SWS_SHWA_00403], [AP_SWS_SHWA_00404].

Usage Path

A typical usage sequence comprises initializing a concrete strategy instance and subsequently evaluating or selecting candidate devices. Here, two primary call paths exist:

• Direct device selection: The application invokes the parameterless method SelectDevice() [AP_SWS_SHWA_00403]. The concrete strategy autonomously determines the most suitable device and returns a ara::core::Result<Device>.
• Iterative individual evaluation: In algorithms for filtering or sorting multiple candidates, the application successively passes the respective instances to operator()(const Device &device) [AP_SWS_SHWA_00404]. The evaluation via operator() is likely to analyze relevant properties or operating states of the passed device internally. Question Q-8ba0b9b900196d50 (open) The returned int value in ara::core::Result<int> is likely to reflect a suitability metric or priority on the basis of which the calling entity makes a selection decision.

Sequence diagram: Invocation sequences for individual evaluation and direct selection including error handling. Sources: [AP_SWS_SHWA_00403], [AP_SWS_SHWA_00404]

Error Scenarios

Both selection methods are declared as noexcept and do not throw C++ exceptions (exception safe). Instead, they signal failures via the error channel of ara::core::Result. Applications must always check the return value for errors before the result is accessed. The following error states are defined for SelectDevice() and operator():

• ShwaErrorCode::kResourceBusy: The requested operation could not be executed because the required resource is currently busy [AP_SWS_SHWA_00403], [AP_SWS_SHWA_00404]. In this case, the application can retry the call at a later point in time or select an alternative strategy.
• ShwaErrorCode::kFeatureNotSupported: Returned if functionality requested for selection or evaluation is not supported by the underlying implementation [AP_SWS_SHWA_00403], [AP_SWS_SHWA_00404].

Because no rollback semantics exist (no_rollback_semantics) [AP_SWS_SHWA_00403], [AP_SWS_SHWA_00404], the system remains in the current state in case of an error, and the calling entity is responsible for suitable compensatory measures. As a precondition for operator(), it also applies that the passed device reference must remain valid throughout the entire call.