classe ara::exec::StateClient

A interface ara::exec::StateClient permite ao State Management solicitar transições de estado para grupos de funções junto ao Execution Management a fim de controlar a execução de processos atribuídos em uma Machine [SWS_EM_02278]. Na criação via Create(), deve ser registrado um callback com validade ininterrupta para estados indefinidos inesperados [SWS_EM_02276]. Além de transições de estado assíncronas, a classe não copiável oferece métodos para consultar o resultado de inicialização da Machine, bem como para análise de falhas em erros de execução [SWS_EM_02279], [SWS_EM_02542].

mais ›

Contexto

A classe ara::exec::StateClient constitui a interface do Execution Management por meio da qual o State Management solicita e controla transições de estado para grupos de funções (Function Groups). O State Management utiliza este cliente durante todo o tempo de operação de uma Machine para iniciar ou encerrar processos de maneira direcionada. O integrador atribui componentes de software a determinados estados de um grupo de funções. Caso o State Management deseje executar esse software, ele solicita ao Execution Management, por meio do StateClient, a transição para o estado do grupo de funções em questão; a parada ocorre de modo análogo, mediante a transição para um estado no qual o software não deve estar ativo [SWS_EM_02278].

Diagrama de contexto: interação entre State Management, StateClient e Execution Management. Fontes: [SWS_EM_02276], [SWS_EM_02278]

Ciclo de vida

Instâncias de StateClient podem ser criadas tanto pelo construtor nomeado Create() [SWS_EM_02276] como ara::core::Result<StateClient> quanto pelo construtor regular StateClient() [SWS_EM_02561]. Ambos os caminhos de construção exigem obrigatoriamente um parâmetro de callback undefinedStateCallback do tipo std::function<void(const ara::exec::ExecutionErrorEvent&)>. Esse callback é acionado pela biblioteca StateClient quando um grupo de funções transita para um estado indefinido de forma inesperada e sem solicitação prévia por SetState(). O chamador deve assegurar que esse callback permaneça invocável durante toda a vida útil da instância de StateClient, o que é relevante em especial nas vinculações de objetos via std::bind [SWS_EM_02276], [SWS_EM_02561].

Operações de cópia são explicitamente proibidas para StateClient: tanto o construtor de cópia [SWS_EM_02565] quanto o operador de atribuição por cópia [SWS_EM_02568] foram excluídos (=delete). A transferência da titularidade só é possível por meio da semântica de movimentação via construtor de movimentação [SWS_EM_02566] e atribuição por movimentação [SWS_EM_02567]. No tocante à concorrência, os métodos funcionais como SetState(), GetExecutionError() e GetInitialMachineStateTransitionResult(), bem como a criação, são projetados como thread-safe [SWS_EM_02276], [SWS_EM_02278], [SWS_EM_02279], [SWS_EM_02542]. Em contrapartida, as operações de movimentação e o destrutor ~StateClient() não são thread-safe [SWS_EM_02277], [SWS_EM_02566], [SWS_EM_02567].

Caminho de utilização

Um ciclo típico de aplicação divide-se em inicialização, consulta do resultado da subida (inicialização), transições regulares de estado e monitoramento de erros:

1. Criação: o State Management instancia StateClient indicando um callback válido de sinalização de erros via Create() [SWS_EM_02276].
2. Consultar o resultado de inicialização inicial: com GetInitialMachineStateTransitionResult(), o State Management solicita o resultado da transição de estado inicial para o estado Startup [SWS_EM_02279]. Como essa transição ocorre exatamente uma vez por ciclo de vida da Machine, o ara::core::Future<void> fornecido permanece estável e não se altera mais até uma reinicialização.
3. Solicitar mudança de estado: por meio de SetState(), o State Management solicita transições de estado assíncronas para Function Groups individuais [SWS_EM_02278]. O método retorna imediatamente e fornece um ara::core::Future<void> para consultar a conclusão. Assim que a solicitação é recebida pelo Execution Management, ela é executada independentemente do tempo de vida restante da instância chamadora.
4. Investigar estados de erro: se um Function Group entrar inesperadamente em um estado indefinido, o erro de execução causador poderá ser determinado na forma de um ara::exec::ExecutionErrorEvent por meio de GetExecutionError() [SWS_EM_02542].

Diagrama de sequência: fluxo de criação, consulta de estado inicial, mudança assíncrona de estado e análise de erros. Fontes: [SWS_EM_02276], [SWS_EM_02279], [SWS_EM_02278], [SWS_EM_02542]

Cenários de erro

As operações da classe comunicam falhas por meio de códigos de erro de ExecErrorDomain:

• ExecErrc::kNoCommunication: sinaliza falhas de comunicação com o Execution Management, por exemplo, no caso de uma conexão IPC interrompida. Ocorre em Create() [SWS_EM_02276], SetState() [SWS_EM_02278], GetInitialMachineStateTransitionResult() [SWS_EM_02279] bem como GetExecutionError() [SWS_EM_02542]. A recuperação prevista consiste na repetição da chamada.
• ExecErrc::kInvalidArgument: é reportado por Create() e StateClient() se o callback fornecido não contiver uma função chamável [SWS_EM_02276], [SWS_EM_02561].
• ExecErrc::kOperationCanceled: indica em SetState() que uma transição em andamento foi cancelada por uma solicitação mais recente [SWS_EM_02278]. Em GetInitialMachineStateTransitionResult(), esse erro ocorre se a transição inicial de inicialização tiver sido cancelada, por exemplo, devido a uma sequência interrompida de atualização de Machine [SWS_EM_02279].
• ExecErrc::kInvalidTransition: a transição de estado solicitada é inválida, por exemplo, a transição para o estado Off para MachineFG, ou o estado não existe mais após uma atualização [SWS_EM_02278].
• ExecErrc::kInvalidMetaModelIdentifier: o estado fornecido não existe no manifesto processado ou o processo não possui mapeamento para o respectivo Function Group [SWS_EM_02278], [SWS_EM_02542]. Se esse erro ocorrer em GetInitialMachineStateTransitionResult(), falta ao processo o mapeamento para MachineFG, o que indica um problema de configuração [SWS_EM_02279].
• ExecErrc::kOperationFailed: a transição falhou [SWS_EM_02278]. Em GetExecutionError(), o código indica que o Function Group não se encontra em um estado indefinido e o problema presumivelmente já foi resolvido [SWS_EM_02542].
• ExecErrc::kIntegrityOrAuthenticityCheckFailed e ExecErrc::kUnexpectedTermination: falhas específicas durante SetState() devido a verificações de integridade com falha ou encerramentos inesperados de processos durante a transição [SWS_EM_02278].