namespace ara::log

A enumeração ara::log::ClientState mapeia o status atual de conexão de um cliente externo ao backend DLT [SWS_LOG_00098]. Ela baseia-se no tipo de dados std::int8_t e é incluída por meio do arquivo de cabeçalho #include "ara/log/common.h" ou do cabeçalho de encaminhamento #include "ara/log/log_fwd.h" [SWS_LOG_00098].

Estados e semântica

A enumeração define três estados de conexão discretos [SWS_LOG_00098]:

• kUnknown (-1): o backend DLT ainda não está operacional; o status real de conexão não pode ser determinado neste momento [SWS_LOG_00098].
• kNotConnected: nenhum cliente externo foi detectado [SWS_LOG_00098].
• kConnected: um cliente remoto está conectado com sucesso [SWS_LOG_00098].

Interação e concorrência

A enumeração serve principalmente como parâmetro de passagem para o callback de função ConnectionStateHandler (definido como std::function<void(ClientState)>), o qual é registrado por meio de ara::log::RegisterConnectionStateHandler [SWS_LOG_00265]. Esse handler é declarado como thread-safe [SWS_LOG_00265]. Interpretação: supõe-se que os handlers registrados sejam chamados de forma assíncrona assim que o backend DLT detectar mudanças de estado do cliente externo. Pergunta Q-b78ef73772a658a2 (aberta)

O alias de tipo ConnectionStateHandler especifica a assinatura para funções de callback destinadas ao monitoramento do status de conexão no módulo log [SWS_LOG_00265]. Ele é declarado no espaço nominal ara::log e requer a inclusão do arquivo de cabeçalho ara/log/logger.h [SWS_LOG_00265]. Como invólucro de função std::function<void(ClientState)>, a rotina de callback recebe o estado de conexão ocorrido através do parâmetro do tipo ClientState e não fornece valor de retorno [SWS_LOG_00265].

A utilização ocorre através da função de registro RegisterConnectionStateHandler [SWS_LOG_00205]. Para a interação e o ciclo de vida do manipulador, aplicam-se as seguintes especificações:

• Momento da chamada: A função de callback registrada é chamada sempre que o status de conexão do cliente é alterado [SWS_LOG_00205].
• Exclusividade: Pode haver apenas um único manipulador ativamente registrado em qualquer momento [SWS_LOG_00205]. Se um callback já tiver sido registrado anteriormente, a nova função passada o substitui completamente, de modo que doravante apenas o novo manipulador seja chamado [SWS_LOG_00205].
• Segurança contra exceções: A função de registro RegisterConnectionStateHandler está especificada com noexcept, de modo que a passagem do callback de função ocorre de forma segura contra exceções [SWS_LOG_00205].

Em relação à simultaneidade, o elemento de especificação é indicado como seguro para threads [SWS_LOG_00265]. Interpretação: Como as mudanças de estado são potencialmente sinalizadas de forma assíncrona pela infraestrutura de logging, a lógica de aplicação fornecida no manipulador provavelmente precisará ser projetada para ser reentrante e não executar operações bloqueantes, a fim de não prejudicar o contexto de comunicação. Pergunta Q-ca507d992cc31284 (aberta)

usar

A função CreateLogger no namespace ara::log serve para a criação e registro de um objeto Logger, que gerencia o respectivo contexto dentro da estrutura de logging [SWS_LOG_00021]. Na chamada, são passados o identificador de contexto ctxId, a descrição textual ctxDescription bem como o nível de log padrão ctxDefLogLevel [SWS_LOG_00021]. Caso nenhum modelo esteja disponível, a estrutura redireciona as saídas por padrão para o console como destino (sink) [SWS_LOG_00021].

A função retorna uma referência Logger & à instância gerenciada internamente. A posse (ownership) permanece inteiramente na estrutura de logging [SWS_LOG_00021].

Simultaneidade e segurança de execução

A interface é declarada como noexcept e especificada tanto como segura contra exceções (exception safe) quanto como segura para threads (thread-safe) [SWS_LOG_00021]. Ela pode, assim, ser chamada com segurança a partir de múltiplas threads concorrentes.

Interação e alternativas

Para diferentes abordagens de configuração, estão disponíveis interfaces relacionadas:

• Uma sobrecarga alternativa permite a instanciação apenas através de ctxId e ctxDescription [SWS_LOG_00263], onde é utilizado implicitamente Warning como nível de log padrão [SWS_LOG_00021].
• Além disso, um Logger pode ser derivado com base em modelo através de um ara::core::InstanceSpecifier a partir do manifesto [SWS_LOG_00256]. Ao fazê-lo, a plataforma verifica erros como InstanceSpecifierMappingIntegrityViolation ou PortInterfaceMappingViolation [SWS_LOG_00256].

A função síncrona CreateLogger cria ou fornece uma referência a um objeto Logger gerenciado internamente com base nos dados do modelo do manifesto [SWS_LOG_00256]. Como parâmetro de chamada serve uma referência a um ara::core::InstanceSpecifier, que identifica o elemento de modelo desejado no contexto do processo em execução [SWS_LOG_00256].

A função é declarada como noexcept, é considerada segura contra exceções (exception safe) e está especificada como segura para threads, de modo que as chamadas podem ocorrer de forma reentrante e concorrente [SWS_LOG_00256]. Para configurações incorretas ou contextos de modelo inválidos, a especificação define várias violações (Violations) [SWS_LOG_00256]:

• InstanceSpecifierMappingIntegrityViolation: Ocorre quando o InstanceSpecifier não pode ser resolvido no contexto do executável ou aponta para um elemento diferente de um PortPrototype [SWS_LOG_00256].
• PortInterfaceMappingViolation: É disparado caso o tipo de mapeamento não corresponda ao tipo esperado da interface de porta [SWS_LOG_00256].
• ProcessMappingViolation: Aplica-se quando, embora exista um InstanceRef correspondente, nenhum processo modelado corresponde ao processo de tempo de execução [SWS_LOG_00256].
• InstanceSpecifierAlreadyInUseViolation: Sinaliza que um construtor na estrutura foi chamado com um identificador que já está sendo utilizado neste processo [SWS_LOG_00256].

Em comparação com as sobrecargas [SWS_LOG_00021] e [SWS_LOG_00263], que inicializam registradores programaticamente através de IDs de contexto e strings de descrição e, na falta de um modelo, utilizam por padrão o console como destino (sink), a configuração aqui ocorre inteiramente orientada a manifesto. Em todas as variantes, a propriedade da instância permanece dentro da estrutura de logging [SWS_LOG_00263].

A função CreateLogger no espaço nominal ara::log ([SWS_LOG_00263]) serve para a criação e registro de um objeto Logger vinculado a contexto dentro da estrutura de logging do AUTOSAR Adaptive.

usar

Através do arquivo de cabeçalho ara/log/logger.h, a função recebe o identificador de contexto ctxId bem como a descrição detalhada ctxDescription, cada um como tipo ara::core::StringView [SWS_LOG_00263]. Como valor de retorno, a chamada fornece uma referência Logger & à instância gerenciada internamente do objeto Logger criado [SWS_LOG_00263]. A propriedade (ownership) desta instância permanece permanentemente com a estrutura de logging e não é transferida para quem a chamou [SWS_LOG_00263]. Caso nenhum modelo esteja disponível no sistema, o console atua por padrão como destino (sink) para todas as saídas de logging [SWS_LOG_00263].

Tratamento de erros e simultaneidade

Para a chamada não estão definidos códigos de erro específicos e não são lançadas exceções C++, pois a função é especificada com noexcept e indicada como segura contra exceções (exception safe) [SWS_LOG_00263]. Em relação à concorrência, CreateLogger é segura para threads (thread-safe), de modo que a função pode ser chamada concorrentemente a partir de múltiplas threads sem sincronização externa [SWS_LOG_00263].

Interação

A estrutura de logging oferece sobrecargas estreitamente relacionadas: Além desta assinatura de dois parâmetros, uma sobrecarga permite a configuração adicional de um nível de log padrão através de ctxDefLogLevel ([SWS_LOG_00021]). Outra assinatura possibilita a criação de um objeto Logger através de um ara::core::InstanceSpecifier diretamente a partir do manifesto ([SWS_LOG_00256]).

usar

A função ara::log::EngFloatMax() do ficheiro de cabeçalho ara/log/logger.h cria sincronicamente uma instância do tipo Format [SWS_LOG_00220]. O objeto retornado contém a indicação de formatação Fmt::kEngFloat para a saída de números de ponto flutuante em notação de engenharia, bem como uma precisão suficiente para uma conversão completa de ida e volta (“full round-trip safety”) [SWS_LOG_00220]. A função não espera parâmetros.

Tratamento de erros

A função é provida com o especificador noexcept e definida como segura contra exceções (exception safe) [SWS_LOG_00220]. Não existem códigos de erro específicos e não são lançadas exceções nem transmitidos erros a entidades de diagnóstico ou de notificação de erros. A chamada não falha em operação regular.

Simultaneidade e restrições

A especificação identifica a função como segura para threads (thread-safe) [SWS_LOG_00220]. Graças à identificação como constexpr, a chamada já pode ser avaliada em tempo de compilação. Interpretação: Como a especificação não define pré-condições e a função é sem estado, não deverão existir restrições quanto ao contexto de chamada nem dependências de uma inicialização prévia da infraestrutura de logging. Pergunta Q-90c67bfad5b19641 (aberta)

A função auxiliar HexFloat serve para a criação de um objeto de formatação para números de ponto flutuante para saída no formato hexadecimal de acordo com [SWS_LOG_00221]. Ela instancia um objeto do tipo Format provido com a dica de formatação Fmt::kHexFloat, bem como uma precisão predefinida.

Utilização e parâmetros

A função está disponível no namespace ara::log através do cabeçalho #include "ara/log/logger.h" [SWS_LOG_00221]:

• Parâmetro: Como parâmetro de entrada, é passado precision do tipo std::uint16_t, o qual define a precisão de saída desejada [SWS_LOG_00221].
• Valor de retorno: Um objeto Format inicializado com prefixo Fmt::kHexFloat definido [SWS_LOG_00221].
• Execução: Devido à caracterização como constexpr, a construção da dica de formatação pode ocorrer de forma síncrona em tempo de execução ou já em tempo de compilação [SWS_LOG_00221].

Tratamento de erros e simultaneidade

A assinatura é declarada com noexcept e considerada totalmente segura contra exceções (exception safe) [SWS_LOG_00221]. Não são gerados códigos de erro nem mensagens de erro específicas. A função é especificada como segura para threads (thread-safe) e pode ser chamada paralelamente a partir de contextos arbitrários sem necessidade de sincronização [SWS_LOG_00221].

A função HexFloatMax no espaço de nomes ara::log serve para a criação de uma instância Format para a saída formatada de valores de ponto flutuante [SWS_LOG_00222]. É disponibilizada através do ficheiro de cabeçalho #include "ara/log/logger.h" e não aceita parâmetros de chamada [SWS_LOG_00222]. Como valor de retorno síncrono, é fornecida uma instância Format que está munida da indicação de formatação Fmt::kHexFloat e apresenta uma precisão que assegura uma segurança de round-trip completa [SWS_LOG_00222].

A assinatura está declarada como constexpr bem como noexcept [SWS_LOG_00222]. Isto permite a avaliação logo em tempo de compilação e garante que nenhuma exceção pode ocorrer durante a execução. Estados de erro especiais, códigos de erro ou mecanismos de tratamento de erros não estão especificados para esta chamada, uma vez que a criação do objeto de formato ocorre sempre sem erros.

No que diz respeito ao contexto de chamada e à concorrência, a função está especificada como segura contra exceções (exception safe) e segura para threads (thread-safe) [SWS_LOG_00222]. Não está sujeita a restrições de chamadas sequenciais e pode ser chamada com segurança e concorrentemente a partir de quaisquer threads sem sincronização adicional.

usar

A função ara::log::Oct() serve como função utilitária para a criação de um objeto de formatação para saídas de registo no sistema octal [SWS_LOG_00213]. Não recebe parâmetros e devolve de forma síncrona um objeto do tipo Format, que está configurado com a indicação de formatação Fmt::kOct bem como com uma precisão predefinida [SWS_LOG_00213]. Como a função está declarada como constexpr, a instanciação já pode ocorrer em tempo de compilação. Interpretação: o objeto Format devolvido destina-se provavelmente sobretudo a controlar a formatação de números inteiros em fluxos de registo. Pergunta Q-3f4fe5ac42de16cb (aberta)

Tratamento de erros

A função garante segurança contra exceções (exception safe) e está explicitamente declarada como noexcept [SWS_LOG_00213]. A ocorrência de erros de tempo de execução ou o lançamento de exceções está excluída. Não existem códigos de erro específicos e não ocorrem notificações para DET ou DEM.

Simultaneidade e restrições

A chamada de Oct() é irrestritamente segura para threads (thread-safe) [SWS_LOG_00213]. Uma vez que não são modificados estados partilhados, a função não está sujeita a restrições relativas a reentrância ou contexto de chamada e pode ser chamada em paralelo a partir de múltiplas threads.

Interação

A função está definida no namespace ara::log e é disponibilizada através do ficheiro de cabeçalho #include "ara/log/logger.h" [SWS_LOG_00213]. Além desta variante sem parâmetros, existe a sobrecarga Oct(std::uint16_t precision), através da qual pode ser definida uma precisão de dígitos divergente [SWS_LOG_00214].

usar

A função auxiliar ara::log::Oct é disponibilizada através do arquivo de cabeçalho #include "ara/log/logger.h" no namespace ara::log [SWS_LOG_00214]. Ela serve para criar uma instância do tipo Format com a dica de formatação Fmt::kOct, bem como uma precisão predefinida [SWS_LOG_00214]. Como parâmetro de entrada, a função recebe o valor inteiro sem sinal de 16 bits precision, o qual define a precisão a ser aplicada [SWS_LOG_00214]. A função opera de forma síncrona e retorna a instância de Format criada imediatamente [SWS_LOG_00214].

Tratamento de erros e simultaneidade

A função é declarada como noexcept e expressamente especificada como segura contra exceções (exception safe) [SWS_LOG_00214]. Não existem códigos de erro específicos nem notificações via DET ou DEM em caso de erro. Em relação ao contexto de chamada e à concorrência, a função é classificada como segura para threads (thread-safe) [SWS_LOG_00214]. Como ela é adicionalmente definida como constexpr, a criação da instrução de formatação já pode ocorrer em tempo de compilação [SWS_LOG_00214].

Interação

Dentro do módulo log, a função complementa a sobrecarga relacionada Oct() [SWS_LOG_00213]. Enquanto a variante sem parâmetros constrói uma instância de Format com precisão padrão (default precision) [SWS_LOG_00213], a presente função permite a configuração explícita de uma precisão personalizada pelo usuário para a formatação octal [SWS_LOG_00214].

A função RegisterConnectionStateHandler no namespace ara::log serve para registrar uma função de callback do lado da aplicação que é chamada a cada mudança do status de conexão [SWS_LOG_00205]. Ela é declarada no cabeçalho ara/log/logger.h [SWS_LOG_00205]. Como parâmetro, é passado um objeto de função callback do tipo ConnectionStateHandler [SWS_LOG_00205], que é especificado como alias de tipo para std::function<void(ClientState)> [SWS_LOG_00265]. Um valor de retorno não existe (void) [SWS_LOG_00205].

Em relação ao ciclo de vida e à ordem, está definido que, a qualquer momento, apenas um único manipulador de estado pode estar instalado [SWS_LOG_00205]. Se uma função de callback já tiver sido registrada anteriormente, cada nova chamada sobrescreve completamente a instância existente, de modo que, a partir desse momento, exclusivamente o último manipulador passado é executado [SWS_LOG_00205].

A função é declarada com noexcept e especificada como segura contra exceções (“exception safe”) [SWS_LOG_00205]. Códigos de erro específicos, valores de erro ou notificações a monitores de erro ou diagnóstico não estão definidos na especificação [SWS_LOG_00205].

Em relação à concorrência, RegisterConnectionStateHandler é expressamente classificado como não thread-safe (“not thread-safe”) [SWS_LOG_00205]. O registro não deve, portanto, ser chamado de forma concorrente sem proteção a partir de múltiplas threads e deve idealmente ocorrer durante a fase de inicialização. Em contraste com isso, o alias de tipo ConnectionStateHandler é especificado como thread-safe [SWS_LOG_00265]. Interpretação: Disso deve decorrer que o callback registrado pode potencialmente ser chamado pelo ambiente de tempo de execução interno de logging a partir de contextos concorrentes em mudanças de status. Pergunta Q-59eae7980ba48666 (aberta)