classe ara::shwa::Accessor

A classe template permite o acesso tipado e controlado à memória alocada de um buffer de dados subjacente. A instanciação ocorre exclusivamente por meio de métodos estáticos de fábrica, que retornam a instância como um ponteiro exclusivo ([AP_SWS_SHWA_00007]). Em tempo de execução, os dados podem ser processados por meio de operações de leitura e escrita com segurança de tipos ou por meio de operadores de indexação ([AP_SWS_SHWA_00011]). Todas as operações de cópia e movimentação são impedidas, enquanto operações de dados individuais estão sujeitas a requisitos específicos de segurança de threads e tratamento de erros.

mais ›

Contexto

A classe template ara::shwa::Accessor constitui a interface de acesso central para o acesso tipado à memória em buffers de memória compartilhada (shared memory) na AUTOSAR Adaptive Platform. Ela encapsula a lógica de endereçamento e de acesso a um ara::shwa::Buffer subjacente e o parametriza estaticamente por meio do tipo de dados (DataT), da dimensionalidade (Dimensions), do modo de acesso (AccessModeType), do dispositivo de destino (AccessTargetType) e do alocador de memória utilizado (AllocatorT). Em cenários avançados, a classe integra um TaskHandler, que presumivelmente controla tarefas de processamento no ambiente de buffer. Pergunta Q-552022fbf949a1f0 (aberta)

Dentro do módulo, a classe atua em interação com três parceiros centrais:

• Aplicação / Chamador: solicita instâncias por meio da interface de fábrica e executa operações de leitura ou escrita por meio de métodos ou operadores.
• ara::shwa::Buffer: disponibiliza a área de memória alocada e é transmitido ao Accessor como referência durante sua criação ([AP_SWS_SHWA_00007]).
• TaskHandler: é registrado, se necessário, durante a criação para coordenar tarefas no tratamento de buffer ([AP_SWS_SHWA_00008]).

Diagrama de contexto: Parceiros de interação de ara::shwa::Accessor. Fontes: [AP_SWS_SHWA_00007], [AP_SWS_SHWA_00008]

Ciclo de vida

O ciclo de vida de ara::shwa::Accessor está sujeito a restrições semânticas rigorosas que impedem a duplicação ou a movimentação descontrolada de instâncias de acesso. O construtor padrão está explicitamente excluído ([AP_SWS_SHWA_00002]). Do mesmo modo, tanto o construtor de cópia ([AP_SWS_SHWA_00003]) quanto o construtor de movimentação ([AP_SWS_SHWA_00005]), bem como todos os operadores de atribuição por cópia e por movimentação, estão declarados como excluídos ([AP_SWS_SHWA_00004], [AP_SWS_SHWA_00006]). Uma instanciação direta na pilha ou uma semântica de valor fica, assim, excluída.

A criação de novas instâncias ocorre exclusivamente por meio do método estático de fábrica Create ([AP_SWS_SHWA_00007], [AP_SWS_SHWA_00008]). Ele retorna um ara::core::Result<std::unique_ptr<Accessor>>, transferindo assim a posse com exclusividade para o chamador. O objeto é automaticamente destruído assim que o std::unique_ptr proprietário sai de seu escopo. Os métodos de criação são especificados como thread-safe e seguros quanto a exceções ([AP_SWS_SHWA_00007], [AP_SWS_SHWA_00008]).

Quanto à concorrência durante a operação contínua, os métodos de acesso explícitos Get ([AP_SWS_SHWA_00012]) e Set ([AP_SWS_SHWA_00011]) são classificados como thread-safe. Em contrapartida, acessos por índice via operator[] ([AP_SWS_SHWA_00009], [AP_SWS_SHWA_00010]), bem como consultas de propriedades via HasProperty ([AP_SWS_SHWA_00015]) e GetProperty ([AP_SWS_SHWA_00016]), não são thread-safe e exigem sincronização no lado da aplicação.

Caminho de utilização

Um fluxo de uso regular divide-se na criação do objeto, na verificação opcional de propriedades e nas operações subsequentes de leitura ou escrita no buffer:

1. Instanciação via fábrica: a aplicação chama Accessor::Create e passa a referência para um ara::shwa::Buffer, bem como, opcionalmente, propriedades de configuração e um TaskHandler ([AP_SWS_SHWA_00007], [AP_SWS_SHWA_00008]). Após a verificação do ara::core::Result, a aplicação assume o std::unique_ptr<Accessor>.
2. Avaliar propriedades: por meio do método template HasProperty<PropertyT>(), é possível consultar se uma característica específica está presente ([AP_SWS_SHWA_00015]). As características presentes são lidas em seguida com GetProperty<PropertyT>() ([AP_SWS_SHWA_00016]).
3. Executar acesso a dados: para a troca de dados propriamente dita, estão disponíveis dois caminhos de interface:
   • Acesso baseado em métodos: operações de escrita ocorrem via Set(index, value) ([AP_SWS_SHWA_00011]), operações de leitura via Get(index) ([AP_SWS_SHWA_00012]), cada uma endereçada por meio de um identificador dimensional (Id<Dimensions>).
   • Acesso baseado em operadores: o operador de índice operator[] permite o endereçamento direto via Id<Dimensions> ([AP_SWS_SHWA_00009]) ou por um deslocamento linear do tipo std::size_t ([AP_SWS_SHWA_00010]). O tipo de retorno ReferenceT resolve-se para const DataT& no acesso de leitura e para DataT& no acesso de escrita ([AP_SWS_SHWA_00014]).

Diagrama de sequência: Sequência típica de chamadas para interação com o buffer via Accessor. Fontes: [AP_SWS_SHWA_00007], [AP_SWS_SHWA_00011], [AP_SWS_SHWA_00012], [AP_SWS_SHWA_00015]

Cenários de erro

Operações com falha são representadas por meio do ara::core::Result utilizando códigos de erro de ShwaErrorCode:

• ShwaErrorCode::kAccessorFailure: Ocorre durante Create se as condições de construção ou os parâmetros forem inválidos ([AP_SWS_SHWA_00007], [AP_SWS_SHWA_00008]).
• ShwaErrorCode::kIntegrityCorrupted: Sinaliza uma violação da integridade de memória do buffer. Isso pode ocorrer durante a instanciação ([AP_SWS_SHWA_00007], [AP_SWS_SHWA_00008]), bem como na escrita via Set ([AP_SWS_SHWA_00011]).
• ShwaErrorCode::kInvalidIndex: É reportado em Get ([AP_SWS_SHWA_00012]) e Set ([AP_SWS_SHWA_00011]) se não houver um valor inicial válido ou se o índice estiver fora dos limites.
• ShwaErrorCode::kInvalidAccessMode: Ocorre em Set se a combinação dos modos de acesso for inválida ([AP_SWS_SHWA_00011]); este deve ser o caso se uma chamada de escrita for realizada em uma classe instanciada para AccessMode::kRead. Pergunta Q-170e82f3dec16e75 (aberta)
• ShwaErrorCode::kResourceBusy: Indica em Get ([AP_SWS_SHWA_00012]) e Set ([AP_SWS_SHWA_00011]) que o recurso está atualmente ocupado. Para este erro é garantida uma semântica de rollback, mantendo-se o estado anterior.
• ShwaErrorCode::kFeatureNotSupported: É retornado quando uma propriedade solicitada via GetProperty não é suportada ([AP_SWS_SHWA_00016]).

Em relação à segurança contra exceções, Create, HasProperty e GetProperty são declarados com noexcept e especificados como seguros contra exceções ([AP_SWS_SHWA_00007], [AP_SWS_SHWA_00008], [AP_SWS_SHWA_00015], [AP_SWS_SHWA_00016]). Em contrapartida, as operações de acesso a dados Get, Set bem como operator[] são consideradas não seguras contra exceções (not exception safe) ([AP_SWS_SHWA_00009], [AP_SWS_SHWA_00010], [AP_SWS_SHWA_00011], [AP_SWS_SHWA_00012]).