classe <SI-Namespace>::proxy::<SI>Proxy

Utilização e semântica

O método de fábrica estático Create serve, conforme [SWS_CM_10438], para a criação livre de exceções de uma instância de proxy (<SI>Proxy) de acordo com a convenção de named constructor. Ele requer como parâmetro handle um handle de serviço previamente determinado de acordo com [SWS_CM_00131]. A chamada ocorre de forma síncrona e é declarada como noexcept. O resultado é retornado em um ara::core::Result, que em caso de sucesso contém a instância de proxy operacional.

Tratamento de erros

Se ocorrer um erro durante a instanciação, Create fornece através do ara::core::Result um código de erro do tipo ara::com::ComErrc [SWS_CM_10438]:

• ComErrc::kServiceNotAvailable: O serviço não está mais disponível após ter sido oferecido anteriormente via OfferService().
• ComErrc::kCommunicationFailure: O binding de rede relata um erro de comunicação recuperável ou a falha de uma conexão segura.

Ambos os erros apresentam uma semântica de rollback [SWS_CM_10438]. Em caso de erros estruturais ou relacionados à segurança, aplicam-se violações especificadas (Violations): se o handle fornecido for nulo ou estiver corrompido, ocorre uma ErroneousServiceHandleViolation. Se faltarem ao processo chamador as permissões necessárias para a instância no âmbito do Grant Enforcement, a requisição é rejeitada e tratada como InsufficientPermissionsViolation (SWS CommunicationManagement §8 «Security», [SWS_CM_10438]).

Simultaneidade e condições marginais

Interpretação: Como Create opera de forma síncrona e vincula recursos de comunicação, a chamada deve ser reentrante para handles diferentes, mas não deve ser executada em loops hard real-time de tempo crítico devido a possíveis inicializações de rede. Pergunta Q-f7ba23670f562788 (aberta)

O método estático FindService da classe de proxy serve para a localização síncrona de instâncias de serviço disponíveis com base num ara::com::InstanceIdentifier ([SWS_CM_00122]). A chamada devolve o resultado imediatamente como ara::core::Result, o qual contém um ara::com::ServiceHandleContainer em caso de execução bem-sucedida ([SWS_CM_00122]). Este contentor — tipicamente implementado como ara::core::Vector ([SWS_CM_00304]) — pode estar vazio, conter um único handle de instância ou múltiplos handles, dependendo do estado atual de disponibilização (ARAComAPI §6.5 «Service Discovery»).

Em caso de erro, o ara::core::Result devolve um código de erro de ara::com::ComErrc, nominalmente ComErrc::kCommunicationFailure, se o binding de rede comunicar um erro de transmissão recuperável ou um problema na comunicação segura ([SWS_CM_00122]). Além disso, o acesso está sujeito a verificação de permissões; permissões insuficientes resultam numa InsufficientPermissionsViolation ([SWS_CM_00122]).

Relativamente ao fluxo e à concorrência, aplicam-se as seguintes condições:

• Contexto de chamada e sincronicidade: Como a pesquisa é executada imediatamente, apenas são encontradas as instâncias para as quais OfferService() foi previamente chamado no lado do servidor (ARAComAPI §6.5 «Service Discovery»).
• Segurança contra exceções e reentrância: A função está especificada como noexcept e exception-safe ([SWS_CM_00122]). Como o método é estático e não requer estado de objeto mutável, deverá poder ser chamado de forma reentrante e segura para threads. Pergunta Q-3228cc998c4a737e (aberta)
• Processamento posterior: Os handles encontrados servem para a instanciação de objetos de proxy através do construtor Proxy(const HandleType &handle) ([SWS_CM_00131]). Para uma pesquisa baseada em modelo, está alternativamente disponível a sobrecarga com ara::core::InstanceSpecifier ([SWS_CM_00622]).

A função estática FindService da classe de proxy serve, de acordo com [SWS_CM_00622], para a localização síncrona de instâncias de serviço disponíveis com base num ara::core::InstanceSpecifier com retorno imediato («immediately returned request»). O pré-requisito para a localização é que a respetiva instância de skeleton de serviço tenha sido previamente disponibilizada por meio de OfferService() (ARAComAPI p. 103 «Figure 6.5: Service Discovery»).

Valores de retorno e interação

Como resultado, a chamada retorna um ara::core::Result com um ara::com::ServiceHandleContainer em conformidade com [SWS_CM_00622], que por padrão se baseia em ara::core::Vector [SWS_CM_00304]. Este contentor pode estar vazio, conter um único handle ou múltiplas instâncias encontradas (ARAComAPI p. 103 «Figure 6.5: Service Discovery»). Os handles de serviço apurados são seguidamente passados ao construtor para instanciação do objeto de proxy [SWS_CM_00131]. Para uma pesquisa orientada a eventos e assíncrona com notificação, está disponível em alternativa StartFindService [SWS_CM_00623], enquanto para identificadores de instância é utilizada a sobrecarga de [SWS_CM_00122].

Tratamento de erros e condições de contorno

A função está declarada como noexcept e é considerada segura contra exceções («exception safe») de acordo com [SWS_CM_00622]. Em caso de erro, o objeto Result contém o código de erro ComErrc::kCommunicationFailure, por exemplo em caso de anomalias de comunicação do binding de rede [SWS_CM_00622]. Além disso, [SWS_CM_00622] define violações de modelo e de permissões tais como InstanceSpecifierMappingIntegrityViolation, PortInterfaceMappingViolation, ProcessMappingViolation, InstanceSpecifierAlreadyInUseViolation bem como InsufficientPermissionsViolation.

Interpretação: Devido ao retorno síncrono e imediato, o método deverá ser adequado primariamente para fases iniciais de inicialização ou polling direcionado, desde que não seja necessária uma monitorização contínua via callback. Pergunta Q-ea5b242a6fe41d20 (aberta)

usar

O construtor explícito <SI>Proxy instancia a classe proxy de serviço específica de tipo no namespace <SI-Namespace>::proxy [SWS_CM_00131]. No âmbito do padrão proxy-skeleton, este objeto gerado atua no lado do consumidor do serviço como fachada local, que encaminha chamadas de método para a implementação real do serviço ARAComAPI Figure 5.1 «Proxy Skeleton Pattern».

Para a construção, é passada como parâmetro uma referência para um HandleType válido [SWS_CM_00131]. Este identificador deve ter sido obtido previamente por meio de mecanismos de Service Discovery – seja de forma síncrona por meio de FindService() [SWS_CM_00122] ou de forma assíncrona por meio do callback registrado de StartFindService() [SWS_CM_00123].

Tratamento de erros

A construção não é segura contra exceções (not exception safe) [SWS_CM_00131]. Se o serviço referenciado não puder ser alcançado, é disparada uma ara::com::ComException conforme ara::com::ComErrc::kServiceNotAvailable [SWS_CM_00131]. Além disso, estão definidas as seguintes violações:

• ErroneousServiceHandleViolation: ocorre quando o objeto HandleType passado é nulo ou corrompido [SWS_CM_00131].
• InsufficientPermissionsViolation: ocorre quando a criação é negada pela verificação de permissões (Grant Enforcement) [SWS_CM_00131].

Restrições e ciclo de vida

Para a classe proxy, o construtor de cópia está explicitamente excluído (=delete) [SWS_CM_00136]. O repasse da instância é permitido exclusivamente por meio do construtor de movimentação (Move Constructor), que também está especificado como não seguro contra exceções [SWS_CM_00137]. Em tempo de execução, o gerenciamento de comunicação atualiza automaticamente em segundo plano o endereçamento da camada de transporte da instância proxy existente, após criação bem-sucedida, em caso de falha temporária e redisponibilização do serviço de destino ARAComAPI Figure 6.1 «Auto Updating of Proxy Instance».

O destrutor ~<SI>Proxy () encerra o ciclo de vida de uma instância de proxy de serviço e liberta os recursos locais associados [SWS_CM_99444]. Um proxy de serviço serve, do lado do consumidor, como uma fachada local para a interação com uma implementação de serviço potencialmente remota e encaminha chamadas ARAComAPI §5.1 «Proxy Skeleton Pattern». O objeto de proxy é previamente instanciado através de um handle de serviço determinado [SWS_CM_00131], o qual foi disponibilizado por funções de Service Discovery como FindService [SWS_CM_00122].

Para a destruição e o comportamento em tempo de execução aplicam-se as seguintes diretrizes e condições de contorno:

• Ciclo de vida e semântica: a destruição ocorre de forma síncrona ao sair do âmbito de validade ou mediante a eliminação explícita da instância. Embora o construtor de cópia da classe de proxy esteja eliminado [SWS_CM_00136], o objeto pode ser movido através da semântica de movimento antes da sua destruição [SWS_CM_00137].
• Segurança face a exceções: o destrutor está especificado como not exception safe [SWS_CM_99444].
• Pré-condições e comportamento de erro: se a pré-condição [SWS_CM_00087] for violada, tal resulta num DanglingSamplesViolation [SWS_CM_99444]. (Interpretação: antes da chamada do destrutor, presume-se que todas as referências de amostras ou ponteiros de dados detidos pelo consumidor devam ser libertados para evitar referências inválidas.) Pergunta Q-5488797b732d9be6 (aberta)
• Interação: se forem utilizadas pesquisas assíncronas de serviços, estas devem, se necessário, ser terminadas através de StopFindService antes da libertação do contexto de utilização [SWS_CM_00125]. Além disso, os manipuladores de tratamento de erros registados para eventos, triggers e campos podem ser previamente reinicializados [SWS_CM_00105] [SWS_CM_00108] [SWS_CM_00126].

O método estático StartFindService [SWS_CM_00123] da classe Proxy inicia a busca assíncrona por instâncias de serviço com base em um ara::com::InstanceIdentifier sob registro de um callback handler (ARAComAPI §6.5 «Service Discovery»). À chamada são passados um ara::com::FindServiceHandler bem como o ara::com::InstanceIdentifier procurado [SWS_CM_00123].

Em caso de sucesso, a função retorna um ara::core::Result com um ara::com::FindServiceHandle [SWS_CM_00123]. Esse identificador representa a requisição de busca ativa e é estritamente necessário para encerrar novamente o monitoramento da disponibilidade do serviço bem como chamadas subsequentes do handler mais tarde por meio de StopFindService [SWS_CM_00125].

Se ocorrer um problema de comunicação durante o estabelecimento da conexão, o método retorna no ara::core::Result o código de erro ComErrc::kCommunicationFailure [SWS_CM_00123]. Se a instância de callable passada for inválida ou nula, isso é avaliado como InvalidHandlerViolation; permissões de acesso ausentes levam a uma InsufficientPermissionsViolation [SWS_CM_00123].

Assim que uma instância de serviço correspondente se torna disponível no sistema, o gerenciamento de comunicação chama o handler registrado com os respectivos service handles [SWS_CM_00123]. Com base em um HandleType reportado, a aplicação pode criar uma instância de proxy concreta através do método named constructor Create [SWS_CM_10438]. Interpretação: o handler deve ser executado de forma assíncrona em uma thread do gerenciamento de comunicação, razão pela qual o acesso a recursos compartilhados no handler deve ser realizado de forma thread-safe. Pergunta Q-9dc570d7e65fc808 (aberta) Para a busca por meio de um identificador baseado em modelo, StartFindService com InstanceSpecifier está disponível como alternativa [SWS_CM_00623].

O método estático StartFindService da classe de proxy inicia a busca contínua por instâncias de serviço com base em um ara::core::InstanceSpecifier modelado [SWS_CM_00623]. Durante a chamada, são passados o InstanceSpecifier e uma função de callback do tipo ara::com::FindServiceHandler [SWS_CM_00623]. Como valor de retorno, a função fornece um ara::core::Result<ara::com::FindServiceHandle> [SWS_CM_00623], que, em caso de registro bem-sucedido, disponibiliza um manipulador de busca (handle) para o gerenciamento da busca.

O tratamento de erros ocorre por meio do ara::core::Result retornado. Se ocorrer um erro de comunicação recuperável ou um erro de comunicação segura na vinculação de rede, o resultado conterá o código de erro ComErrc::kCommunicationFailure [SWS_CM_00623]. Além disso, violações específicas são especificadas: InvalidHandlerViolation, caso o manipulador fornecido seja inválido ou nulo, InsufficientPermissionsViolation em caso de permissões ausentes por Grant Enforcement, bem como violações de modelagem como InstanceSpecifierMappingIntegrityViolation ou PortInterfaceMappingViolation [SWS_CM_00623].

Em relação à concorrência e condições de contorno, a função é declarada como noexcept e especificada como segura contra exceções [SWS_CM_00623]. Presume-se que a execução do manipulador registrado ocorra de forma assíncrona pelo gerenciamento de comunicação, assim que instâncias de serviço correspondentes forem detectadas no sistema. Pergunta Q-79fb3ff78d517714 (aberta)

Na interação com interfaces relacionadas, aplicam-se os seguintes pontos:

• O ara::com::FindServiceHandle retornado deve ser retido para encerrar a busca em andamento via StopFindService [SWS_CM_00125] e interromper o recebimento de notificações adicionais.
• Os handles (HandleType) fornecidos por meio do callback servem tipicamente para instanciar o objeto proxy via o método fábrica Create [SWS_CM_10438].
• Como alternativa à busca por meio de um InstanceSpecifier, uma busca também pode ser iniciada com um ara::com::InstanceIdentifier [SWS_CM_00123].

O método SetServiceStateChangeHandler serve, numa instância de proxy, para registar uma função de callback para monitorização de alterações de disponibilidade do respetivo serviço ([SWS_CM_01074], SWS CommunicationManagement §8.3.8.2.4.6 «SetServiceStateChangeHandler(ara::com::ServiceStateHandler)»). A gestão de comunicação chama este handler assim que o estado da disponibilidade do serviço (ServiceState) se altera ([SWS_CM_01074]).

Como parâmetro é passado um objeto de função do tipo ara::com::ServiceStateHandler, o qual está especificado como std::function<void(ServiceState)> ([SWS_CM_01072]). A função não possui valor de retorno. Um handler já registado pode ser substituído durante o tempo de execução através de nova chamada ([SWS_CM_01074]).

No que diz respeito ao tratamento de erros, a função está declarada como segura contra exceções (noexcept) ([SWS_CM_01074]). Se o callable passado não existir ou for nulo, verifica-se a violação InvalidHandlerViolation ([SWS_CM_01074]).

Quanto ao ambiente de execução, [SWS_CM_01074] representa a interface base. Como aqui não pode ser passado nenhum executor, o callback deverá presumivelmente ser executado no contexto de thread interno da gestão de comunicação. Caso seja necessária uma execução num contexto de aplicação específico, está disponível em alternativa a variante de template sobrecarregada com um executor de acordo com [SWS_CM_01076] (SWS CommunicationManagement §8.3.8.2.4.5 «SetServiceStateChangeHandler(ara::com::ServiceStateHandler, ExecutorT&&)»). Pergunta Q-7833435e7aa1da9f (aberta)

Utilização e contexto de chamada

O método de template SetServiceStateChangeHandler serve, na classe de proxy gerada <SI-Namespace>::proxy::<SI>Proxy, para o registro de um callback para monitoramento da disponibilidade do serviço [SWS_CM_01076]. A função recebe dois parâmetros AUTOSAR_AP_SWS_CommunicationManagement §8.3.8.2.4.5 «SetServiceStateChangeHandler(ara::com::ServiceStateHandler, ExecutorT&&)»:

• handler: Um functor do tipo ara::com::ServiceStateHandler (definido como std::function<void(ServiceState)>), que é chamado a cada alteração do status de disponibilidade [SWS_CM_01072], [SWS_CM_01074].
• executor: Um contexto de execução do tipo de template ExecutorT conforme [SWS_CM_11360], no qual o tratador registrado é executado [SWS_CM_01076].

A função não possui valor de retorno (void) [SWS_CM_01076].

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

A função é declarada como noexcept e especificada como segura contra exceções (exception safe) [SWS_CM_01076]. Caso o tratador chamável fornecido não exista ou seja null, é disparada uma InvalidHandlerViolation [SWS_CM_01076].

Simultaneidade e restrições

Um tratador registrado pode ser sobrescrito em tempo de execução [SWS_CM_01074]. Como a execução ocorre por meio do objeto executor fornecido [SWS_CM_01076], a notificação provavelmente é processada de forma assíncrona no contexto de thread ou dispatch disponibilizado pelo usuário. Pergunta Q-349c5224c3b9cc20 (aberta)

Interação

O método estende a variante elementar [SWS_CM_01074] com a definição explícita do contexto de execução [SWS_CM_01076]. Para a inclusão é necessário o cabeçalho <SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h, enquanto o tipo do tratador é originário de ara/com/types.h [SWS_CM_01072].

O método de modelo estático StartFindService inicia a monitorização assíncrona em segundo plano para localização de instâncias de um serviço com base num ara::com::InstanceIdentifier ([SWS_CM_11352], EXP_ARAComAPI §5.3.3 «Proxy Class API’s»). Além da instância de destino (instance de acordo com [SWS_CM_00122]), são registados uma função de callback (handler de acordo com [SWS_CM_00123]) bem como um contexto de execução (executor do tipo de modelo ExecutorT de acordo com [SWS_CM_11360]) ([SWS_CM_11352]). As notificações de callback deverão ser processadas no contexto de thread ou tarefa do executor transmitido ([SWS_CM_11352]). Pergunta Q-1db520123c1e49a4 (aberta)

Como valor de retorno, a chamada fornece um ara::com::FindServiceHandle ([SWS_CM_11352]). Este identificador identifica a atividade de pesquisa em curso e é necessário para encerrar explicitamente a atividade em segundo plano mais tarde através de [SWS_CM_00125] (StopFindService) (EXP_ARAComAPI §5.3.3 «Proxy Class API’s»). Os identificadores de serviço (HandleType) obtidos através do callback registado servem posteriormente para a construção das instâncias de proxy associadas ([SWS_CM_00131]).

A função está declarada como noexcept e especificada como segura contra exceções (exception safe) ([SWS_CM_11352]). Estão definidas as seguintes violações em tempo de execução (Violations):

• InvalidHandlerViolation: Ocorre se a função manipuladora transmitida for inválida ou corresponder a null ([SWS_CM_11352]).
• InsufficientPermissionsViolation: Ocorre se o acesso for recusado pelo sistema de autorizações (Grant Enforcement) ([SWS_CM_11352]).

Se, em vez disso, um serviço dever ser pesquisado através de um ara::core::InstanceSpecifier baseado em modelo, está disponível como alternativa a variante da função [SWS_CM_11365].

A função de modelo estática StartFindService inicia a pesquisa contínua e assíncrona de instâncias de serviço com base num ara::core::InstanceSpecifier mediante o registo de um manipulador de notificação num contexto de execução transmitido [SWS_CM_11365]. Ao contrário de pesquisas pontuais síncronas, despoleta uma atividade em segundo plano para monitorização da disponibilidade do serviço e retorna um ara::com::FindServiceHandle EXP_ARAComAPI §5.3 «Proxy Class APIs».

Parâmetros e execução

A função recebe três parâmetros [SWS_CM_11365]:

• handler: Função de callback do tipo ara::com::FindServiceHandler de acordo com [SWS_CM_00123], que é invocada em caso de alterações da disponibilidade da instância.
• instance: O ara::core::InstanceSpecifier a pesquisar de acordo com [SWS_CM_00123].
• executor: Um contexto de execução do tipo de modelo ExecutorT de acordo com [SWS_CM_11360]. Interpretação: o argumento de modelo ExecutorT deverá definir em que contexto de thread ou de tarefas o callback registado é executado. Pergunta Q-6d46f67d536a391e (aberta)

Tratamento de erros e condições de contorno

A assinatura está declarada como noexcept e especificada como exception safe [SWS_CM_11365]. Especificativamente estão definidas violações funcionais (Violations): InstanceSpecifierMappingIntegrityViolation (resolução no contexto do executável falhou ou não é PortPrototype), PortInterfaceMappingViolation e ProcessMappingViolation (mapeamentos de PortInterface não coincidentes), InstanceSpecifierAlreadyInUseViolation, InvalidHandlerViolation (manipulador inválido ou inexistente) bem como InsufficientPermissionsViolation em caso de falta de autorização de acesso [SWS_CM_11365].

Interação

O FindServiceHandle obtido serve para terminar de forma controlada a monitorização contínua em segundo plano mediante a passagem para StopFindService [SWS_CM_00125]. Os identificadores reportados ao manipulador são utilizados para instanciar proxies de serviço concretos por meio de Proxy(handle) [SWS_CM_00131]. Para pesquisas por meio de ara::com::InstanceIdentifier, existe uma sobrecarga alternativa [SWS_CM_11352].

A função estática StopFindService da classe proxy termina uma pesquisa assíncrona de serviço previamente iniciada com StartFindService e interrompe a receção de notificações adicionais para o identificador (handle) [SWS_CM_00125] transmitido. Deste modo, a atividade em segundo plano em curso para monitorização da disponibilidade do serviço é cessada pelo binding técnico AP EXP ARAComAPI §5.3 «Proxy Class API’s».

Utilização e semântica

• Parâmetros: Como parâmetro de entrada, a função espera um ara::com::FindServiceHandle que foi previamente obtido através de um dos métodos StartFindService ([SWS_CM_00123], [SWS_CM_00623], [SWS_CM_11352], [SWS_CM_11365], [SWS_CM_00125]).
• Valor de retorno e segurança contra falhas: A função não fornece qualquer valor de retorno (void), está declarada com noexcept e especificada como segura quanto a exceções [SWS_CM_00125].
• Simultaneidade e contexto de chamada: Uma chamada de StopFindService é expressamente permitida também diretamente dentro da função de callback FindServiceHandler [SWS_CM_00383] definida pelo utilizador AP EXP ARAComAPI §5.3 «Proxy Class API’s». Para este efeito, o respetivo FindServiceHandle é transmitido ao manipulador (handler) como parâmetro [SWS_CM_00383]. Dado que o próprio callback não tem de ser reentrante, a serialização de chamadas sucessivas deve ser assegurada pelo implementador do binding AP EXP ARAComAPI §5.3 «Proxy Class API’s».

A função-membro UnsetServiceStateChangeHandler é parte integrante da classe de proxy gerada no namespace <SI-Namespace>::proxy::<SI>Proxy de acordo com [SWS_CM_01075] (AUTOSAR_AP_SWS_CommunicationManagement §8.3.8.2.4.12 «UnsetServiceStateChangeHandler»). É incluída através do cabeçalho #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_proxy.h".

No que diz respeito à utilização, comportamento e concorrência, aplicam-se as seguintes definições:

• Utilização: o método possui a assinatura void UnsetServiceStateChangeHandler() noexcept;. Não recebe parâmetros e não retorna nenhum valor. Interpretação: de acordo com o identificador e a referência a [SWS_CM_01074], a chamada serve para reinicializar ou cancelar o registo de um manipulador de callback previamente registado para alterações do estado do serviço na instância de proxy. Pergunta Q-6eb71298a6f37ad9 (aberta)
• Tratamento de erros e segurança face a exceções: a operação é declarada como noexcept e especificada como exception safe ([SWS_CM_01075]). Não lança exceções e não reporta códigos de erro ao chamador.
• Interação e condições de contorno: a semântica funcional remete para a definição em [SWS_CM_01074]. Interpretação: o cancelamento do registo deverá produzir efeitos de forma síncrona, de modo que, após o retorno da chamada da função, não sejam entregues mais transições de estado através do callback anterior. Pergunta Q-31348a50d9be537d (aberta)