classe <SI-Namespace>::skeleton:: events::<Event>

O método Allocate é chamado no nível do skeleton para um evento ([SWS_CM_90438]; AUTOSAR_AP_EXP_ARAComAPI §5.4.1 «Skeleton Class API’s»), a fim de alocar memória para a transmissão de dados de eventos quando o Communication Management (ara::com) é responsável pelo gerenciamento dos dados ([SWS_CM_90438]). Ele retorna uma instância do tipo ara::com::SampleAllocateePtr<SampleType> ([SWS_CM_90438]). Esse tipo de ponteiro comporta-se conceitualmente como um std::unique_ptr<T>, de modo que apenas uma parte é proprietária do ponteiro em qualquer momento (ARAComAPI §6 «Event Allocate/Send sample Binding implementer hint»).

Em relação ao tratamento de erros e segurança contra exceções, Allocate é especificado como not exception safe ([SWS_CM_90438]). A especificação define duas violações possíveis (Violations):

• SampleAllocationViolation: Não há recursos de memória suficientes disponíveis para alocar os dados ([SWS_CM_90438]).
• AllocateUsageViolation: A alocação ocorreu indevidamente por meio de um alocador definido pelo usuário ([SWS_CM_90438]).

O conceito por trás de Allocate visa primariamente o suporte a mecanismos de zero-copy, em particular no transporte IPC baseado em memória compartilhada, pressupondo-se uma sincronização estrita entre leitores e escritores (ARAComAPI §6 «Event Allocate/Send sample Binding implementer hint»). Os implementadores devem observar que requisitos de serialização podem inviabilizar o zero-copy, caso tipos de dados não estejam configurados como binariamente compatíveis no deployment ou uma lógica de detecção exclua isso (ARAComAPI §6 «Event Allocate/Send sample Binding implementer hint»).

Na interação com o envio de eventos, o ponteiro de memória obtido via Allocate é passado para Send(ara::com::SampleAllocateePtr<SampleType> data) ([SWS_CM_90437]). Após a chamada de Send, a aplicação de serviço não deve mais acessar os dados assim que o Communication Management transmitir os dados a todas as aplicações subscritoras ([SWS_CM_90437]).

A função [SWS_CM_00162] serve, no lado do provedor de serviço dentro de <SI-Namespace>::skeleton::events::<Event>, para o envio de dados de eventos para todas as aplicações assinantes. Nesta variante, a responsabilidade pela alocação de dados permanece inteiramente com a aplicação usuária. O objeto de dados é passado através do parâmetro data, após o que a implementação de binding cria uma cópia interna durante a chamada (ARAComAPI, Figure 6.17 «BrakeEvent Class»). Após o retorno da chamada síncrona do método, a aplicação pode modificar ou liberar imediatamente a área de memória original.

O método está declarado com noexcept e especificado como seguro contra exceções. Ele retorna um ara::core::Result<void>, o qual em caso de sucesso contém void e em caso de erro reporta códigos de erro de [SWS_CM_10432] ([SWS_CM_00162]):

• ComErrc::kServiceNotOffered: ocorre quando a instância de serviço ainda não foi disponibilizada via OfferService().
• ComErrc::kMinimumSendIntervalViolationError: Ocorre quando a requisição de envio foi emitida mais rapidamente do que o intervalo mínimo de envio configurado (ServiceInterfaceDeploymentElement.minimumSendInterval).

Ao contrário da alternativa zero-copy [SWS_CM_90437], que pressupõe ponteiros do tipo ara::com::SampleAllocateePtr obtidos via Allocate(), esta chamada não exige vinculação de memória ao framework. O mesmo comportamento de transmissão e as mesmas condições de erro também se aplicam, de acordo com [SWS_CM_00119], ao método de atualização Update de campos.

Utilização e contexto de chamada

O método Send é chamado em uma instância de evento no esqueleto de serviço (<SI-Namespace>::skeleton::events::<Event>) ([SWS_CM_90437]). Ele transmite dados de evento pelos quais o Communication Management é responsável pelo gerenciamento de memória. O parâmetro data do tipo ara::com::SampleAllocateePtr<SampleType> deve ter sido obtido previamente via Allocate() ([SWS_CM_90437]). Esse tipo de ponteiro comporta-se semanticamente como um std::unique_ptr, transferindo a propriedade dos dados para a camada de comunicação durante a chamada (ARAComAPI §6.17 «BrakeEvent Class»). Após a entrega, é proibido qualquer acesso adicional aos dados pela aplicação emissora ([SWS_CM_90437]).

Tratamento de erros e condições de contorno

A função é declarada como noexcept e retorna um ara::core::Result<void> ([SWS_CM_90437]). Se o envio falhar, o resultado conterá um código de erro de ara::com::ComErrc ([SWS_CM_10432]):

• ComErrc::kServiceNotOffered: O serviço correspondente ainda não foi disponibilizado previamente com OfferService() ([SWS_CM_90437]).
• ComErrc::kMinimumSendIntervalViolationError: O intervalo mínimo de envio configurado para o elemento de serviço (minimumSendInterval) ainda não decorreu desde a última transmissão ([SWS_CM_90437]).

Ambos os casos de erro possuem semântica de rollback ([SWS_CM_90437]). Antes da chamada, o serviço deve, portanto, ter sido obrigatoriamente oferecido, e chamadas consecutivas de envio devem respeitar o intervalo mínimo configurado.

Interação e otimização

Em comparação com a assinatura [SWS_CM_00162], na qual dados gerenciados pela aplicação são passados e copiados pelo Communication Management, esta variante visa a comunicação zero-copy via memória compartilhada (Shared Memory) (ARAComAPI §6.18 «Event Allocate/Send sample»). Para isso, pressupõe-se uma sincronização estrita entre escritores e leitores, devendo-se observar possíveis requisitos de serialização entre os parceiros de comunicação (ARAComAPI §6.18 «Event Allocate/Send sample»).

usar

A função SetSubscriptionStateChangeHandler registra no escopo do skeleton (skeleton::events) um manipulador de callback para monitorar o status de assinatura de um evento [SWS_CM_12008]. O parâmetro handler deve ser um objeto chamável de acordo com o tipo SubscriptionStateChangeHandler conforme [SWS_CM_00311]. O método não retorna nenhum valor e é especificado como noexcept [SWS_CM_12008].

O Communication Management chama o manipulador registrado assim que o status de assinatura do evento é alterado [SWS_CM_12012]. No lado do skeleton, isso ocorre com o estado kSubscribed assim que o número de assinaturas ativas se torna maior que zero [SWS_CM_12013], ou com kNotSubscribed quando não há mais assinaturas ativas presentes [SWS_CM_12014] SWS CommunicationManagement §7.5.4 «Query Service Event Subscription State on Skeleton side».

Tratamento de erros e simultaneidade

A operação é classificada como exception safe [SWS_CM_12008]. Se o chamável passado for inválido ou nulo, ocorre um InvalidHandlerViolation [SWS_CM_12008]. Interpretação: Como a função não lança exceções nem retorna um código de erro, essa violação de especificação provavelmente deve ser interceptada por mecanismos de tempo de execução específicos da plataforma. Pergunta Q-a7b7b54f0d538b40 (aberta)

O manipulador pode ser sobrescrito em tempo de execução [SWS_CM_12012]. Para a execução em um contexto de thread ou de tarefa dedicado, existe a sobrecarga com o parâmetro de template executor [SWS_CM_12009]. Um registro análogo para elementos de gatilho do skeleton é definido por [SWS_CM_01110].

A função de template SetSubscriptionStateChangeHandler serve, ao nível do skeleton ([SWS_CM_12009]) no espaço de nomes de um evento, para o registo de um callback para alterações de estado de subscrições recebidas. Em comparação com a função de base sem executor ([SWS_CM_12008]), esta aceita adicionalmente um contexto de execução (executor) no qual o handler registado é executado ([SWS_CM_12009]). A função não possui valor de retorno, está declarada como noexcept e é considerada segura contra exceções ([SWS_CM_12009]).

Relativamente ao comportamento face a erros, a passagem de um callable inválido ou nulo resulta num InvalidHandlerViolation ([SWS_CM_12009]). O handler registado pode ser substituído a qualquer momento em tempo de execução da aplicação através de uma nova chamada ([SWS_CM_12012]).

O Communication Management chama o handler assim que o estado das subscrições para o respetivo evento se altera (SWS CommunicationManagement §7.5.4 «Query Service Event Subscription State on Skeleton side», [SWS_CM_12012]):

• A chamada ocorre com o estado kSubscribed quando o número de subscrições ativas aumenta de zero para mais de zero ([SWS_CM_12013]).
• Se o número de subscritores ativos voltar a descer para zero, o handler é notificado com kNotSubscribed ([SWS_CM_12014]).

Interpretação: Através da passagem de executor, a execução do handler deverá ser vinculada de forma direcionada a contextos de thread ou de dispatching próprios da aplicação ([SWS_CM_12009]), a fim de separar de forma limpa a notificação concorrente do código do skeleton relativamente às threads de comunicação internas. Pergunta Q-b11f3bc97069f2ec (aberta)

A função UnsetSubscriptionStateChangeHandler serve, no nível do skeleton no namespace ::skeleton::events::{<event-name>}, para cancelar o registro de um manipulador de alteração de estado previamente registrado para o ara::com::SubscriptionState de um evento [SWS_CM_12010]. A função não recebe parâmetros de entrada e não fornece valor de retorno (void) [SWS_CM_12010]. A inclusão ocorre por meio do cabeçalho #include "<SiNamespaceDerivedDirectoryPath>/<SiShortname>_skeleton.h" [SWS_CM_12010].

Em relação ao comportamento de exceção, o método é declarado com noexcept e especificado como seguro contra exceções (exception safe) [SWS_CM_12010]. Não são retornados códigos de erro específicos nem lançadas exceções em C++ [SWS_CM_12010]. Interpretação: eventuais estados de erro internos durante o cancelamento do registro provavelmente são interceptados internamente pelo gerenciamento de comunicação, uma vez que a assinatura não prevê feedback de erro. Pergunta Q-7e986a15e552ca19 (aberta)

Na interação com interfaces relacionadas, existem funções análogas para o cancelamento de registro de manipuladores:

• No nível do skeleton, ::skeleton::triggers::{<trigger-name>}::UnsetSubscriptionStateChangeHandler fornece o respectivo cancelamento de registro para triggers [SWS_CM_01112].
• No nível do proxy, existem métodos equivalentes para cancelar o registro de manipuladores de alteração de estado para events [SWS_CM_00334], fields [SWS_CM_11609] e triggers [SWS_CM_01108] dentro do namespace proxy AUTOSAR_AP_EXP_ARAComAPI §5.3.1 «Proxy Class API’s».