The ara::com::SamplePtr behaves as a std::unique_ptr as long as the event/ field is subscribed to, or the Proxy it belongs to is not destroyed. The precondition defined in [SWS_CM_00085] and [SWS_CM_00087] must be fulfilled. Otherwise it is considered a violation.
Note: The SamplePtr is always passed with a const SampleType to the callable in GetNewSamples() (see [SWS_CM_00701]). Therefore the sample datatype (typename T) and the SamplePtr operators using the sample datatype (typename T) are implicitly declared as const. This means that the sample data will always be read-only.
Permite o acesso exclusivo de leitura a eventos recebidos e controla o tempo de vida da memória do middleware.
GERADO POR IAnão revisadoModelo: gemini-3.8-flash-medium · Esforço: medium · Temperatura: não controlável · Prompt: f5d97c2beaf2ProcedênciaPerguntas em aberto (1)
traduzido do guia alemãogemini-3.8-flash-low · 2026-10-13 · Original em alemão
Permite o acesso exclusivo de leitura a eventos recebidos e controla o tempo de vida da memória do middleware.
A classe template encapsula a posse exclusiva de amostras de eventos recebidas segundo o modelo de std::unique_ptr e concede à aplicação acesso direto e imutável de leitura aos buffers do middleware (EXP ARAComAPI §5.3.5.4). As instâncias são passadas na consulta de novas amostras, podem ser transferidas exclusivamente por semântica de movimentação e mantêm o espaço de memória ocupado ([SWS_CM_11537]). Somente a destruição do ponteiro ou uma anulação explícita libera novamente o slot de buffer. A validade pressupõe que o evento permaneça subscrito e que o proxy correspondente exista.
Contexto
A classe template ara::com::SamplePtr representa, na Adaptive Platform, o modelo central de acesso e posse para dados de eventos recebidos (event samples) (EXP ARAComAPI §5.3.5.4). Semanticamente, a classe reproduz um smart pointer exclusivo segundo o modelo de std::unique_ptr (EXP ARAComAPI §5.3.5.4). Os parceiros primários de interação são o nível de aplicação, o objeto de evento ou proxy receptor e o middleware de comunicação subjacente ara::com, que gerencia os recursos de buffer (EXP ARAComAPI, p. 44, EXP ARAComAPI, p. 50).
O conceito segue expressamente uma abordagem zero-copy baseada em referências: em vez de passar dados de eventos por cópia de valor para a aplicação, ara::com encaminha ponteiros ou referências para buffers de comunicação centrais (EXP ARAComAPI, p. 50). Em cenários típicos de distribuição 1:N, os caches locais de eventos podem, com isso, ser atendidos puramente por atualizações de referência, o que minimiza o consumo de memória e a latência (EXP ARAComAPI, p. 50). O acesso aos dados úteis é projetado conceitualmente como estritamente de leitura: na disponibilização, SamplePtr é sempre instanciado com um tipo constante de dados úteis (ara::com::SamplePtr<SampleType const>), tornando todos os operadores de acesso implicitamente constantes (EXP ARAComAPI, p. 39, EXP ARAComAPI, p. 44, [SWS_CM_00701]).
Ciclo de vida
Instâncias de SamplePtr podem ser criadas como ponteiros vazios por meio do construtor padrão ou com nullptr ([SWS_CM_11534], [SWS_CM_11535]). Já instâncias válidas e preenchidas com dados úteis são criadas dentro do middleware durante a desserialização de eventos em slots de buffer e são transmitidas a um callable do lado da aplicação no âmbito de GetNewSamples() (EXP ARAComAPI, p. 44).
Com a entrega, ocorre uma transferência completa de posse (ownership transfer) para a aplicação (EXP ARAComAPI §5.3.5.4). Para garantir a exclusividade da posse, o construtor de cópia e o operador de atribuição por cópia são excluídos ([SWS_CM_11536], [SWS_CM_11538]). A transferência do slot de memória gerenciado é possível exclusivamente por meio de construção por movimentação ou atribuição por movimentação ([SWS_CM_11537], [SWS_CM_11540]), enquanto Swap() permite a troca de conteúdo entre dois ponteiros ([SWS_CM_11544]).
Enquanto uma instância de SamplePtr existir e mantiver o sample, o middleware não pode reivindicar de volta nem sobrescrever o espaço de memória ocupado (EXP ARAComAPI §5.3.5.4). A liberação do slot do middleware ocorre apenas quando o tempo de vida do SamplePtr termina pela chamada do destrutor ([SWS_CM_11547]) ou quando o ponteiro é explicitamente esvaziado mediante Reset(nullptr) ou atribuição de nullptr ([SWS_CM_11539], [SWS_CM_11545]).
O fluxo típico de acesso aos dados divide-se nas seguintes etapas:
Disparar consulta de sample: A aplicação chama GetNewSamples() no proxy do evento e passa uma função de callback adequada com a assinatura void(ara::com::SamplePtr<SampleType const>), bem como um limite superior para a quantidade de samples a serem buscados (EXP ARAComAPI, p. 44).
Entrega ao callback: Se houver novos dados disponíveis e a cota do buffer não estiver esgotada, o middleware desserializa o sample e entrega a nova instância de SamplePtr ao callback (EXP ARAComAPI, p. 44).
Verificar status End-to-End: Por meio de GetProfileCheckStatus(), a aplicação pode consultar o resultado da verificação de proteção E2E para o pacote de dados presente ([SWS_CM_90420]).
Ler dados: A lógica da aplicação acessa o objeto gerenciado para leitura por meio de operator* ([SWS_CM_11541]), operator-> ([SWS_CM_11542]) ou do método Get() ([SWS_CM_11546]).
Processamento posterior ou liberação: caso o sample deva ser persistido além do callback, a aplicação move o ponteiro por meio de construção por movimento para estruturas de memória próprias ([SWS_CM_11537]). Se o ponteiro permanecer no escopo do callback, ele será automaticamente destruído ao sair ([SWS_CM_11547]), o que libera imediatamente o slot no middleware (EXP ARAComAPI §5.3.5.4).
Ao utilizar o SamplePtr, devem ser observadas condições de contorno e fontes de erro específicas:
Esgotamento da cota de buffer: a cada chamada de GetNewSamples(), o middleware monitora se a quantidade de samples atualmente retidos pela aplicação excede a cota previamente assegurada na chamada de Subscribe(). Se a cota for excedida, o GetNewSamples() recusa a entrega de novos samples e retorna, em vez disso, um ara::core::ErrorCode (EXP ARAComAPI, p. 44, EXP ARAComAPI, p. 45).
Invalidade por perda de assinatura ou destruição do proxy: o SamplePtr comporta-se de forma determinística como um std::unique_ptr apenas enquanto o evento subjacente permanecer assinado e a instância de proxy de nível superior existir. Reter ponteiros além do término da assinatura ou da destruição do proxy é considerado uma violação das pré-condições.
Validade do ponteiro e estado nulo: por meio de operator bool(), é possível avaliar o estado de ocupação do ponteiro ([SWS_CM_11543]). A desreferenciação de um ponteiro vazio via operator* ou operator-> leva a comportamento indefinido. Todos os métodos de acesso e modificação são declarados como noexcept ([SWS_CM_11541], [SWS_CM_11542], [SWS_CM_11546]).
Erros de validação E2E: um ponteiro recebido de forma válida não garante obrigatoriamente dados de transmissão livres de erros; por meio do valor de retorno de GetProfileCheckStatus(), a aplicação deve verificar se a proteção End-to-End sinaliza corrupção de dados ou atrasos de transmissão ([SWS_CM_90420]).
Este guia de classe foi gerado por um assistente de curadoria de IA com base nas especificações AUTOSAR para Adaptive Platform Release R25-11.
GERADO POR IAnão revisadoModelo: gemini-3.8-flash-medium · Esforço: medium · Temperatura: não controlável · Prompt: 1cc8beae7ae3ProcedênciaPerguntas em aberto (1)
traduzido do guia alemãogemini-3.8-flash-low · 2026-10-13 · Original em alemão
Utilização e semântica
A função Get é uma função-membro sem parâmetros da classe ara::com::SamplePtr do cabeçalho ara/com/service/sample_ptr.h[SWS_CM_11546]. Retorna de forma síncrona um ponteiro bruto do tipo T* para o objeto gerido pela instância [SWS_CM_11546]. Ao contrário de consultas assíncronas de campos de serviço, que disponibilizam um ara::core::Future[SWS_CM_00112], este acesso ocorre imediatamente na thread chamadora.
Tratamento de erros e condições de contorno
O método é declarado como noexcept e especificado como seguro face a exceções (exception safe) [SWS_CM_11546]; não ocorrem estados de erro através de exceções C++. Se a instância não gerir atualmente nenhum objeto, o ponteiro retornado será presumivelmente nullptr. Pergunta Q-d850bd8ee144369a (aberta) Antes do processamento posterior do dado referenciado, deve assegurar-se que a monitorização E2E apresenta o estado ara::com::e2e::SMState::kValid e que a verificação de estado do perfil não indicou qualquer erro [SWS_CM_90422].
Interação e distinção
Na gestão de comunicações, Get serve para o acesso direto a dados de valores recebidos (amostras), tal como são disponibilizados no âmbito da gestão de amostras AUTOSAR_AP_EXP_ARAComAPI §10 «GetNewSamples». Esta função deve ser claramente delimitada de outras operações de Get:
Getter de campo: a obtenção de campos de serviço no proxy ocorre via Get() com o retorno de um ara::core::Future[SWS_CM_00112], para o qual pode ser registado um manipulador do lado do servidor [SWS_CM_00114].
Estado E2E: o estado de monitorização de um getter de campo é determinado separadamente via GetE2EStateMachineStateGetter[SWS_CM_00145].
Este texto foi criado por uma IA e baseia-se no release AUTOSAR R25-11.
GERADO POR IAnão revisadoModelo: gemini-3.8-flash-medium · Esforço: medium · Temperatura: não controlável · Prompt: 0a03c7966b10ProcedênciaPerguntas em aberto (1)
traduzido do guia alemãogemini-3.8-flash-low · 2026-10-13 · Original em alemão
A função-membro Reset da classe ara::com::SamplePtr serve para reinicializar o ponteiro para o objeto gerido [SWS_CM_11545]. Como parâmetro, aceita o valor other do tipo std::nullptr_t. A chamada substitui o objeto atualmente detido por um ponteiro nulo e não retorna nenhum valor (void) [SWS_CM_11545].
No que concerne ao tratamento de erros e à segurança face a exceções, o método é declarado com noexcept e especificado como totalmente seguro face a exceções (exception safe) [SWS_CM_11545]. Não são lançadas exceções C++ nem são reportados códigos de erro específicos.
No sistema global, a libertação de instâncias SamplePtr cumpre uma pré-condição essencial para evitar erros de memória:
Uma obrigação comparável é formulada por [SWS_CM_00085] antes do cancelamento da subscrição de eventos ou campos (Unsubscription).
Interpretação: a chamada explícita de Reset(nullptr) deverá ser, em cenários de aplicação, o meio direto para renunciar deterministicamente à posse de uma amostra de evento antes de tais transições de ciclo de vida, caso o ponteiro não saia automaticamente do seu âmbito de validade. Pergunta Q-a615fa4078ab03ce (aberta)
Esta nota de uso foi criada de forma automatizada com base na especificação AUTOSAR R25-11.
GERADO POR IAnão revisadoModelo: gemini-3.8-flash-medium · Esforço: medium · Temperatura: não controlável · Prompt: 18d4b3f3f0f9ProcedênciaPerguntas em aberto (1)
traduzido do guia alemãogemini-3.8-flash-low · 2026-10-13 · Original em alemão
A chamada ocorre de forma síncrona e espera o seguinte parâmetro:
other: referência a outra instância de ara::com::SamplePtr cujo objeto gerido é trocado com o de *this ([SWS_CM_11544]).
O método não possui valor de retorno (void) ([SWS_CM_11544]).
Tratamento de erros
A assinatura é declarada com noexcept e classificada como segura face a exceções (exception safe) ([SWS_CM_11544]). A chamada não lança exceções e não retorna códigos de erro.
Simultaneidade e restrições
Como Swap altera o estado de dois objetos (*this e other) em simultâneo, chamadas paralelas em pelo menos uma das instâncias envolvidas presumivelmente não serão thread-safe sem sincronização externa. Pergunta Q-d906e8c05aefbd15 (aberta)
Interação
O método é parte integrante da classe ara::com::SamplePtr ([SWS_CM_11544]). Permite a transferência eficiente de propriedade ou a nova atribuição de amostras de dados recebidas em fluxos de comunicação, sem que o objeto de dados úteis subjacente tenha de ser copiado.
Esta nota de uso foi gerada automaticamente com base nos documentos de especificação.
gemini-3.8-flash-low· 2026-10-13 · Original em alemão