namespace ara::com

A enumeração ComErrc define, de acordo com [SWS_CM_10432], os códigos de erro padronizados de ara::com::ComErrorDomain para erros recuperáveis (Recoverable Errors) conforme EXP ARAComAPI §2 «Recoverable Errors». Ela é transportada em tipos de retorno como ara::core::Result ou ara::core::Future de APIs síncronas e assíncronas do gerenciamento de comunicação para sinalizar com precisão causas de erros funcionais no contexto de cliente ou servidor.

Os enumeradores cobrem casos de erro específicos ao longo do ciclo de vida do serviço e da transmissão de dados:

• Ciclo de vida do serviço e vinculação: kServiceNotOffered indica que um serviço ainda não foi disponibilizado via OfferService() ([SWS_CM_00101]), enquanto kServiceNotAvailable sinaliza a perda intermitente. kInstanceIDNotResolvable ocorre quando um InstanceSpecifier não pode ser resolvido ([SWS_CM_00118]).
• Assinaturas de eventos e amostras: kMaxSamplesExceeded avisa sobre a violação de cotas prometidas de SamplePtr, e kMaxSampleCountNotRealizable relata valores inadequados no recadastramento via [SWS_CM_00141].
• Campos e transmissão: kFieldValueNotInitialized indica a falta de inicialização antes de Update() ([SWS_CM_00119]), kFieldSetHandlerNotSet a falta de um manipulador setter. Problemas de rede local, como no envio de trigger via [SWS_CM_00721], levam a kCommunicationFailure ([SWS_CM_10517]). Além disso, kMinimumSendIntervalViolationError pune violações de taxa de clock e kUnknownApplicationError erros inesperados de servidor ([SWS_CM_10432]).

Como tipo de enumeração puro, ComErrc não possui estado próprio; portanto, operações de leitura e comparação em valores de erro provavelmente são seguras para concorrência na thread chamadora. Pergunta Q-013822ee5711df2b (aberta) A verificação real de erros cabe à aplicação após a avaliação do respectivo objeto de resultado.

A enumeração ara::com::MethodCallProcessingMode define os modos de processamento para chamadas de método recebidas em uma instância de serviço [SWS_CM_00301]. Ela é passada como parâmetro para os construtores das classes skeleton, com o valor padrão ara::com::MethodCallProcessingMode::kEvent predefinido [SWS_CM_00130], [SWS_CM_00152], [SWS_CM_00153].

Os enumeradores controlam a concorrência e o contexto de execução dos métodos de serviço [SWS_CM_00301]:

• kPoll: Modo polling. Chamadas recebidas de consumidores de serviço não são executadas automaticamente. A implementação do serviço controla ativamente sua execução através da chamada de ProcessNextMethodCall() [SWS_CM_00199]. O método pendente é processado de forma síncrona no contexto desta chamada. Isso garante controle total sobre trocas de thread e de contexto no lado do serviço ARAComAPI §6.3.3 «Event Buffering Approaches».
• kEvent: Modo orientado a eventos e concorrente para o processamento paralelo de chamadas recebidas.
• kEventSingleThread: Modo orientado a eventos, sequencial, para a execução individual de chamadas de método.

Tratamento de erros e restrições:

• Se um modo não permitido for passado para um construtor de skeleton, ocorre a violação WrongMethodCallProcessingModeViolation [SWS_CM_00130], [SWS_CM_00153].
• A chamada de ProcessNextMethodCall() em um esqueleto construído com kEvent também resulta em uma WrongMethodCallProcessingModeViolation [SWS_CM_00199] (interpretação: isso provavelmente também se aplica a kEventSingleThread, visto que o método é previsto apenas para kPoll). Pergunta Q-bcd9f07119db44fb (aberta)

A enumeração SubscriptionState [SWS_CM_00310] representa, no namespace ara::com com base no tipo std::uint8_t, o estado atual de uma subscrição. Ela define três estados distintos:

• kNotSubscribed: A subscrição está inativa.
• kSubscriptionPending: A subscrição ainda está pendente ou a conexão está sendo restabelecida após uma falha.
• kSubscribed: A subscrição está ativa.

O método GetSubscriptionState() serve para a consulta síncrona, sendo disponibilizado em eventos de proxy [SWS_CM_00316], campos de proxy [SWS_CM_11604] e triggers [SWS_CM_01105], bem como em triggers de skeleton [SWS_CM_01109]. Todas essas funções de consulta são declaradas como noexcept e garantem total segurança contra exceções.

Para reações assíncronas a mudanças de status, as aplicações podem registrar um callback do tipo SubscriptionStateChangeHandler por meio de SetSubscriptionStateChangeHandler() [SWS_CM_00311] [SWS_CM_00333]. Se for passado um tratador inválido ou vazio, ocorre a violação InvalidHandlerViolation [SWS_CM_00333]. O cancelamento do registro é realizado via UnsetSubscriptionStateChangeHandler() [SWS_CM_00334]. Além disso, é possível definir o contexto de execução para o callback por meio de uma sobrecarga de template com ExecutorT [SWS_CM_11354].

No ciclo de vida de uma instância de proxy, o SubscriptionState está intimamente interligado com a atualização automática: se uma instância de serviço falhar, as chamadas de método falham e GetSubscriptionState() retorna kSubscriptionPending para eventos subscritos anteriormente ARAComAPI §6.1 «Auto Updating of Proxy Instance». Assim que a instância de serviço estiver novamente acessível via Service Discovery, o gerenciamento de comunicação atualiza a conexão de forma transparente; em seguida, GetSubscriptionState() retorna automaticamente kSubscribed AUTOSAR_AP_EXP_ARAComAPI §5.3.5.2. Não é necessária uma recriação manual do proxy ou uma nova subscrição.

O alias de tipo SubscriptionStateChangeHandler no namespace ara::com é declarado como std::function<void(SubscriptionState)> no arquivo de cabeçalho ara/com/types.h ([SWS_CM_00311]). Ele especifica a assinatura de função para callbacks próprios da aplicação que são disparados assim que o ara::com::SubscriptionState de um evento de proxy assinado muda ([SWS_CM_00311], EXP_ARAComAPI §5.3 «Proxy Class API’s»). Na chamada, o novo estado de assinatura é passado diretamente como parâmetro; um valor de retorno não está previsto ([SWS_CM_00311]).

O registro do tratador ocorre através do método SetSubscriptionStateChangeHandler() da respectiva classe de proxy (EXP_ARAComAPI §5.3.1 «Proxy Class API’s», EXP_ARAComAPI §5.3 «Proxy Class API’s»). Esta operação retorna um ara::core::Result<void> (EXP_ARAComAPI §5.3 «Proxy Class API’s»), por meio do qual os desenvolvedores da aplicação podem verificar de forma síncrona possíveis erros no registro. A remoção direcionada do callback registrado ocorre através da chamada de UnsetSubscriptionStateChangeHandler() conforme [SWS_CM_00334] (EXP_ARAComAPI §1 «Introduction», EXP_ARAComAPI §5.3.1 «Proxy Class API’s»).

Em relação ao fluxo e à concorrência, a notificação de estado ocorre de forma assíncrona. A chamada do tratador deve provavelmente ocorrer no contexto de thread da infraestrutura de comunicação (interpretação). Pergunta Q-8dda0cd4de0070bf (aberta) Portanto, a implementação do callback deve retornar rapidamente e ser estruturada de forma reentrante ou segura para threads. A interação do tratador integra-se estreitamente ao ciclo de vida da assinatura de eventos, especialmente em combinação com Subscribe(), Unsubscribe() e GetSubscriptionState() (EXP_ARAComAPI §5.3.1 «Proxy Class API’s»).

usar

A função global GetComErrorDomain no namespace ara::com disponibiliza uma referência ao objeto de domínio de erro ara::com::ComErrorDomain [SWS_CM_11334]. A declaração é incluída por meio do cabeçalho ara/com/com_error_domain.h e ocorre como uma chamada síncrona sem parâmetros SWS CommunicationManagement §8.12.3.1.1 «GetComErrorDomain». Como valor de retorno, a função fornece uma referência constante do tipo const ara::core::ErrorDomain&, que representa o domínio de erro de comunicação no sistema.

Tratamento de erros e segurança de exceções

A interface é declarada explicitamente como noexcept e considerada segura contra exceções (exception safe) [SWS_CM_11334]. Como a chamada de função é sempre bem-sucedida, não ocorrem erros em tempo de execução. Os chamadores, portanto, não precisam prever nenhum tratamento de erro para a própria chamada da função. Códigos de erro específicos, canais de retorno ou notificações para DET ou DEM não são definidos na especificação para essa consulta.

Concorrência e interação

Graças à declaração com constexpr e noexcept, a função deve ser sem estado (stateless), livre de efeitos colaterais, bem como irrestritamente reentrante e thread-safe; provavelmente, ela também pode ser executada em tempo de compilação. O domínio de erro fornecido serve no sistema global como instância de referência para verificar códigos de erro de operações do Communication Management com base em seu domínio de pertencimento e diferenciá-los de outras fontes de erro [SWS_CM_11334]. Pergunta Q-21aafe1fdcb5997b (aberta)

A função auxiliar ara::com::MakeErrorCode serve para a criação de uma instância de ara::core::ErrorCode ([SWS_CM_11335], SWS CommunicationManagement §8.12.3.1.2 «MakeErrorCode»). Ela é declarada através do arquivo de cabeçalho #include "ara/com/com_error_domain.h" no namespace ara::com. Como parâmetros de entrada, ela recebe o número de erro code do tipo ara::com::ComErrc bem como dados adicionais específicos do fabricante data do tipo ara::core::ErrorDomain::SupportDataType, e retorna o respectivo objeto de erro de forma síncrona.

Em relação à segurança de execução, a função é especificada como noexcept e classificada expressamente como segura contra exceções (“exception safe”) ([SWS_CM_11335]). Mensagens em tempo de execução via DET ou DEM não estão previstas para esta função auxiliar, pois ela serve exclusivamente para a construção de objetos de erro. Devido à declaração como constexpr e noexcept, a função deve ser livre de efeitos colaterais e reentrante, tornando as chamadas permitidas inclusive em tempo de compilação e a partir de contextos concorrentes. Pergunta Q-43f118920f402d86 (aberta)

O padrão de arquitetura segue o modelo de erros de toda a plataforma do Adaptive AUTOSAR e é disponibilizado de forma análoga para domínios funcionais adjacentes: para a proteção ponta a ponta existe a função ara::com::e2e::MakeErrorCode ([SWS_CM_12511], SWS CommunicationManagement §8.15.2.1.2 «MakeErrorCode»), enquanto para funções de segurança está disponível apext::com::secoc::MakeErrorCode ([SWS_CM_12522], SWS CommunicationManagement §C.2.2.1.2 «MakeErrorCode»).