estrutura ara::tsync::UserData

A estrutura ara::tsync::UserData serve para a transmissão de dados úteis compactos específicos da aplicação no âmbito de bases de tempo sincronizadas. Ela gerencia um buffer estático com um limite superior imutável de três bytes, definido por meio de kMaxUserDataSize [SWS_TS_14231]. As aplicações escrevem dados úteis no array e identificam a quantidade de bytes efetivamente válidos por meio do campo size [SWS_TS_14232]. Como condição de contorno central, a lógica de programação da aplicação deve garantir que size nunca exceda a capacidade máxima estabelecida e que acessos a áreas não inicializadas do buffer sejam evitados.

mais ›

Contexto

A estrutura de dados ara::tsync::UserData serve, dentro do cluster funcional para sincronização de tempo (tsync) da AUTOSAR Adaptive Platform, para encapsular dados úteis específicos da aplicação no âmbito de bases de tempo sincronizadas. A estrutura é declarada no arquivo de cabeçalho ara/tsync/synchronized_time_base_status.h. Sua responsabilidade primária consiste em fornecer uma área de memória compacta e dimensionada estaticamente para dados adicionais da aplicação, que são transmitidos ou avaliados juntamente com informações de tempo. A extensão máxima desses dados úteis é definida exatamente em três bytes pela constante estática kMaxUserDataSize [SWS_TS_14231]. Para o armazenamento em buffer dos bytes de dados úteis propriamente ditos, é utilizado o array data do tipo ara::core::Array<ara::core::Byte, kMaxUserDataSize> [SWS_TS_14233]. Esse buffer é complementado pelo campo size, que indica a quantidade de bytes de dados úteis efetivamente válidos no buffer [SWS_TS_14232]. Interpretação: devido ao local de definição no cabeçalho ara/tsync/synchronized_time_base_status.h, UserData deve servir principalmente como um campo de status para a transmissão de pequenas informações adicionais relacionadas à aplicação, como flags de controle ou contadores. Pergunta Q-a0fb20686141f042 (aberta) Como parceiros de interação atuam tipicamente serviços provedores de tempo e aplicações receptoras, que consultam ou repassam o status de uma base de tempo sincronizada.

Ciclo de vida

Como uma estrutura C++ comum (Value Object), UserData não possui um ciclo de vida interno complexo e dispensa completamente alocações dinâmicas de memória. As instâncias são geralmente criadas na pilha ou como elemento de dados embutido de estruturas de status de nível superior. A inicialização ocorre diretamente por meio de inicialização de membros ou atribuição padrão de C++. Em relação à posse, a estrutura obedece à semântica de valor: os componentes criadores possuem integralmente sua instância local e a transmitem por cópia ou referência para as interfaces. Como UserData não implementa mecanismos internos de sincronização ou bloqueios por mutex, o acesso concorrente de leitura e escrita a partir de múltiplas threads para a mesma instância não é seguro para threads. As aplicações devem proteger os acessos simultâneos por meio de medidas externas de sincronização, enquanto instâncias independentes entre si podem ser usadas com segurança em contextos concorrentes. A destruição não requer limpeza explícita de recursos, já que o campo de dados contido data [SWS_TS_14233] é reservado estaticamente.

Caminho de utilização

Um caminho de uso típico abrange o preenchimento, o repasse e a avaliação do buffer de dados. Primeiramente, um componente transmissor ou disponibilizador de status cria uma instância de UserData. Em seguida, os dados úteis são copiados para o array data, podendo ser ocupados no máximo kMaxUserDataSize bytes [SWS_TS_14231], [SWS_TS_14233]. Imediatamente depois, o componente define o campo size para o número efetivo de bytes gravados [SWS_TS_14232]. No lado do receptor, a aplicação de processamento verifica primeiramente o valor de size [SWS_TS_14232]. Se size for maior que zero, a aplicação lê exatamente esse prefixo válido do buffer data [SWS_TS_14233]. Valores fora desse intervalo, ou seja, a partir do índice size até kMaxUserDataSize - 1, são ignorados, pois podem conter dados residuais indefinidos ou desatualizados.

Cenários de erro

Situações de erro resultam em UserData principalmente de inconsistências entre a indicação de tamanho e a capacidade do buffer. Se o campo size assumir um valor que exceda o tamanho máximo definido kMaxUserDataSize de três bytes [SWS_TS_14231], ocorre uma violação dos limites da especificação. Em tal caso, durante a leitura iterativa de data [SWS_TS_14233], há risco de estouros de buffer ou acessos fora dos limites definidos do array. Outro risco reside na leitura incorreta de data quando size for igual a zero [SWS_TS_14232], uma vez que nesse estado não existem dados úteis válidos. Códigos de erro ou exceções não são gerados pela própria estrutura; a validação de pré-condições — em especial size <= kMaxUserDataSize — cabe, portanto, inteiramente à lógica de programação da aplicação.