类 apext::sm::PowerStateInterface

该接口作为 OS 包装器，协调 State Management 与操作系统之间的电源状态 ([SWS_SM_71000])。State Management 通过它预先注册唤醒事件的回调处理程序，并将具体的状态请求转发给操作系统 ([SWS_SM_71001])。成功重新激活后，可以在 OS 包装器中注销该处理程序注册。一个重要的功能边界条件是，所有方法调用都不是线程安全的，因此调用者必须对其进行串行化。

更多 ›

上下文

C++ 类 apext::sm::PowerStateInterface 用作 State Management 模块的功能接口，用于与操作系统协调电源状态 ([SWS_SM_71000], SWS StateManagement §C.1.2 “Class: PowerStateInterface”)。在系统架构中，它承担 OS 包装器的角色，将 State Management 的请求转发到底层操作系统并接收反馈。整个交互涉及三个核心组件：作为协调实例的 State Management、作为中介的类 PowerStateInterface 以及执行底层电源管理的主机操作系统 ([SWS_SM_71001])。

上下文图：State Management、OS 包装器和操作系统之间电源状态与唤醒信号的协调。来源：[SWS_SM_71000], [SWS_SM_71001], [SWS_SM_71003]。

生命周期

规范文档中未通过显式工厂方法规定类 PowerStateInterface 实例的创建和销毁。根据解释，实例化应该由 State Management 在其初始化阶段执行，以提供 OS 包装器。 问题 Q-15bde6ce044e9bc3 (未决)要包含该类，预定使用头文件 apext/sm/power_state_interface.h ([SWS_SM_71001], SWS StateManagement §C.1.2.1.1 “Member Functions”)。

在内部状态方面，该对象管理唤醒事件处理程序的注册。该状态一直保持活动，直到显式再次移除该处理程序 ([SWS_SM_71005])。关于并发性，所有成员函数均被归类为非线程安全 (not-threadsafe) ([SWS_SM_71001], [SWS_SM_71003], [SWS_SM_71005])。因此，发起调用的 State Management 必须自行确保对实例的调用严格串行化，且不会发生来自多个线程的未受保护的并发访问。

使用路径

用于控制电源状态和接收唤醒信号的典型使用路径分为多个协调步骤进行：

• 处理程序注册：在发起省电状态之前，State Management 通过 RegisterWakeUpHandler 在 OS 包装器中注册一个 apext::sm::WakeUpHandler 类型的回调函数 ([SWS_SM_71003], SWS StateManagement §C.1.2.1.1.1 “RegisterWakeUpHandler”)。由此确定如何将后续唤醒过程通知 State Management。
• 状态请求：随后，State Management 调用带有期望目标状态 apext::sm::PowerState 的方法 SetPowerState ([SWS_SM_71001], SWS StateManagement §C.1.2.1.1.2 “SetPowerState”)。该接口立即将此请求转发给操作系统。状态转换的技术实现推测在操作系统中以平台特定的方式完成。 问题 Q-29345b74ba3bedf2 (未决)
• 唤醒通知：如果操作系统检测到唤醒事件，则将通知报告给 OS 包装器。后者执行先前注册的 WakeUpHandler。根据解释，该调用应该在重新激活过程的执行上下文中异步发生。 问题 (未决)
• 处理程序注销：一旦唤醒过程完成或 State Management 不再需要进一步的通知，注册的回调就会通过 UnregisterWakeUpHandler 从 OS 包装器中移除 ([SWS_SM_71005], SWS StateManagement §C.1.2.1.1.3 “UnregisterWakeUpHandler”)。

时序图：处理程序注册、状态转发到操作系统以及注销的典型流程。来源：[SWS_SM_71001], [SWS_SM_71003], [SWS_SM_71005]。

错误场景

接口方法 RegisterWakeUpHandler、SetPowerState 和 UnregisterWakeUpHandler 的返回类型为 void，且未定义特定的错误返回码 ([SWS_SM_71001], [SWS_SM_71003], [SWS_SM_71005])。所有函数均声明为 noexcept 并保证完全异常安全 (exception safe)。

错误的系统状态主要可能由违反前置条件引起。这包括由于未受保护的并发方法调用而违反所要求的线程安全性。此外，作为 RegisterWakeUpHandler 的前置条件，State Management 必须确保传入的函数对象有效，并在通过 UnregisterWakeUpHandler 解除之前一直保留在内存中 ([SWS_SM_71003], [SWS_SM_71005])。