classe <SI-Namespace>::skeleton::<SI>Skeleton

O método OfferService() é chamado em uma instância da classe skeleton para oferecer um serviço disponibilizado no sistema e torná-lo localizável para consumidores por meio do Service Discovery [SWS_CM_00101], ARAComAPI §6.5 «Service Discovery». A chamada ocorre sem parâmetros e de forma síncrona, assim que a implementação do serviço tiver sido completamente instanciada e colocada em estado operacional AUTOSAR_AP_EXP_ARAComAPI §5.4.4 «Offering Service instance». A função está declarada como noexcept e retorna um ara::core::Result<void> [SWS_CM_00101].

A oferta é um pré-requisito obrigatório para a comunicação funcional por meio de métodos, eventos, campos ou gatilhos AUTOSAR_AP_EXP_ARAComAPI §4.2 «Means of Communication». Se, por exemplo, for tentado enviar um gatilho sem oferta prévia, isso falha com ComErrc::kServiceNotOffered [SWS_CM_00721]. Em relação à concorrência, aplica-se o seguinte: assim que OfferService() é chamado, chamadas de método recebidas já podem ser entregues à instância do serviço – mesmo que a chamada de OfferService() ainda não tenha retornado AUTOSAR_AP_EXP_ARAComAPI §5.4.4 «Offering Service instance».

Se a oferta falhar, o ara::core::Result retornado contém um código de erro correspondente de ComErrc [SWS_CM_00101], [SWS_CM_10432]:

• ComErrc::kFieldValueNotInitialized: pelo menos um valor de campo configurado ainda não havia sido inicializado antes da oferta [SWS_CM_00101].
• ComErrc::kFieldSetHandlerNotSet: para um campo com suporte a setter, ainda não foi registrado nenhum manipulador por meio de RegisterSetHandler() [SWS_CM_00101].
• ComErrc::kCommunicationFailure: a vinculação de rede relata um erro de comunicação recuperável ou a falha da comunicação segura [SWS_CM_00101].

Se a disponibilização do serviço deve ser encerrada, deve-se chamar StopOfferService() AUTOSAR_AP_EXP_ARAComAPI §5.4.4 «Offering Service instance».

O método ProcessNextMethodCall() destina-se a provedores de serviço no skeleton para processar de forma determinística chamadas de método recebidas no modo polling [SWS_CM_00199]. Ele só pode ser utilizado se a instância do skeleton tiver sido configurada com o modo ara::com::MethodCallProcessingMode::kPoll EXP ARAComAPI §2 «Polling».

Utilização e semântica

A função não recebe parâmetros e executa uma requisição pendente de chamada de método de forma síncrona no contexto de thread do chamador [SWS_CM_00199], [SWS_CM_00191]. Isso permite, em especial para aplicações de tempo real, processar requisições de serviço sem trocas descontroladas de contexto de thread dentro de seu orçamento de tempo atribuído EXP ARAComAPI §5.4 «ProcessNextMethodCall». O valor de retorno sinaliza o resultado da consulta:

• true: pelo menos uma requisição pendente encontrava-se na fila e foi processada [SWS_CM_00199].
• false: não havia requisição pendente; a fila estava vazia [SWS_CM_00199]. Uma chamada subsequente direta após um false geralmente permanece sem efeito EXP ARAComAPI §5.4 «ProcessNextMethodCall».

Tratamento de erros e condições de contorno

A função está especificada como noexcept e exception safe [SWS_CM_00199]. Uma chamada em um skeleton instanciado com kEvent ou kEventSingleThread representa uma violação (WrongMethodCallProcessingModeViolation) [SWS_CM_00199]. Interpretação: como exceções regulares do C++ são excluídas por noexcept, tal violação deve provavelmente ser tratada pela plataforma como um erro de tempo de execução grave. Pergunta Q-61661dbd6cc37bc7 (aberta)

usar

A função SetTransportFaultConditionHandler serve para o registro de um callback do tipo ara::com::e2e::TransportFaultConditionHandler no namespace da classe Skeleton (<SI-Namespace>::skeleton::<SI>) [SWS_CM_00093]. Por meio deste manipulador são reportados erros de transporte para todos os métodos da respectiva instância de serviço AUTOSAR_AP_SWS_CommunicationManagement §7.4.1 «End-to-end communication protection for SOMEIP». A função recebe o objeto invocável handler e não possui valor de retorno (void) [SWS_CM_00093].

Tratamento de erros

A operação está declarada com noexcept e é segura contra exceções (exception safe) [SWS_CM_00093]. Caso a unidade invocável passada não exista ou seja null, é lançado um InvalidHandlerViolation [SWS_CM_00093]. Em caso de erro, o manipulador configurado reporta falhas de transporte ocorridas, como por exemplo TransportFaultCondition::kSampleRejected, quando requisições são descartadas por falta de recursos ou corrupção na camada de transporte AUTOSAR_AP_SWS_CommunicationManagement §7.4.2.3 «Methods».

Simultaneidade e restrições

Interpretação: como esta interface básica não recebe nenhum contexto de execução, o callback provavelmente deve ser chamado de forma síncrona a partir da thread interna do gerenciamento de comunicação. Caso a execução do manipulador deva ocorrer em um pool de threads ou worker definido, deve-se utilizar a sobrecarga com ExecutorT&& executor [SWS_CM_00094]. Pergunta Q-e4007fa72de6aa12 (aberta)

Interação

O registro vincula o tratamento de erros de forma centralizada a todos os métodos de uma instância de Skeleton [SWS_CM_00093]. Ele integra-se ao tratamento de erros de nível superior de ara::com:

• Enquanto os métodos de Skeleton reportam erros de transporte através deste manipulador, os métodos de cliente sinalizam falhas de transporte de forma assíncrona através de seu ara::core::Future resultante com ComErrc::kCommunicationFailure [SWS_CM_00090].
• Para operações de campo (Get/Set) no nível de Skeleton existem interfaces separadas [SWS_CM_00096].
• No nível de Proxy estão disponíveis funções de registro análogas para eventos [SWS_CM_00099], gatilhos [SWS_CM_00106] bem como notificadores [SWS_CM_00109].

A função template SetTransportFaultConditionHandler no namespace da classe Skeleton serve para o registro de um handler de erro para erros de transporte de todos os métodos de uma instância de serviço [SWS_CM_00094]. Ela estende a função básica sem parâmetros [SWS_CM_00093] com um contexto de execução:

• Chamada e parâmetros: são passados um callable handler do tipo ara::com::e2e::TransportFaultConditionHandler bem como uma referência universal executor [SWS_CM_00094]. Quaisquer computações assíncronas e execuções de callback devem ser iniciadas nesse objeto executor. A função não possui valor de retorno.
• Tratamento de erros: a interface está declarada como noexcept e especificada como segura contra exceções [SWS_CM_00094]. Se o callable passado não existir ou for nulo, ocorre um InvalidHandlerViolation [SWS_CM_00094].
• Interação: o escopo abrange todos os métodos do skeleton [SWS_CM_00094], enquanto funções de registro separadas estão disponíveis para operações de Get e Set de fields ([SWS_CM_00096], [SWS_CM_00097]). No binding de rede DDS, o handler configurado reporta erros de transporte como TransportFaultCondition::kSampleRejected [SWS_CM_00216]; no lado do cliente, por outro lado, tais erros são sinalizados via ComErrc::kCommunicationFailure nas futures de resultado [SWS_CM_00090].
• Concorrência: Interpretação: a passagem do executor desacopla o tratamento de erros do contexto interno da camada de comunicação; provavelmente, o registro deve ocorrer antecipadamente durante a inicialização do skeleton, antes da chegada das primeiras chamadas de método. Pergunta Q-e56b2a1928cf32ad (aberta)

O construtor [SWS_CM_00130] instancia um skeleton de serviço com base num ara::com::InstanceIdentifier concreto. O skeleton liga a implementação de serviço do lado da aplicação à camada de transporte do Communication Management, para que os consumidores de serviço distribuídos possam aceder-lhe (ARAComAPI §5.1 «Proxy Skeleton Pattern»).

Através do parâmetro mode, define-se como são processadas as chamadas de método recebidas. Como valor predefinido, está estipulado o modo baseado em eventos ara::com::MethodCallProcessingMode::kEvent [SWS_CM_00130]. Se, em vez disso, for selecionado um modo baseado em sondagem (polling), a execução de chamadas de método pendentes ocorre de forma síncrona no contexto de chamada de ProcessNextMethodCall() [SWS_CM_00199].

Tratamento de erros e condições de contorno

A função construtora está declarada com noexcept e não lança exceções C++ [SWS_CM_00130]. Possíveis violações são sinalizadas através do sistema de tempo de execução: se a criação for recusada pela imposição de concessão (grant enforcement), ocorre uma InsufficientPermissionsViolation; no caso de transmissão de um modo de processamento inválido, resulta uma WrongMethodCallProcessingModeViolation [SWS_CM_00130]. Interpretação: a validação do modo de processamento deverá ocorrer diretamente durante a execução do construtor. Pergunta Q-80e02c0079757082 (aberta)

As operações de cópia estão explicitamente eliminadas para o skeleton [SWS_CM_00134], enquanto a construção por movimento (move) é suportada [SWS_CM_00135]. Para que o serviço fique localizável na rede, deve ser chamado OfferService() após a instanciação [SWS_CM_00101] (ARAComAPI §6.5 «Service Discovery»). Antes da destruição da instância [SWS_CM_11370], a disponibilização pode ser novamente terminada mediante StopOfferService() [SWS_CM_00111].

O construtor instancia um skeleton de serviço com base em um identificador de instância [SWS_CM_00152]. Ele serve para vincular uma implementação de serviço concreta à camada de transporte do Communication Management. Como parâmetros são passados um ara::core::InstanceSpecifier e opcionalmente o modo de processamento ara::com::MethodCallProcessingMode, o qual é predefinido como padrão para kEvent [SWS_CM_00152].

Em relação ao tratamento de erros e comportamento de exceções, o construtor é declarado como noexcept e exception safe [SWS_CM_00152]. Em caso de configurações incorretas ou desvios de modelagem, são especificadas as seguintes violations:

• InstanceSpecifierMappingIntegrityViolation, se o identificador não puder ser resolvido no contexto de execução ou não referenciar um PortPrototype [SWS_CM_00152].
• PortInterfaceMappingViolation e ProcessMappingViolation, se o tipo de mapeamento e o tipo de interface não coincidirem [SWS_CM_00152].
• InstanceSpecifierAlreadyInUseViolation, se o InstanceSpecifier já estiver em uso [SWS_CM_00152].
• WrongMethodCallProcessingModeViolation bem como InsufficientPermissionsViolation em caso de permissões insuficientes [SWS_CM_00152].

Interpretação: Como o construtor é declarado como noexcept, as violations especificadas não devem ser propagadas como exceções C++ lançadas em tempo de execução, mas sim interceptadas por verificações da plataforma ou Grant Enforcement. Pergunta Q-f1a1a0baeb56e482 (aberta)

Para ciclo de vida e concorrência, aplica-se que o construtor de cópia foi excluído [SWS_CM_00134], enquanto um construtor de movimento está disponível [SWS_CM_00135]. A liberação ocorre através do destrutor virtual [SWS_CM_11370]. Após a construção bem-sucedida, o serviço é tipicamente oferecido na rede via [SWS_CM_00101] (OfferService). Se o modo de processamento kPoll tiver sido selecionado, a aplicação deve processar explicitamente as chamadas recebidas dos métodos de serviço [SWS_CM_00191] via [SWS_CM_00199] (ProcessNextMethodCall).

usar

O construtor instancia um skeleton de serviço com base em um contêiner de identificadores de instância (instanceIDs) e conecta a implementação do serviço no lado do servidor com a camada de transporte do Communication Management [SWS_CM_00153], ARAComAPI §5.1 «Proxy Skeleton Pattern». Através do parâmetro mode, define-se como chamadas de métodos recebidas são processadas; por padrão, o processamento ocorre orientado a eventos através de kEvent [SWS_CM_00153]. Alternativamente, estão disponíveis construtores para identificadores de instância individuais [SWS_CM_00130] ou especificadores de instância [SWS_CM_00152].

Tratamento de erros e simultaneidade

A função é declarada como noexcept e especificada como segura contra exceções (exception safe) [SWS_CM_00153]. Possíveis violações durante a criação são WrongMethodCallProcessingModeViolation em caso de passagem de um modo de processamento não permitido, bem como InsufficientPermissionsViolation, caso a verificação de autorização (Grant Enforcement) falhe [SWS_CM_00153].

Se o modelo de polling (kPoll) for configurado para mode, a aplicação do servidor deve processar chamadas de método pendentes de forma síncrona no contexto de sua própria thread chamando ProcessNextMethodCall() [SWS_CM_00199]. O construtor de cópia da classe de skeleton está excluído (delete) [SWS_CM_00134]; movimentações, por outro lado, são suportadas através do construtor de movimento [SWS_CM_00135].

Interação

Após a instanciação bem-sucedida, o serviço é disponibilizado para consumidores remotos ou locais através de OfferService() [SWS_CM_00101], ARAComAPI §6.5 «Service Discovery». Antes da destruição do skeleton por meio do destrutor [SWS_CM_11370], a disponibilização deve ser encerrada via StopOfferService() [SWS_CM_00111]. Chamadas de métodos recebidas retornam, cada uma, um ara::core::Future no lado do servidor [SWS_CM_00191].

O destrutor virtual ~<SI>Skeleton() [SWS_CM_11370] encerra o ciclo de vida de uma instância de skeleton de serviço. O skeleton de serviço, como artefato gerado, conecta a implementação concreta do serviço à camada de transporte do Communication Management, permitindo que os consumidores do serviço acessem os métodos e funcionalidades oferecidos (ARAComAPI §5.1 «Proxy Skeleton Pattern»).

A destruição ocorre de forma síncrona durante a desconstrução da classe de implementação derivada. O método não recebe parâmetros e não declara valor de retorno. Em contraste com os construtores do skeleton, como [SWS_CM_00130] ou [SWS_CM_00152], o destrutor é explicitamente classificado na especificação como not exception safe [SWS_CM_11370].

Em relação ao tratamento de erros e condições de contorno, fica estabelecido que, em caso de pré-condição violada, pode ocorrer uma DanglingSamplesViolation [SWS_CM_11370]. Se o serviço foi previamente oferecido externamente por meio de OfferService() [SWS_CM_00101] (ARAComAPI §6.5 «Service Discovery»), deve provavelmente ser necessário chamar o método StopOfferService() [SWS_CM_00111] antes da chamada do destrutor para encerrar de forma limpa as relações de comunicação em andamento. Pergunta Q-c430a7f0fc838eba (aberta)

Para o skeleton, o construtor de cópia foi excluído [SWS_CM_00134], enquanto operações de movimentação são suportadas [SWS_CM_00135]. Processamentos em andamento – tais como o processamento de chamadas pendentes via ProcessNextMethodCall() [SWS_CM_00199] – devem ser concluídos antes do início da destruição.

O método [SWS_CM_00111] encerra a oferta de uma instância de serviço pela aplicação provedora de serviço em ara::com. A chamada ocorre sem parâmetros na instância concreta do skeleton no namespace <SI-Namespace>::skeleton::<SI> e não fornece valor de retorno (EXP_ARAComAPI §5.4.1 «Skeleton Class API’s»).

Para o uso e o comportamento em tempo de execução, aplicam-se as seguintes condições:

• Contexto de chamada e pré-condição: o método é chamado quando uma instância previamente disponibilizada por meio de OfferService() não deve mais estar disponível – por exemplo, em decorrência de alterações de estado (EXP_ARAComAPI §5.4.4 «Offering Service instance»).
• Garantia (contrato): assim que StopOfferService() retornar, de acordo com o contrato, nenhuma chamada de método adicional será encaminhada para esta instância de serviço (EXP_ARAComAPI §5.4.4 «Offering Service instance»).
• Ciclo de vida e destrutor: caso uma instância de serviço ainda esteja sendo oferecida ativamente quando o destrutor da classe skeleton for chamado, o destrutor executará StopOfferService() internamente de forma obrigatória (EXP_ARAComAPI §5.4.4 «Offering Service instance»).
• Service Discovery: através da chamada, o registro local ou o protocolo de Service Discovery do middleware é atualizado sobre a retirada do serviço (EXP_ARAComAPI §7.2.1 «Central vs Distributed approach»).

A função está declarada como noexcept e é considerada segura contra exceções ([SWS_CM_00111]). Ela não sinaliza erros nem por meio de exceções, nem por mensagens de erro ou códigos de retorno.