classe ara::sm::s2r::S2RSatellite

usar

O método fábrica estático ara::sm::s2r::S2RSatellite::Create serve para a instanciação síncrona de um satélite para conexão direta com o S2RHub dentro da mesma máquina ([SWS_SM_81014]). A chamada não recebe parâmetros e retorna um ara::core::Result<S2RSatellite>, que fornece o objeto de satélite criado em caso de sucesso ([SWS_SM_81014]).

Tratamento de erros

Caso a opção «Force IAM switch» esteja definida como true na configuração, a chamada falha e fornece o código de erro ara::sm::SmErrc::kAuthenticationRequired ([SWS_SM_00716]). Nesse caso, é obrigatório utilizar, em vez disso, o construtor ara::sm::s2r::S2RSatellite::S2RSatellite ([SWS_SM_81014]). Além disso, é acionado um AraNotInitialized-Violation se o ambiente de tempo de execução ARA não estiver inicializado no momento da chamada ([SWS_SM_81014]).

Simultaneidade e condições marginais

A função está especificada como thread-safe e exception-safe e declarada com noexcept ([SWS_SM_81014]). Ela pode, assim, ser chamada com segurança a partir de contextos concorrentes da aplicação.

Interação

Instâncias de S2RSatellite são utilizadas em aplicações compatíveis com S2R para processar notificações antes e após o modo suspend (SWS StateManagement §7.5.2 «S2R Satellite»). Após a instanciação bem-sucedida, a aplicação se registra no hub via Offer ([SWS_SM_00710]). Antes da destruição do objeto, o cancelamento do registro deve ser chamado por meio de StopOffer ([SWS_SM_00713]). Interpretação: O método Create provavelmente deve ser destinado primariamente para cenários de aplicação nos quais nenhuma autenticação IAM é forçada para o satélite. Pergunta Q-fc41980edcb3f61a (aberta)

O método de callback puramente virtual EnterSuspendMode da classe ara::sm::s2r::S2RSatellite [SWS_SM_81010] solicita a uma instância de satélite a entrada no modo Suspend [SWS_SM_00711]. A chamada é iniciada quando o S2R Hub instrui, via RequestToEnterSuspendMode, todos os satélites ativamente registrados a alternar para o estado Suspend [SWS_SM_00701]. O pré-requisito para o recebimento desta chamada é que a instância de satélite tenha sido previamente registrada com sucesso no hub via Offer [SWS_SM_81010] [SWS_SM_00710].

Como valor de retorno serve ara::core::Future<void> [SWS_SM_81010]. Se a aplicação puder assumir com sucesso o modo Suspend, a future é satisfeita com void [SWS_SM_81010]. Se ocorrer um erro, a future deve ser finalizada com o código de erro SmErrc::kRejected [SWS_SM_81010]. Se ao menos um satélite relatar kRejected, a requisição do hub retorna o resultado geral kAtLeastOneRejected [SWS_SM_00702]. Se um satélite não responder a tempo dentro do timeout, a comunicação é interrompida com o erro kCommunicationTimeout AUTOSAR_AP_SWS_StateManagement p. 36.

Em relação à concorrência, a interface é definida como não thread-safe (not-threadsafe) e não segura contra exceções (not exception safe) [SWS_SM_81010]. Antes da destruição do objeto de satélite, deve-se chamar StopOffer; essa chamada desregistra o satélite e bloqueia até que execuções de callback em andamento sejam concluídas [SWS_SM_00713]. Como o método é declarado puramente virtual, presume-se que a implementação concreta ocorra em uma classe de aplicação derivada para persistir estados locais antes do Suspend-to-RAM. Pergunta Q-628b88828075652c (aberta)

O método puramente virtual LeaveSuspendMode serve para aplicações compatíveis com S2R (S2R-Aware applications) deixarem o modo Suspend e retomarem a operação regular [SWS_SM_81011], SWS StateManagement §7.5.2 «S2R Satellite». A lógica de retomada específica da aplicação deve, como interpretação, ser implementada em uma classe derivada de ara::sm::s2r::S2RSatellite. Pergunta Q-c8e12bf51d76935c (aberta)

Utilização e contexto de chamada

A chamada ocorre de forma assíncrona e é acionada pela receção de um acionador de retoma (resume trigger) no satélite [SWS_SM_00711]. Este acionador tem origem em ara::sm::s2r::S2RHub::RequestToLeaveSuspendMode, que envia uma mensagem a todas as instâncias de satélite ativamente registadas [SWS_SM_00703]. O método não espera parâmetros e devolve um ara::core::Future<void> [SWS_SM_81011]. Em caso de sucesso, a future é satisfeita com void assim que o modo de suspensão tiver sido abandonado com êxito [SWS_SM_81011].

Tratamento de erros

Se surgirem problemas durante o despertar, a future falha com o código de erro SmErrc::kRejected (semântica de reversão/rollback) [SWS_SM_81011]. Isto faz com que o hub S2R emita kAtLeastOneHadIssuesToLeave como resultado global [SWS_SM_00707]. Se um satélite não responder dentro do prazo estipulado, o hub aborta com kCommunicationTimeout [SWS_SM_00707].

Concorrência e pré-condições

• Registo: A ativação do manipulador (handler) pressupõe que Offer tenha sido previamente chamado [SWS_SM_81011], estando assim o satélite ativamente registado [SWS_SM_00710].
• Segurança: A operação está especificada como not-threadsafe e not exception safe [SWS_SM_81011].
• Ciclo de vida: Antes da destruição do satélite, StopOffer tem de ser chamado; a chamada bloqueia até que os callbacks em execução estejam concluídos [SWS_SM_00713].

A função-membro síncrona ara::sm::s2r::S2RSatellite::Offer registra uma instância de satélite no hub S2R central [SWS_SM_00710]. A chamada sem parâmetros ativa a recepção de notificações, de modo que callbacks do lado da aplicação para a transição para o modo suspend, bem como para o redespertar, possam ser chamados [SWS_SM_81012], [SWS_SM_81010], [SWS_SM_81011]. O método retorna um ara::core::Result<void> e está declarado como seguro contra exceções (noexcept) [SWS_SM_81012].

No caso regular de sucesso, o Result retornado está vazio [SWS_SM_81012]. Se o serviço não puder ser fornecido devido a uma falha de comunicação com o daemon de State Management, a chamada falha com o código de erro SmErrc::kOfferFailed [SWS_SM_81012]. Além disso, o contexto do processo do satélite deve cumprir as diretrizes de IAM para a aplicação registrada, visto que instâncias não autorizadas são rejeitadas [SWS_SM_00715]. Interpretação: Se o registro falhar, a instância provavelmente deve permanecer não registrada no hub. Pergunta Q-1b445bcf1aecef2d (aberta)

Em relação à concorrência, Offer está especificado como não seguro para threads (not thread-safe) [SWS_SM_81012]; chamadas paralelas na mesma instância requerem, portanto, sincronização externa. Após a disponibilização bem-sucedida, o satélite permanece registrado ativamente até que a aplicação chame explicitamente ara::sm::s2r::S2RSatellite::StopOffer [SWS_SM_00710]. O cancelamento do registro via StopOffer deve ocorrer antes da destruição do satélite e bloqueia até que os callbacks em execução sejam concluídos [SWS_SM_00713].

Utilização e semântica

O método StopOffer() cancela o registro de uma instância de ara::sm::s2r::S2RSatellite no S2R Hub e desativa futuras chamadas de callback ([SWS_SM_81013], [SWS_SM_00710]). A chamada ocorre de forma síncrona e bloqueia até que todas as execuções de callback atualmente ativas estejam completamente concluídas ([SWS_SM_00713]). A função não recebe parâmetros e não possui valor de retorno.

Ciclo de vida e tratamento de erros

A interface está declarada como noexcept e não lança exceções; códigos de erro específicos não existem ([SWS_SM_81013]). De acordo com a especificação, StopOffer() não é segura para threads (not thread-safe). A aplicação deve garantir que StopOffer() seja chamado explicitamente antes da destruição do objeto S2RSatellite ou — interpretação: presumivelmente — seja executado dentro do destrutor da classe de usuário encapsuladora (SWS StateManagement §7.5.2 «Deregistration of S2R Satellites at S2R Hub»). Pergunta Q-79aa369fb23871ed (aberta)

Interação no fluxo de Suspend-to-RAM

Se o S2R Hub estiver na execução de RequestToEnterSuspendMode ou RequestToLeaveSuspendMode, ele aguardará por todos os satélites endereçados. Se um satélite cancelar o registro nessa fase por meio de StopOffer(), isso será avaliado pelo hub como uma resposta positiva e evitará uma falha na mudança de estado ([SWS_SM_00702], [SWS_SM_00707]).