classe <SI-Namespace>::skeleton::fields::<Field>

usar

O método RegisterGetHandler é chamado no lado do servidor no objeto de campo de um skeleton ([SWS_CM_00114]). Ele existe no código gerado exclusivamente se um getter tiver sido configurado na descrição da interface para o campo em questão (Field.hasGetter == TRUE) (EXP ARAComAPI §5.4.8.1 «Registering Getters»). É passado um callback handler do tipo std::function<ara::core::Future<FieldType>()>, o qual é chamado pela implementação de binding mediante uma solicitação Get() recebida de um proxy.

O registro de tal handler é totalmente opcional (EXP ARAComAPI §5.4.8.1 «Registering Getters»). Usualmente, a implementação do serviço não necessita de um handler de getter, uma vez que o Communication Management armazena em cache o valor definido mais recentemente via Update() e responde autonomamente a solicitações do proxy. Um handler é útil principalmente se a determinação do valor do campo for demorada ou computacionalmente intensiva e, portanto, deva ocorrer apenas sob demanda real de forma assíncrona através do padrão promise/future.

Tratamento de erros e condições de contorno

A função não possui valor de retorno, está declarada como noexcept e é segura contra exceções (exception safe) ([SWS_CM_00114]). Se o chamável passado não existir ou for null, ocorre o erro InvalidHandlerViolation ([SWS_CM_00114]).

Interação

Ao contrário de RegisterSetHandler, cuja chamada é obrigatória havendo um setter configurado (EXP ARAComAPI §5.4.8.2 «Registering Setters»), RegisterGetHandler permanece puramente opcional. Caso o handler deva ser processado de forma assíncrona em um contexto de execução específico, está disponível adicionalmente a função de template sobrecarregada com ExecutorT ([SWS_CM_11360]).

usar

O método RegisterGetHandler no namespace <SI-Namespace>::skeleton::fields::<Field> registra um callback do lado da aplicação (handler), que é chamado pelo binding de comunicação mediante uma chamada Get() de entrada de um proxy ([SWS_CM_11360], EXP ARAComAPI §5.4.8.1 «Registering Getters»). Diferente da sobrecarga básica sem parâmetros [SWS_CM_00114], o método recebe um contexto de execução executor do tipo ExecutorT, no qual a execução do callback ocorre de forma assíncrona ([SWS_CM_11360]). Como executor, pode ser utilizado o ara::core::Executor padronizado ou um tipo específico do usuário com a mesma interface ([SWS_CM_11360]).

O manipulador registrado retorna um ara::core::Future<FieldType>, desacoplando o cálculo do valor do campo através do padrão Promise/Future ([SWS_CM_11360], EXP ARAComAPI §5.4.8.1 «Registering Getters»). O registro é totalmente opcional: caso nenhum manipulador esteja registrado, o Communication Management responde às requisições de forma autônoma com o último valor definido via Update() (EXP ARAComAPI §5.4.8.1 «Registering Getters»). Um manipulador getter é adequado primariamente para a determinação sob demanda de valores de campos complexos ou demorados (EXP ARAComAPI §5.4.8.1 «Registering Getters»).

Restrições e tratamento de erros

O método existe no skeleton exclusivamente quando um getter foi configurado na IDL para o campo (Field.hasGetter == TRUE, [SWS_CM_00114], EXP ARAComAPI §5.4.8.1 «Registering Getters»). RegisterGetHandler é declarado como noexcept; no entanto, se um callable inválido ou vazio for passado, ocorre um InvalidHandlerViolation ([SWS_CM_11360]). Interpretação: o executor fornecido provavelmente deve permanecer válido durante todo o período de uso do manipulador, já que requisições recebidas são encaminhadas de forma assíncrona em seu contexto. Pergunta Q-c58eb22b06a8c27c (aberta)

usar

O método RegisterSetHandler serve, no lado do servidor (skeleton), para registrar uma função de callback que é chamada na chegada de uma requisição Set() de um cliente para um campo [SWS_CM_00116]. O método existe exclusivamente quando o campo oferecido está configurado com suporte a setter (Field.hasSetter == TRUE) [SWS_CM_00116]. Em contraste com o registro de getter, a chamada de RegisterSetHandler é obrigatória, uma vez que a implementação do servidor deve validar previamente valores de campos novos ou atualizados de clientes anônimos EXP ARAComAPI §5.4.8.2 «Registering Setters».

O tratador registrado recebe o novo valor como argumento e retorna um ara::core::Future<FieldType> com o valor efetivo, eventualmente corrigido [SWS_CM_00116], EXP ARAComAPI §5.4.8.2 «Registering Setters». Este valor efetivo é adotado implicitamente pelo gerenciamento de comunicação e publicado para os clientes; uma chamada explícita de Update() dentro do tratador é, portanto, desnecessária EXP ARAComAPI §5.4.8.2 «Registering Setters».

Tratamento de erros e condições de contorno

A função é definida como noexcept e é segura contra exceções [SWS_CM_00116]. Se for passado um callable inexistente ou inválido (nulo), ocorre uma violação de especificação na forma de uma InvalidHandlerViolation [SWS_CM_00116]. Interpretação: O registro deve ter que ocorrer antes da disponibilização do serviço via OfferService(), para que seja possível receber requisições de clientes desde o início. Pergunta Q-d45be0a899ddb6dd (aberta)

Interação

Além do método básico, existe uma sobrecarga de template [SWS_CM_11362], com a qual a execução do tratador pode ser vinculada a um contexto de execução específico (ExecutorT conforme [SWS_CM_11360]) EXP ARAComAPI.

A função de template RegisterSetHandler registra, no nível do servidor ou do skeleton de um campo, uma função de callback que é chamada assim que um cliente transmite uma requisição Set() ([SWS_CM_11362], [SWS_CM_00116]). A interface só existe se o campo de serviço configurado previr suporte a setter (Field.hasSetter == TRUE) ([SWS_CM_00116]). Ao contrário do registro de Get, o registro de um tratador Set é obrigatório, pois a implementação do servidor deve sempre validar novos valores de campos provenientes de clientes anônimos (EXP ARAComAPI §5.4.8.2 «Registering Setters»).

Em comparação com o registro padrão de acordo com [SWS_CM_00116], esta sobrecarga recebe adicionalmente um contexto de execução executor do tipo ExecutorT&& ([SWS_CM_11362], [SWS_CM_11360]). Interpretação: Presume-se que o executor controle em qual contexto de thread ou de escalonador de tarefas o callback é executado. Pergunta Q-6dec4c0005c388dd (aberta) O tratador fornecido possui a assinatura std::function<ara::core::Future<FieldType>(<SFieldDerivedType> value)>; ele recebe o valor definido pelo cliente e retorna de forma assíncrona, via ara::core::Future, o valor efetivo – opcionalmente validado ou corrigido – ([SWS_CM_11362], EXP ARAComAPI §5.4.8.2 «Registering Setters»).

O Communication Management assume o valor efetivo retornado pelo tratador implicitamente como se a própria aplicação de servidor tivesse chamado Update(); uma chamada manual de Update() dentro do tratador é, portanto, supérflua (EXP ARAComAPI §5.4.8.2 «Registering Setters», EXP ARAComAPI §4.6 «Data Type Abstractions»).

Tratamento de erros e concorrência:

• Segurança contra exceções: A função é declarada como noexcept e especificada como segura contra exceções (exception safe) ([SWS_CM_11362]).
• Violações: Se o chamável setHandler fornecido não existir ou for nullptr, ocorre a violação InvalidHandlerViolation ([SWS_CM_11362]).
• Contexto: O método assegura que a execução do tratador ocorra no contexto fornecido do executor ([SWS_CM_11362]).

A função SetTransportFaultConditionHandler serve para o registro de um tratador de erros do tipo ara::com::e2e::TransportFaultConditionHandler para solicitações Get e Set de um campo no nível do skeleton no namespace <SI-Namespace>::skeleton::fields::<Field> [SWS_CM_00096]. A chamada é executada de forma síncrona, não possui valor de retorno (void) e garante segurança contra exceções através da especificação como noexcept [SWS_CM_00096]. Para cenários em que a execução do handler deve ser delegada para um contexto de execução explícito, está disponível a sobrecarga de template com um objeto executor ExecutorT&& executor [SWS_CM_00097].

Como condição de erro, está definida a violação InvalidHandlerViolation; ela ocorre quando o chamável handler passado não existe ou é nulo [SWS_CM_00096]. Enquanto, no lado do cliente, erros em solicitações de métodos e campos são reportados através de ComErrc::kCommunicationFailure nas respectivas instâncias de ara::core::Future [SWS_CM_00090], esta função permite que a instância do servidor receba erros de transporte em chamadas Get e Set recebidas [SWS_CM_00096].

O conceito corresponde aos mecanismos de registro correspondentes para todos os métodos de uma instância de serviço do skeleton [SWS_CM_00093], bem como a handlers do lado do proxy para eventos [SWS_CM_00099], disparadores [SWS_CM_00106] e notificadores de campo [SWS_CM_00109]. Interpretação: o registro do handler deve sensatamente ocorrer durante a fase de inicialização antes da disponibilização do skeleton, a fim de permitir a captura transparente de erros em acessos iniciais a campos. Pergunta Q-627229896b666532 (aberta)

A função SetTransportFaultConditionHandler no namespace <SI-Namespace>::skeleton::fields::<Field> registra um manipulador de erros para falhas de transporte em requisições Get e Set de um campo no nível de Skeleton [SWS_CM_00097]. Ela é incluída através do cabeçalho <SiNamespaceDerivedDirectoryPath>/<SiShortname>_skeleton.h [SWS_CM_00097].

Utilização e parâmetros

A chamada ocorre de forma síncrona e não possui valor de retorno (void) [SWS_CM_00097]. Como parâmetros são passados o callback de erro invocável handler do tipo ara::com::e2e::TransportFaultConditionHandler, bem como uma referência de encaminhamento executor do tipo genérico ExecutorT&& [SWS_CM_00097]. O parâmetro executor designa o objeto de execução em cujo contexto eventuais computações assíncronas são executadas [SWS_CM_00097].

Tratamento de erros e simultaneidade

O método está declarado como noexcept e garante segurança completa contra exceções (exception safe) [SWS_CM_00097]. Se o invocável handler passado não existir ou for null, é lançado um InvalidHandlerViolation [SWS_CM_00097]. Interpretação: através do objeto executor passado, presumivelmente é determinado em qual contexto de thread ou de tarefa a notificação assíncrona em caso de erros de transporte será processada. Pergunta Q-4101faaa8d6a3130 (aberta)

Interação

O método estende o registro padrão [SWS_CM_00096] com um contexto de execução dedicado para campos de Skeleton [SWS_CM_00097]. Sobrecargas correspondentes com executor também existem para métodos de Skeleton ([SWS_CM_00094]), bem como no lado do cliente ou de proxy para eventos ([SWS_CM_00100]) e notificadores de campo ([SWS_CM_00110]).

A função UnsetTransportFaultConditionHandler serve, no lado do skeleton de uma interface de serviço, para cancelar um ara::com::e2e::TransportFaultConditionHandler previamente registrado para requisições Get e Set de um campo ([SWS_CM_00098]). Ela é definida no namespace <SI-Namespace>::skeleton::fields::<Field> e incluída através do cabeçalho <SiNamespaceDerivedDirectoryPath>/<SiShortname>_skeleton.h (AUTOSAR_AP_SWS_CommunicationManagement §8.4.3.2.1.3 «UnsetTransportFaultConditionHandler»). A chamada ocorre de forma síncrona, não aceita parâmetros de passagem e não fornece valor de retorno (void).

Com o cancelamento, o callback específico da aplicação para estados de erro de transporte em requisições de campo é desativado (AUTOSAR_AP_SWS_CommunicationManagement §7.4.1 «End-to-end communication protection for SOMEIP»). A interface é declarada como noexcept e garante segurança contra exceções (exception safe) ([SWS_CM_00098]). Códigos de erro ou mensagens de erro específicas através de DET ou DEM não são especificados; a operação é projetada para ser concluída sem erros.

Em relação à concorrência e reentrância, a especificação não contém requisitos separados. Consequentemente, o cancelamento de registro deve ocorrer preferencialmente durante fases de desinicialização ou fora de processamentos Get/Set concorrentes, a fim de evitar inconsistências em processos de comunicação em andamento. Pergunta Q-06bc8d90f1891904 (aberta)

A operação faz parte da proteção de comunicação ponta a ponta para instâncias de serviço (AUTOSAR_AP_SWS_CommunicationManagement §7.4.1 «End-to-end communication protection for SOMEIP»). Ela forma a contrapartida relacionada a campos para [SWS_CM_00095], que cancela o registro do tratador para todos os métodos de um skeleton. No lado do proxy, ela corresponde a cancelamentos de registro equivalentes para eventos ([SWS_CM_00105]), triggers ([SWS_CM_00108]) e notifiers de campos ([SWS_CM_00126]).

O método Update() é chamado no lado do servidor no escopo <SI-Namespace>::skeleton::fields::<Field> para atualizar o valor interno de um campo e iniciar a transmissão dos novos dados para clientes inscritos ([SWS_CM_00119], AUTOSAR_AP_EXP_ARAComAPI §4.6 «Data Type Abstractions»). Uma notificação é enviada aos inscritos se hasNotifier == TRUE estiver configurado para o campo ([SWS_CM_00119], [SWS_CM_00120], [SWS_CM_00162]). O parâmetro value é passado por referência; durante a chamada, a implementação de binding cria uma cópia tipicamente serializada, de modo que os dados da aplicação possam ser modificados ou liberados no lado do chamador após o retorno (AUTOSAR_EXP_ARAComAPI «UpdateRate Class»).

A função está definida como noexcept bem como exception safe e retorna sincronicamente um ara::core::Result<void> ([SWS_CM_00119]). Se ocorrer um erro, o resultado contém um código de erro de ara::com::ComErrc ([SWS_CM_00119], [SWS_CM_10432]). Concretamente, ComErrc::kMinimumSendIntervalViolationError é retornado com semântica de rollback caso as solicitações de envio ocorram mais rapidamente do que o estipulado pelo intervalo mínimo de envio configurado ServiceInterfaceDeploymentElement.minimumSendInterval ([SWS_CM_00119]).

No ciclo de vida do serviço, é necessária uma chamada inicial de Update() antes de oferecer o serviço: se OfferService() for chamado antes de o valor do campo ter sido inicializado, a disponibilização falha com ComErrc::kFieldValueNotInitialized ([SWS_CM_00101], [SWS_CM_00128]). Na ausência de uma garantia explícita de reentrância no padrão, chamadas simultâneas na mesma instância de campo deverão ser sincronizadas no lado da aplicação. Pergunta Q-67b174ef05867989 (aberta)