classe apext::sm::PowerStateInterface

A interface atua como um wrapper de OS, coordenando os estados de energia entre o State Management e o sistema operativo ([SWS_SM_71000]). Através dela, o State Management regista previamente manipuladores de retorno de chamada (callbacks) para eventos de despertar e encaminha solicitações de estado concretas para o sistema operativo ([SWS_SM_71001]). Após a reativação bem-sucedida, o registo do manipulador no wrapper de OS pode ser cancelado. Como restrição funcional essencial, todas as chamadas de método não são seguras para threads (thread-safe), devendo, por isso, ser obrigatoriamente serializadas pelo chamador.

mais ›

Contexto

A classe C++ apext::sm::PowerStateInterface funciona como uma interface funcional do módulo State Management para coordenar estados de energia com o sistema operativo ([SWS_SM_71000], SWS StateManagement §C.1.2 «Class: PowerStateInterface»). Na arquitetura do sistema, assume o papel de um wrapper de OS que encaminha solicitações do State Management para o sistema operativo subjacente e recebe respostas. Três componentes centrais participam na interação global: o State Management como entidade coordenadora, a classe PowerStateInterface como intermediária e o sistema operativo anfitrião, que executa a gestão de energia a nível de hardware ([SWS_SM_71001]).

Diagrama de contexto: coordenação de estados de energia e sinais de despertar entre o State Management, o wrapper de OS e o sistema operativo. Fontes: [SWS_SM_71000], [SWS_SM_71001], [SWS_SM_71003].

Ciclo de vida

A criação e destruição de instâncias da classe PowerStateInterface não é regulada nos documentos de especificação através de métodos de fábrica explícitos. Segundo a interpretação, a instanciação deve ser realizada pelo State Management durante a sua fase de inicialização, a fim de disponibilizar o wrapper de OS. Pergunta Q-15bde6ce044e9bc3 (aberta) O cabeçalho apext/sm/power_state_interface.h é previsto para a integração da classe ([SWS_SM_71001], SWS StateManagement §C.1.2.1.1 «Member Functions»).

No que diz respeito ao estado interno, o objeto gere o registo de um manipulador para eventos de despertar. Este estado permanece ativo até que o manipulador seja explicitamente removido ([SWS_SM_71005]). Relativamente à concorrência, todas as funções-membro são classificadas como não seguras para threads (not-threadsafe) ([SWS_SM_71001], [SWS_SM_71003], [SWS_SM_71005]). O State Management chamador deve, portanto, assegurar de forma autónoma que as chamadas para uma instância sejam estritamente serializadas e que não ocorram acessos paralelos desprotegidos a partir de múltiplas threads.

Caminho de utilização

Um fluxo típico de utilização para controlar estados de energia e receber sinais de despertar processa-se em vários passos coordenados entre si:

• Registo do manipulador: antes de iniciar um estado de poupança de energia, o State Management regista uma função de retorno de chamada (callback) do tipo apext::sm::WakeUpHandler no wrapper de OS através de RegisterWakeUpHandler ([SWS_SM_71003], SWS StateManagement §C.1.2.1.1.1 «RegisterWakeUpHandler»). Deste modo, define-se como o State Management é informado sobre procedimentos de despertar subsequentes.
• Solicitação de estado: em seguida, o State Management chama o método SetPowerState com o estado pretendido apext::sm::PowerState ([SWS_SM_71001], SWS StateManagement §C.1.2.1.1.2 «SetPowerState»). A interface encaminha imediatamente esta solicitação para o sistema operativo. A implementação técnica da transição ocorre presumivelmente de forma específica da plataforma no sistema operativo. Pergunta Q-29345b74ba3bedf2 (aberta)
• Notificação de despertar: caso o sistema operativo detete um evento de despertar, a notificação é comunicada ao wrapper de OS. Este executa o WakeUpHandler previamente registado. Segundo a interpretação, a chamada deve ocorrer de forma assíncrona no contexto de execução do procedimento de reativação. Pergunta (aberta)
• Desregisto do manipulador: assim que o processo de despertar estiver concluído ou o State Management já não necessitar de notificações adicionais, o callback registado é removido do wrapper de OS através de UnregisterWakeUpHandler ([SWS_SM_71005], SWS StateManagement §C.1.2.1.1.3 «UnregisterWakeUpHandler»).

Diagrama de sequência: sequência típica de registo de manipulador, encaminhamento de estado para o sistema operativo e desregisto. Fontes: [SWS_SM_71001], [SWS_SM_71003], [SWS_SM_71005].

Cenários de erro

Os métodos de interface RegisterWakeUpHandler, SetPowerState e UnregisterWakeUpHandler possuem o tipo de retorno void e não definem códigos de retorno de erro específicos ([SWS_SM_71001], [SWS_SM_71003], [SWS_SM_71005]). Todas as funções estão declaradas como noexcept e garantem segurança total contra exceções (exception safe).

Estados de sistema com falha podem resultar principalmente de violações de pré-condições. Isto inclui a violação da segurança de threads exigida através de chamadas de método paralelas desprotegidas. Além disso, como pré-condição para RegisterWakeUpHandler, o State Management deve assegurar que o objeto de função transmitido é válido e permanece na memória até ser removido por UnregisterWakeUpHandler ([SWS_SM_71003], [SWS_SM_71005]).