class apext::sm::PowerStateInterface

As an OS wrapper, the interface coordinates power states between State Management and the operating system ([SWS_SM_71000]). Via it, State Management registers callback handlers for wakeup events in advance and forwards specific state requests to the operating system ([SWS_SM_71001]). After reactivation has occurred, the handler registration in the OS wrapper can be canceled. An essential functional constraint is that all method calls are not thread-safe and therefore must strictly be serialized by the caller.

more ›

Context

C++ class apext::sm::PowerStateInterface acts as the functional interface of the State Management module for coordinating power states with the operating system ([SWS_SM_71000], SWS StateManagement §C.1.2 “Class: PowerStateInterface”). In the system architecture, it takes on the role of an OS wrapper that forwards requests from State Management to the underlying operating system and receives feedback. Three core components are involved in the overall interaction: State Management as the coordinating instance, class PowerStateInterface as the mediator, and the host operating system, which executes the hardware-related power management ([SWS_SM_71001]).

Context diagram: Coordination of power states and wakeup signals between State Management, OS wrapper, and operating system. Sources: [SWS_SM_71000], [SWS_SM_71001], [SWS_SM_71003].

Lifecycle

The creation and destruction of instances of class PowerStateInterface is not governed via explicit factory methods in the specification documents. According to the interpretation, instantiation is likely performed by State Management during its initialization phase to provide the OS wrapper. Question Q-15bde6ce044e9bc3 (open) Header apext/sm/power_state_interface.h is intended for including the class ([SWS_SM_71001], SWS StateManagement §C.1.2.1.1 “Member Functions”).

With regard to internal state, the object manages the registration of a handler for wakeup events. This state remains active until the handler is explicitly removed again ([SWS_SM_71005]). Regarding concurrency, all member functions are classified as not thread-safe (not-threadsafe) ([SWS_SM_71001], [SWS_SM_71003], [SWS_SM_71005]). The calling State Management must therefore ensure under its own responsibility that calls to an instance are strictly serialized and that no unprotected parallel accesses occur from multiple threads.

Usage Path

A typical usage path for controlling power states and receiving wakeup signals proceeds in several coordinated steps:

• Handler registration: Prior to initiating a power-saving state, State Management registers a callback function of type apext::sm::WakeUpHandler in the OS wrapper by means of RegisterWakeUpHandler ([SWS_SM_71003], SWS StateManagement §C.1.2.1.1.1 “RegisterWakeUpHandler”). This defines how State Management is informed about subsequent wakeup processes.
• State request: Subsequently, State Management calls method SetPowerState with the desired target state apext::sm::PowerState ([SWS_SM_71001], SWS StateManagement §C.1.2.1.1.2 “SetPowerState”). The interface forwards this request directly to the operating system. The technical implementation of the transition presumably takes place in a platform-specific manner in the operating system. Question Q-29345b74ba3bedf2 (open)
• Wakeup notification: If the operating system detects a wakeup event, the notification is reported to the OS wrapper. The wrapper executes the previously registered WakeUpHandler. According to the interpretation, the invocation is likely to occur asynchronously in the execution context of the reactivation process. Question (open)
• Handler deregistration: As soon as the wakeup process is completed or State Management requires no further notifications, the registered callback is removed from the OS wrapper via UnregisterWakeUpHandler ([SWS_SM_71005], SWS StateManagement §C.1.2.1.1.3 “UnregisterWakeUpHandler”).

Sequence diagram: Typical sequence of handler registration, state forwarding to the operating system, and deregistration. Sources: [SWS_SM_71001], [SWS_SM_71003], [SWS_SM_71005].

Error Scenarios

The interface methods RegisterWakeUpHandler, SetPowerState, and UnregisterWakeUpHandler have the return type void and do not define specific error return codes ([SWS_SM_71001], [SWS_SM_71003], [SWS_SM_71005]). All functions are declared as noexcept and guarantee full exception safety (exception safe).

Erroneous system states can arise primarily from violations of preconditions. These include violation of the required thread safety through unprotected parallel method calls. Furthermore, as a precondition for RegisterWakeUpHandler, State Management must ensure that the passed function object is valid and remains in memory until removal by UnregisterWakeUpHandler ([SWS_SM_71003], [SWS_SM_71005]).