classe ara::log::Logger

A função-membro LogDebug da classe ara::log::Logger serve para criar mensagens de log com a severidade de erro Debug e retorna para isso um objeto LogStream correspondentemente configurado [SWS_LOG_00068]. A declaração é feita por meio do arquivo de cabeçalho #include "ara/log/logger.h" [SWS_LOG_00068].

Para o uso e a semântica, estão definidas as seguintes características de especificação:

• Chamada e valor de retorno: O método não recebe parâmetros de passagem e retorna diretamente um objeto LogStream com nível de severidade Debug [SWS_LOG_00068]. O modo de funcionamento corresponde ao do método Logger::LogFatal() [SWS_LOG_00068].
• Tratamento de erros: A assinatura é declarada como noexcept e especificada como segura contra exceções (exception safe) [SWS_LOG_00068]. Não são indicadas mensagens de erro ou códigos de erro em caso de erro [SWS_LOG_00068].
• Concorrência: A função-membro é classificada como constante (const) bem como explicitamente thread-safe [SWS_LOG_00068], de modo que acessos concorrentes de leitura na mesma instância de logger são permitidos.

O método LogError da classe ara::log::Logger serve para iniciar uma entrada de log com o nível de severidade Error [SWS_LOG_00065]. A função é declarada através do arquivo de cabeçalho ara/log/logger.h e não recebe parâmetros [SWS_LOG_00065].

Utilização e valor de retorno

A chamada síncrona retorna um objeto do tipo LogStream com o nível de severidade Error [SWS_LOG_00065]. O comportamento corresponde funcionalmente ao de Logger::LogFatal() [SWS_LOG_00065]. Como LogError é declarado como const, a chamada não modifica o estado do objeto logger e também pode ser executada em instâncias constantes [SWS_LOG_00065].

Simultaneidade e segurança contra exceções

Para o contexto de chamada aplicam-se garantias definidas [SWS_LOG_00065]:

• Segurança de thread: A função é especificada como thread-safe [SWS_LOG_00065]. Interpretação: Chamadas provavelmente podem, portanto, ocorrer de forma concorrente a partir de múltiplas threads na mesma instância sem sincronização externa. Pergunta Q-e55d2b523c5cbcb3 (aberta)
• Segurança contra exceções: O método é declarado como noexcept bem como exception safe [SWS_LOG_00065]; ele não lança exceções em tempo de execução.

Tratamento de erros

Códigos de erro específicos ou notificações ao DET ou DEM não estão previstos para LogError [SWS_LOG_00065]. Estados de erro na chamada são excluídos pela segurança garantida contra exceções e pela interface sem parâmetros [SWS_LOG_00065].

Uso e tempo de vida

O método LogFatal da classe ara::log::Logger (disponibilizado por meio do cabeçalho ara/log/logger.h) cria um objeto LogStream com o nível de severidade Fatal ([SWS_LOG_00064]). A função não recebe argumentos e retorna o stream diretamente. O objeto LogStream retornado recebe mensagens de log e parâmetros sequencialmente por meio do operador de stream << ([SWS_LOG_00064]). No cenário de aplicação regular, o tempo de vida do stream criado é limitado a uma única instrução e termina com o ponto e vírgula final após o último parâmetro passado ([SWS_LOG_00064]). Para estender o tempo de vida do objeto de stream além disso, ele pode ser atribuído a uma variável nomeada ([SWS_LOG_00064]).

Tratamento de erros e simultaneidade

A função é declarada como noexcept e especificada como segura contra exceções (exception safe) ([SWS_LOG_00064]). Ela não lança exceções em tempo de execução e não utiliza códigos de erro específicos. Quanto à concorrência, o método é especificado como const e totalmente thread-safe (thread-safe), permitindo chamadas paralelas por meio da mesma instância de logger ([SWS_LOG_00064]).

Interação

O método corresponde, em interface e comportamento, aos métodos de logging correlatos para diferentes níveis de severidade dentro de ara::log::Logger: LogError ([SWS_LOG_00065]), LogWarn ([SWS_LOG_00066]), LogInfo ([SWS_LOG_00067]), LogDebug ([SWS_LOG_00068]) bem como LogVerbose ([SWS_LOG_00069]).

A função-membro LogInfo da classe ara::log::Logger ([SWS_LOG_00067]) é declarada por meio do cabeçalho ara/log/logger.h. Ela serve para criar uma mensagem de log com o nível de severidade Info, não requer parâmetros de passagem e retorna sincronamente um objeto do tipo LogStream ([SWS_LOG_00067]). O comportamento corresponde, segundo a especificação, ao de Logger::LogFatal() ([SWS_LOG_00067]), sendo a interpretação de que a funcionalidade opera de forma análoga e apenas a classificação de severidade está definida como Info.

Quanto à concorrência e ao contexto de chamada, o método é declarado como const e explicitamente especificado como thread-safe (thread-safe) ([SWS_LOG_00067]). Com isso, LogInfo pode ser chamado a qualquer momento em paralelo por múltiplas threads na mesma instância de logger, sem que sejam necessários mecanismos de sincronização ou bloqueios sob a responsabilidade da aplicação.

No tratamento de erros, a função é provida com o identificador noexcept e classificada como segura contra exceções (exception safe) ([SWS_LOG_00067]). Não são retornados códigos de erro específicos nem são acionadas mensagens de erro do DEM ou DET ([SWS_LOG_00067]); um caso de erro não está definido para esta chamada.

Na estrutura de requisitos, a interface está diretamente atribuída aos upstream requirements [RS_LT_00003] e [RS_LT_00049] ([SWS_LOG_00067]), que definem as diretrizes gerais para o subsistema de logging e tracing.

O método LogVerbose() da classe ara::log::Logger do arquivo de cabeçalho #include "ara/log/logger.h" serve para gerar saídas de log com o nível de severidade mais detalhado Verbose [SWS_LOG_00069]. Nenhum parâmetro é passado na chamada. A função retorna de forma síncrona um objeto LogStream, que é explicitamente inicializado com a severidade Verbose e é utilizado para o encaminhamento de conteúdos de mensagens [SWS_LOG_00069].

A especificação indica o comportamento como idêntico a Logger::LogFatal() [SWS_LOG_00069]; como interpretação, isso deve significar que o armazenamento em buffer e a disponibilização do stream seguem o mecanismo geral de log e diferem apenas pelo nível de severidade atribuído. Pergunta Q-522523e7a845dc3a (aberta) Para o tratamento de erros, o método é especificado como noexcept bem como exception safe [SWS_LOG_00069]. Consequentemente, não ocorrem exceções, e códigos de erro específicos não existem no contexto de chamada [SWS_LOG_00069].

Em relação à concorrência e aos contratos de interface, aplicam-se as seguintes propriedades:

• Segurança de thread: O método é classificado como thread-safe, de modo que chamadas concorrentes por meio da mesma instância de logger ou de instâncias diferentes podem ser executadas com segurança [SWS_LOG_00069].
• Constância: A declaração como const garante que a chamada não altere o estado interno do objeto logger [SWS_LOG_00069].

usar

A função-membro LogWarn da classe ara::log::Logger é disponibilizada por meio do cabeçalho ara/log/logger.h [SWS_LOG_00066]. A chamada é feita sem parâmetros em uma instância de logger através da assinatura LogStream LogWarn () const noexcept; [SWS_LOG_00066]. Como valor de retorno, a função retorna sincronamente um objeto do tipo LogStream com a classificação de severidade Warn (Warn severity) [SWS_LOG_00066]. O comportamento funcional corresponde à descrição de Logger::LogFatal() [SWS_LOG_00066]. Interpretação: O objeto LogStream fornecido deve servir para compor mensagens de log do nível de aviso para posterior saída. Pergunta Q-02b18df759926020 (aberta)

Concorrência e segurança contra erros

Em relação ao contexto de chamada e à concorrência, o método é especificado como thread-safe [SWS_LOG_00066]. Ele pode, assim, ser chamado com segurança a partir de múltiplas threads concorrentes na mesma instância. A função garante total segurança contra exceções (exception safe) e é declarada com noexcept [SWS_LOG_00066]. Códigos de erro específicos, valores de erro ou sinais de retorno para erros de tempo de execução não estão definidos para esta operação [SWS_LOG_00066]; Interpretação: Uma falha no retorno deve estar excluída em operação regular. Pergunta Q-44b264cd97ff8159 (aberta)

usar

O método template LogWith da classe ara::log::Logger serve para o registo estruturado de mensagens com base num identificador, bem como em atributos e argumentos associados [SWS_LOG_00133]. É incluído através do cabeçalho #include "ara/log/logger.h" e executado sincronamente sem valor de retorno [SWS_LOG_00133].

A função recebe os seguintes parâmetros [SWS_LOG_00133]:

• attrs: um std::tuple com atributos da mensagem (tipos Attrs...),
• msgId: uma instância definida pela implementação do tipo MsgId para a identificação do objeto de mensagem,
• params: argumentos variádicos (tipos Params...) que são adicionados à entrada de registo.

Simultaneidade e restrições

A função está especificada como thread-safe e pode ser executada concorrentemente [SWS_LOG_00133]. Está declarada com noexcept e classificada como segura contra exceções (exception safe), razão pela qual não são lançadas exceções C++ [SWS_LOG_00133]. Não estão definidos códigos de erro ou mensagens de erro específicos.

Para a instanciação do template aplica-se: a função não participa na resolução de sobrecargas caso pelo menos um dos tipos em Attrs... não represente um atributo de mensagem permitido [SWS_LOG_00133]. Interpretação: como o requisito para o tipo Attr está marcado com TBD na especificação, a verificação concreta de tipos dependerá provavelmente da respetiva implementação da plataforma. Pergunta Q-30f5de483410d716 (aberta)