classe ara::exec::ExecutionClient

A classe ara::exec::ExecutionClient serve para que processos de aplicação reportem de forma vinculativa seu estado de execução interno ao Execution Management ([SWS_EM_02003]). Durante a inicialização, ela também assume a interceptação do sinal SIGTERM e o encaminha para um handler de terminação personalizado em uma thread em segundo plano ([SWS_EM_02562]). Como um objeto move-only, a instância vincula estritamente o tratamento de sinais ao seu ciclo de vida e restaura o estado de sinal anterior quando destruída. Os chamadores devem garantir que o callback registrado permaneça chamável durante toda a vida útil da instância.

mais ›

Contexto

A classe ara::exec::ExecutionClient é utilizada por processos na Adaptive Platform para reportar seu estado de execução interno ao Execution Management ([SWS_EM_02003]). Ela atua como uma interface padronizada entre a aplicação em execução e o gerenciamento central de processos. Além de encaminhar transições de estado, a instância assume a responsabilidade pelo tratamento do sinal do sistema operacional SIGTERM ([SWS_EM_02562], [SWS_EM_02002]). Ao receber o sinal, ela executa um callback definido pelo usuário em uma thread separada em segundo plano para permitir que a aplicação seja encerrada de forma ordenada ([SWS_EM_02562]). Interpretação: o sistema operacional ou o Execution Management provavelmente transmite o sinal SIGTERM ao processo quando o encerramento da unidade de execução é solicitado. Pergunta Q-51eee947d01ae8b4 (aberta)

Diagrama de contexto: Interação entre processo de aplicação, ExecutionClient, Execution Management e mecanismo de sinal. Fontes: [SWS_EM_02003], [SWS_EM_02562], [SWS_EM_02002].

Ciclo de vida

A instanciação de ara::exec::ExecutionClient ocorre opcionalmente através do método de fábrica estático Create ([SWS_EM_02562]) ou do construtor regular ([SWS_EM_02560]). Enquanto Create é seguro contra exceções (noexcept) e retorna o resultado encapsulado em um ara::core::Result ([SWS_EM_02562]), o construtor regular é declarado como noexcept(false) ([SWS_EM_02560]). Ambos os caminhos de criação esperam como parâmetro um callback std::function<void()> chamável (terminationHandler). Este callback deve permanecer válido e chamável durante toda a vida útil da instância ExecutionClient ([SWS_EM_02562], [SWS_EM_02560]).

Em relação à posse, a classe é concebida como move-only: o construtor de cópia ([SWS_EM_02563]) bem como o operador de atribuição por cópia ([SWS_EM_02564]) são explicitamente excluídos (delete). Uma transferência de instâncias só é possível através do construtor de movimento ([SWS_EM_02580]) e do operador de atribuição por movimento ([SWS_EM_02581]), sendo ambos seguros contra exceções (noexcept), porém não thread-safe. O método de fábrica Create e o próprio construtor são considerados thread-safe ([SWS_EM_02562], [SWS_EM_02560]).

O destrutor ~ExecutionClient() é definido como noexcept ([SWS_EM_02002]) e não é thread-safe. Ao destruir a instância, a responsabilidade pelo sinal SIGTERM é novamente liberada: o destrutor redefine o tratador de sinal para SIGTERM para o estado original que estava ativo antes da instanciação ([SWS_EM_02002]).

Caminho de utilização

O fluxo regular é dividido em inicialização, transmissão de estado e terminação ordenada:

• Criação: No início do tempo de execução do processo, a instância é inicializada via Create, passando-se o handler de terminação ([SWS_EM_02562]). Normalmente, este handler define uma flag ou sinaliza primitivas de sincronização para desbloquear threads em execução.
• Notificação de estado: Assim que o processo estiver pronto, ele reporta seu status de execução via ReportExecutionState ao Execution Management ([SWS_EM_02003]). A chamada é thread-safe e pode ocorrer a partir de diferentes threads de trabalho.
• Recepção de sinal e terminação: Se um sinal SIGTERM chegar durante o tempo de execução, ExecutionClient ativa o terminationHandler registrado de forma assíncrona em uma thread em segundo plano ([SWS_EM_02562]). O processo conclui as tarefas pendentes de forma ordenada.
• Destruição: Ao sair do escopo, o destrutor restaura a configuração de sinal original ([SWS_EM_02002]).

Diagrama de sequência: Fluxo desde a criação e notificação de estado até a terminação controlada por sinal. Fontes: [SWS_EM_02562], [SWS_EM_02003], [SWS_EM_02002].

Cenários de erro

Ao usar ExecutionClient, diferentes situações de erro são cobertas por códigos de erro de ara::exec::ExecErrc:

• ara::exec::ExecErrc::kInvalidArgument: Ocorre durante a instanciação via Create ([SWS_EM_02562]) ou pelo construtor regular ([SWS_EM_02560]), se o objeto terminationHandler passado não contiver uma função chamável. O sistema aplica semântica de rollback; para correção, deve ser passado um callable válido.
• ara::exec::ExecErrc::kNoCommunication: Pode ocorrer tanto na criação ([SWS_EM_02562], [SWS_EM_02560]) quanto em ReportExecutionState ([SWS_EM_02003]), se houver um erro de comunicação entre o processo de aplicação e o Execution Management (por exemplo, ausência de confirmação do recebimento da mensagem). Aqui não se aplica a semântica de rollback; como medida de recuperação, prevê-se uma nova tentativa de chamada.
• ara::exec::ExecErrc::kInvalidTransition: É retornado por ReportExecutionState ([SWS_EM_02003]) se for solicitada uma mudança de estado inválida, por exemplo, uma nova notificação de um estado já ativo como kRunning. Como o estado já foi reportado, nenhuma nova transmissão é necessária (semântica de rollback).