class ara::shwa::DeviceMonitor

The class ara::shwa::DeviceMonitor serves for the synchronous monitoring of the state of hardware devices in the functional cluster shwa. Instances are created via the static factory method Create based on a device reference ([AP_SWS_SHWA_01407]), after which the device status can be continuously queried via the method Status() ([AP_SWS_SHWA_01409]). While creation via factory methods is executed thread-safely, the call for status query is not thread-safe and presumably requires application-side synchronization in case of concurrent access. Question (open)

more ›

Context

The class ara::shwa::DeviceMonitor provides the central interface for monitoring the state of hardware devices in module shwa. Application software uses the class to query the operating status of a hardware component identified via a device reference Device or via a selector element DeviceSelector ([AP_SWS_SHWA_01407], [AP_SWS_SHWA_01408]). By encapsulating the status determination in the return type DeviceStatus ([AP_SWS_SHWA_01409]), DeviceMonitor decouples the calling control application from internal hardware details and serves as a standardized observer for the life and fault cycle of the addressed device.

Lifecycle

Instances of DeviceMonitor cannot be created via a parameterless default constructor, as it is explicitly deleted ([AP_SWS_SHWA_01402]). Instead, object creation occurs in a controlled manner via two static factory methods: Create(const Device &device) ([AP_SWS_SHWA_01407]) or the template function Create(const DeviceSelector &deviceSelector) ([AP_SWS_SHWA_01408]). Both factory paths return a ara::core::Result<DeviceMonitor>, are specified as exception-safe (exception safe), and guarantee thread safety.

Regarding ownership and value semantics, the class behaves flexibly: Both copy constructor ([AP_SWS_SHWA_01403]) and copy assignment operator ([AP_SWS_SHWA_01404]) as well as move constructor ([AP_SWS_SHWA_01405]) and move assignment operator ([AP_SWS_SHWA_01406]) are available as standardized (default) and exception-safe (noexcept) operations.

Regarding concurrency, a strict distinction must be made between construction and usage: While creation via the factory functions is thread-safe, the query method Status() is explicitly declared as not thread-safe (not thread-safe) ([AP_SWS_SHWA_01409]). In the event of parallel access by multiple threads to the same instance, application-side synchronization is presumably required. Question Q-4002d6fb6cac23ce (open)

Usage Path

The typical usage path is divided into creating the monitor instance, validating the result, and repeatedly querying the device status. First, the application calls one of the factory methods Create and passes the target component ([AP_SWS_SHWA_01407], [AP_SWS_SHWA_01408]). Subsequently, the application checks the resulting ara::core::Result for success. If the object is valid, the method Status() is called ([AP_SWS_SHWA_01409]), which synchronously returns an object of type DeviceStatus.

Sequence diagram: Typical call sequence from instantiation to repeated status query. Sources: [AP_SWS_SHWA_01407], [AP_SWS_SHWA_01409]

Error Scenarios

Errors predominantly occur during creation via the factory methods Create and are provided without C++ exceptions in the return type ara::core::Result via ShwaErrorCode ([AP_SWS_SHWA_01407], [AP_SWS_SHWA_01408]). The following error states are defined for creation:

• ShwaErrorCode::kRuntime: A general runtime error occurred during initialization ([AP_SWS_SHWA_01407], [AP_SWS_SHWA_01408]).
• ShwaErrorCode::kResourceBusy: The underlying resource is currently busy, so the monitor creation cannot be completed immediately ([AP_SWS_SHWA_01407], [AP_SWS_SHWA_01408]).
• ShwaErrorCode::kInvalidParameter: An invalid argument was passed to the call, for example an invalid device specification ([AP_SWS_SHWA_01407], [AP_SWS_SHWA_01408]).
• ShwaErrorCode::kFeatureNotSupported: The requested monitoring function is not supported by the target platform or hardware configuration ([AP_SWS_SHWA_01407], [AP_SWS_SHWA_01408]).

During ongoing operation when calling Status(), no error codes or exceptions are provided; the method is noexcept and guarantees exception safety ([AP_SWS_SHWA_01409]). A hardware failure or connection loss is therefore likely to be mapped in the returned state value DeviceStatus. Question Q-8e2c8c2c7533b36f (open)