classe <SI-Namespace>::proxy::triggers::<Trigger>

usar

A função SetReceiveHandler é chamada no escopo da classe de trigger de um proxy de serviço (<SI-Namespace>::proxy::triggers::<Trigger>) e incluída através do cabeçalho <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h [SWS_CM_00250]. Os triggers formam, ao lado de events, methods e fields, um dos quatro mecanismos de comunicação em ara::com EXP_ARAComAPI §4.2 «Means of Communication».

O parâmetro handler do tipo ara::com::TriggerReceiveHandler recebe um objeto chamável que é invocado pelo Communication Management na chegada de um trigger. O tratador em si não possui parâmetros; para consultar a contagem atual de triggers, deve-se chamar o método GetNewTriggers da classe de trigger específica dentro da função de callback [SWS_CM_00250].

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

O registro não fornece valor de retorno (void) e é definido como noexcept bem como exception safe [SWS_CM_00250]. Uma violação da convenção de chamada na forma de uma InvalidHandlerViolation ocorre se o callable passado não existir ou for null [SWS_CM_00250].

Interação e variantes

Para cenários nos quais o tratador de trigger deve ser processado em um contexto de execução definido, existe a sobrecarga de template com ExecutorT [SWS_CM_00352]. Métodos de registro comparáveis para callbacks também estão disponíveis no nível de proxy para events ([SWS_CM_00181], [SWS_CM_11356]) bem como fields ([SWS_CM_11605], [SWS_CM_11611]) EXP_ARAComAPI §5.3.1 «Proxy Class API’s».

usar

A função template SetSubscriptionStateChangeHandler no escopo <SI-Namespace>::proxy::triggers::<Trigger> registra um callback para notificação sobre alterações do status de assinatura ([SWS_CM_01106]). Ela é declarada por meio do arquivo de cabeçalho <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h e aceita dois parâmetros:

• handler: A entidade chamável do tipo ara::com::SubscriptionStateChangeHandler que deve ser executada mediante uma alteração de status ([SWS_CM_01107]).
• executor: Um contexto de execução do tipo ExecutorT ([SWS_CM_11360]), no qual a execução do manipulador deve ocorrer.

O registro em si comporta-se de forma síncrona e não possui valor de retorno (void). O callback registrado é executado no contexto de execução especificado mediante alterações de status.

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

O método é declarado como noexcept e especificado como exception safe ([SWS_CM_01106]). Se a instância de callable fornecida não existir ou for nula, ocorre uma InvalidHandlerViolation ([SWS_CM_01106]). Uma vez que nenhuma exceção é lançada, um manipulador inválido provavelmente leva a um fluxo de erro específico da plataforma (interpretação). Pergunta Q-cbb90bfbfa10338d (aberta)

Concorrência e interação

Ao passar o executor ([SWS_CM_11360]), a aplicação controla por si mesma o contexto de execução para os callbacks de status. Presume-se que isso impeça que chamadas de manipuladores de longa duração bloqueiem o processamento interno de eventos do gerenciamento de comunicação (interpretação). Pergunta (aberta) A função estende a variante sem contexto [SWS_CM_01107] e constitui a contraparte de trigger para as interfaces baseadas em executor para proxy events ([SWS_CM_11354]), proxy fields ([SWS_CM_11608]) e skeleton triggers ([SWS_CM_11111]).

Com a função [SWS_CM_01107], é registrado na área de proxy de um gatilho (<SI-Namespace>::proxy::triggers::<Trigger>) um manipulador de callback que o Communication Management chama a cada alteração do estado da assinatura (ara::com::SubscriptionState). A função não possui valor de retorno e é especificada como segura contra exceções (noexcept).

Como a assinatura deve ser tratada fundamentalmente como um processo assíncrono, a aplicação só pode assumir uma assinatura bem-sucedida quando o manipulador registrado via [SWS_CM_01107] ou a função de consulta GetSubscriptionState() reportar o estado kSubscribed [SWS_CM_12006]. Em caso de atrasos temporais ou se o servidor estiver temporariamente indisponível devido a uma reinicialização ou problema de rede, o Communication Management ativa o manipulador com o estado kSubscriptionPending [SWS_CM_00313].

Para o tratamento de erros e integração, aplicam-se as seguintes condições de contorno:

• Tratamento de erros: A transmissão de um chamável não existente ou vazio (null) é inadmissível e conduz a uma InvalidHandlerViolation [SWS_CM_01107].
• Contexto de execução: Se o manipulador não deve ser executado no contexto padrão, mas sim dentro de um contexto de execução específico, a sobrecarga de modelo com ExecutorT&& está disponível [SWS_CM_01106].
• Interação: Para eventos de serviço, existe a interface análoga [SWS_CM_00333] no âmbito das APIs gerais de classes de proxy ARAComAPI §5.3.1 «Proxy Class API’s».

A função SetTransportFaultConditionHandler serve para registar uma função de callback do tipo ara::com::e2e::TransportFaultConditionHandler numa instância de proxy::triggers::<Trigger> ([SWS_CM_00106]). Recebe o parâmetro handler, não tem valor de retorno e está especificada como noexcept bem como exception safe ([SWS_CM_00106]).

Através do manipulador registado, a camada de comunicação sinaliza erros detetados da camada de transmissão. No binding de rede DDS, o manipulador comunica eventos da entidade DataReader subjacente como TransportFaultCondition ([SWS_CM_00212]):

• TransportFaultCondition::kSampleRejected em amostras descartadas (por exemplo, devido a escassez de memória ou corrupção de dados),
• TransportFaultCondition::kDeadlineMissed em prazos de receção violados (REQUESTED_DEADLINE_MISSED),
• TransportFaultCondition::kSampleLost na perda de amostras de dados detetadas ([SWS_CM_00212]).

Se, em vez de um invocável válido, for passado um manipulador inexistente ou vazio, o ambiente de tempo de execução comunica uma InvalidHandlerViolation ([SWS_CM_00106]). Uma vez que a assinatura da função está declarada como noexcept, esta infração conduz presumivelmente a um tratamento de erros por parte da plataforma em vez de uma exceção C++. Pergunta Q-ebaf44b8f7b198e8 (aberta)

O registo ocorre de forma síncrona no contexto do chamador; a execução do manipulador nesta sobrecarga não é delegada a um despachante específico. Caso o callback deva ser executado num contexto de execução definido, está disponível a variante de modelo sobrecarregada com ExecutorT&& adicional ([SWS_CM_00107]). A associação deverá ocorrer tipicamente antes do processamento propriamente dito do trigger, para capturar erros desde o início. Pergunta (aberta)

Existem possibilidades de registo correspondentes para TransportFaultConditionHandler de forma semelhante para eventos de proxy ([SWS_CM_00099]), campos de proxy ([SWS_CM_00109]), bem como métodos skeleton ([SWS_CM_00093]) e campos skeleton ([SWS_CM_00096]).

A função [SWS_CM_00107] serve para o registro de uma rotina de callback para erros de transporte de um trigger de proxy no namespace <SI-Namespace>::proxy::triggers::<Trigger>. Como sobrecarga com contexto de execução, ela aceita, além do tratador do tipo ara::com::e2e::TransportFaultConditionHandler, um objeto executor executor, no qual os cálculos assíncronos disparados são executados.

Para a utilização e o tratamento de erros aplicam-se as seguintes definições:

• Parâmetros e valor de retorno: O parâmetro handler passa o callable a ser definido, enquanto executor define o contexto de execução para tarefas assíncronas [SWS_CM_00107]. A função não retorna nenhum valor e é declarada como noexcept (segurança contra exceções: exception safe).
• Casos de erro e violações: Se for passado um tratador inexistente ou inválido (null), o runtime relata uma InvalidHandlerViolation [SWS_CM_00107].
• Estados de erro relatados: O tratador registrado recebe erros de transporte detectados conforme [SWS_CM_00212]. Entre eles incluem-se TransportFaultCondition::kSampleRejected (por exemplo, em caso de corrupção de dados ou falta de recursos), TransportFaultCondition::kDeadlineMissed (em prazos violados), bem como TransportFaultCondition::kSampleLost (em amostras perdidas).

Em comparação com a função básica sem executor [SWS_CM_00106], esta variante permite o controle direcionado do contexto de concorrência para o processamento de erros do trigger. Sobrecargas análogas com contexto de execução existem no gerenciamento de comunicação para eventos de proxy [SWS_CM_00100], campos de proxy [SWS_CM_00110], bem como no nível do skeleton para métodos [SWS_CM_00094] e campos [SWS_CM_00097].

O método Subscribe serve para subscrever, do lado do cliente, um trigger de serviço por meio de uma instância de proxy no namespace <SI-Namespace>::proxy::triggers::<Trigger> [SWS_CM_00723]. Antes do uso, a instância de serviço deve ter sido disponibilizada no lado do servidor via OfferService() e encontrada pelo cliente por meio de mecanismos de Service Discovery AUTOSAR_AP_EXP_ARAComAPI §4.2 «Means of Communication».

Em comparação com subscrições de eventos ([SWS_CM_00141]) e de campos ([SWS_CM_11601]), Subscribe apresenta propriedades específicas para triggers:

• Parâmetros e cache: A função não recebe parâmetros (void Subscribe() noexcept) [SWS_CM_00723]. Como os triggers transmitem notificações puras sem amostras de dados, não é necessária a reserva de um cache local de amostras via maxSampleCount [SWS_CM_00141], habitual em eventos.
• Valor de retorno: Não é retornado nenhum ara::core::Result, mas sim void [SWS_CM_00723].
• Assincronismo: A chamada inicia a subscrição; o estabelecimento efetivo da conexão com a instância de serviço deve ocorrer, de forma análoga às subscrições de eventos, de modo assíncrono no Communication Management AUTOSAR_AP_EXP_ARAComAPI §5.3.5.2 «Monitoring Event Subscription». Pergunta Q-92ae3f442b45f3cc (aberta)

Para o ciclo de vida e o tratamento de erros aplicam-se as seguintes condições:

• Verificação de estado e idempotência: Se o trigger já estiver no estado kSubscribed ou kSubscriptionPending no momento da chamada, o método retorna imediatamente sem ação adicional [SWS_CM_00723].
• Segurança contra exceções: A função é especificada como noexcept e exception safe [SWS_CM_00723].
• Controle de acesso: Em caso de permissões insuficientes, a aplicação de concessões recusa a execução com uma InsufficientPermissionsViolation [SWS_CM_00723].

usar

A função síncrona UnsetReceiveHandler no espaço de nomes <SI-Namespace>::proxy::triggers::<Trigger> serve para desativar o handler de receção previamente registado para um acionador de serviço do lado do proxy [SWS_CM_11614]. A função requer a inclusão do ficheiro de cabeçalho #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h", não aceita parâmetros de passagem e não possui valor de retorno.

Através da chamada, o callback específico da aplicação é cancelado (desregistado). Isto permite à aplicação alternar de forma flexível entre uma receção orientada a eventos e um modelo baseado em interrogação (polling) (AUTOSAR_AP_EXP_ARAComAPI p. 46, AUTOSAR_AP_SWS_CommunicationManagement §7.5.18.1).

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

Ao contrário das funções análogas para eventos de serviço [SWS_CM_00183] e campos de serviço [SWS_CM_11606], que são explicitamente especificadas como noexcept e seguras contra exceções, UnsetReceiveHandler para acionadores é declarada como não segura contra exceções (not exception safe) [SWS_CM_11614]. Interpretação: Os chamadores devem preparar-se para o lançamento de exceções em caso de erros internos da infraestrutura de comunicação, embora tipos de exceção específicos ou códigos de erro não constem da norma. Pergunta Q-92e16243a7ddee35 (aberta)

Interação e bindings

O método é parte integrante das classes de acionadores no espaço de nomes do proxy (AUTOSAR_AP_EXP_ARAComAPI §5.3.1). Em caso de utilização de um binding DDS, a chamada do método é mapeada de acordo com [SWS_CM_11141] através do DataReader associado, segundo as regras estipuladas em [SWS_CM_11026].

A função UnsetSubscriptionStateChangeHandler serve no lado do cliente para remover um callback previamente registrado para alterações de estado da assinatura (ara::com::SubscriptionState) de um trigger [SWS_CM_01108]. Ela é declarada no escopo <SI-Namespace>::proxy::triggers::<Trigger> e deve ser incluída por meio do cabeçalho #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" [SWS_CM_01108].

Utilização e contexto de chamada

O método possui a assinatura void UnsetSubscriptionStateChangeHandler () noexcept;, não recebe parâmetros de entrada e não retorna valor [SWS_CM_01108]. Ele é chamado sincronamente na instância do respectivo trigger de uma classe proxy para cancelar notificações de alterações do status de assinatura AUTOSAR_AP_EXP_ARAComAPI §5.3.1 «Proxy Class API’s». Interpretação: após a execução da chamada, presume-se que nenhuma alteração de status adicional seja entregue ao manipulador anterior. Pergunta Q-d08dc975aacba85c (aberta)

Tratamento de erros e simultaneidade

A interface é declarada como noexcept e especificada explicitamente como segura contra exceções (exception safe) [SWS_CM_01108]. Portanto, uma falha na chamada ou o lançamento de exceções estão excluídos, e não existem valores de retorno de erro.

Interação

A função enquadra-se no esquema unificado das interfaces de proxy. Métodos análogos de cancelamento de registro estão disponíveis no contexto do proxy para events de acordo com [SWS_CM_00334] AUTOSAR_AP_SWS_CommunicationManagement §8.3.2.2.4.5 «UnsetSubscriptionStateChangeHandler», bem como para fields de acordo com [SWS_CM_11609] AUTOSAR_AP_SWS_CommunicationManagement §8.3.3.2.4.5 «UnsetSubscriptionStateChangeHandler». No lado do servidor ou skeleton, existem contrapartes correspondentes para triggers [SWS_CM_01112] e events [SWS_CM_12010].

A função UnsetTransportFaultConditionHandler serve para cancelar novamente o registro de um ara::com::e2e::TransportFaultConditionHandler previamente registrado para um disparador de proxy específico ([SWS_CM_00108], documentado em AUTOSAR_AP_SWS_CommunicationManagement §8.3.7.1.1.3 «UnsetTransportFaultConditionHandler»). Ela está localizada no namespace <SI-Namespace>::proxy::triggers::<Trigger> e deve ser incluída através do arquivo de cabeçalho #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h" ([SWS_CM_00108]).

A assinatura é void UnsetTransportFaultConditionHandler() noexcept;. A chamada não aceita parâmetros e não retorna nenhum valor de retorno ([SWS_CM_00108]). Devido à declaração noexcept e à classificação como exception safe, a função não lança exceções em operação regular ([SWS_CM_00108]). Códigos de erro específicos, canais de erro ou valores de fallback não estão previstos na especificação.

Em relação ao fluxo, a função desfaz a associação com a rotina de tratamento de erros de forma síncrona; consequentemente, após a execução bem-sucedida, nenhuma notificação adicional sobre erros de transporte de E2E para o disparador afetado deverá ser entregue ao handler anterior (interpretação). Pergunta Q-ae8477bc6530e352 (aberta)

No âmbito do sistema geral, o elemento forma a contrapartida para funções análogas de cancelamento de registro para outros padrões de comunicação em AUTOSAR_AP_SWS_CommunicationManagement §8.3/8.4:

• Eventos de proxy: UnsetTransportFaultConditionHandler no nível de eventos ([SWS_CM_00105]).
• Campos de proxy: cancelamento de registro para notificadores de campo ([SWS_CM_00126]).
• Nível do skeleton: cancelamento de registro para Get/Set de campo ([SWS_CM_00098]), bem como para todos os métodos de um skeleton ([SWS_CM_00095]).