classe ara::log::LogStream

A classe ara::log::LogStream representa uma mensagem de log formatável cujo buffer interno é preenchido gradualmente com dados e metadados por meio de operadores de stream. As instâncias são tipicamente obtidas de forma temporária via métodos de logging e encaminham o conteúdo coletado automaticamente para o framework de logging por meio do destrutor ao sair do escopo [SWS_LOG_00262]. Para mensagens de múltiplas linhas ou reutilizadas, o encaminhamento pode ser disparado explicitamente via Flush() [SWS_LOG_00039]. Como restrição central, a classe não é thread-safe e impede totalmente operações de cópia.

mais ›

Contexto

A classe ara::log::LogStream representa uma mensagem de log formatável no subsistema de logging adaptativo. Ela fornece uma interface de buffer baseada em mensagens que permite anexar gradualmente dados úteis heterogêneos a um buffer interno por meio de operadores de stream sobrecarregados.

No caso de uso regular, os processos da aplicação não interagem diretamente com LogStream por meio de uma instanciação explícita. Em vez disso, a API principal de logging (por exemplo, por meio de métodos de logging como LogDebug()) disponibiliza instâncias temporárias desta classe, já inicializadas com o nível de severidade exigido. O único motivo previsto para manter um objeto LogStream além do escopo padrão de instrução única (one-statement scope) consiste em compor mensagens de log ao longo de várias linhas de código. Assim que o objeto sai do seu escopo ou é esvaziado explicitamente, o conteúdo do buffer é entregue ao framework de logging para processamento posterior.

Diagrama de contexto: interação entre o processo da aplicação, a API de logging, o LogStream e o framework de logging. Fontes: [SWS_LOG_00039], [SWS_LOG_00262]

Ciclo de vida

A criação de instâncias de LogStream ocorre primariamente como objeto temporário por meio de métodos de fábrica da API principal de logging. Para uma disponibilização eficiente, a classe declara um construtor de movimentação como noexcept [SWS_LOG_00176]. Esse construtor de movimentação é tipicamente apenas declarado e não definido, o que permite aos compiladores compatíveis com C++14 utilizar Return Value Optimization (RVO) no retorno a partir de funções de fábrica [SWS_LOG_00176]. Uma duplicação ou atribuição por movimentação de instâncias está estritamente excluída: o construtor de cópia [SWS_LOG_00174], o operador de atribuição por cópia [SWS_LOG_00175] e o operador de atribuição por movimentação [SWS_LOG_00177] estão excluídos (=delete).

O fim da vida útil é gerenciado pelo destrutor ~LogStream() [SWS_LOG_00262]. Se o objeto sair de seu escopo (por exemplo, no final de um bloco de função ou de uma instrução), o destrutor assegura internamente que o conteúdo do buffer seja encaminhado para processamento no framework de logging [SWS_LOG_00039], [SWS_LOG_00262].

Se uma instância de LogStream for reutilizada no mesmo escopo para várias mensagens consecutivas, a função-membro Flush() deve ser chamada [SWS_LOG_00039]. O importante aqui é que o Flush() não esvazia o buffer, mas envia os dados atuais para o framework de logging e inicia imediatamente um novo fluxo de mensagens [SWS_LOG_00039].

Em relação à concorrência, todas as funções-membro são especificadas como não thread-safe ([SWS_LOG_00039], [SWS_LOG_00040], [SWS_LOG_00129]). Portanto, um exemplar de LogStream não deve ser utilizado em paralelo por múltiplas threads sem sincronização externa.

Caminho de utilização

Um fluxo típico de registro em log compreende as seguintes fases:

1. Disponibilização da stream: o processo da aplicação chama um método de logging que cria uma instância temporária de LogStream e a retorna via RVO [SWS_LOG_00176].
2. Enriquecimento de metadados: antes ou durante a entrada de dados, atributos opcionais podem ser anexados por meio de encadeamento de métodos, incluindo locais no código-fonte via WithLocation(file, line) [SWS_LOG_00129], tags via WithTag(tag) [SWS_LOG_00132] ou níveis de confidencialidade via WithPrivacy(value) [SWS_LOG_00258]. Cada um desses métodos retorna uma referência para *this.
3. Preenchimento de dados: dados úteis são gravados no buffer interno por meio de operadores sobrecarregados operator<<. A interface suporta tipos padrão como valores booleanos [SWS_LOG_00040], inteiros de diferentes larguras [SWS_LOG_00041], [SWS_LOG_00044], números de ponto flutuante [SWS_LOG_00049], cadeias de caracteres e visualizações de string [SWS_LOG_00051], [SWS_LOG_00062], sequências de bytes via core::Span<const core::Byte> [SWS_LOG_00128], bem como argumentos estruturados via Argument<T> [SWS_LOG_00203]. Além disso, o operador pode ser estendido para tipos definidos pelo usuário.
4. Entrega ao framework: ao sair do escopo, o destrutor encaminha a mensagem [SWS_LOG_00262]. Caso a instância deva permanecer para mensagens adicionais, Flush() é chamado explicitamente [SWS_LOG_00039].

Diagrama de sequência: fluxo de um registro em log desde a criação da stream passando pelo preenchimento de metadados e dados até o envio via fim de escopo ou Flush(). Fontes: [SWS_LOG_00039], [SWS_LOG_00040], [SWS_LOG_00129], [SWS_LOG_00176], [SWS_LOG_00262]

Cenários de erro

A classe segue um rigoroso design sem exceções (no-exception design). Todas as funções-membro, incluindo os operadores de stream ([SWS_LOG_00040] a [SWS_LOG_00051], [SWS_LOG_00062], [SWS_LOG_00128], [SWS_LOG_00203]), WithLocation() [SWS_LOG_00129], WithTag() [SWS_LOG_00132], WithPrivacy() [SWS_LOG_00258], Flush() [SWS_LOG_00039] e o destrutor [SWS_LOG_00262], são declaradas como noexcept e seguras contra exceções ("exception safe").

Condições de erro e riscos de utilização limitam-se aos seguintes cenários:

• Erro de tipo em WithPrivacy: o template WithPrivacy<T> exige obrigatoriamente que T seja um tipo integral ou um tipo de enumeração. Se a função for instanciada com um tipo divergente, o programa é malformado (ill-formed) e leva a um erro de compilação [SWS_LOG_00258]. Além disso, apenas os 8 bits menos significativos do valor passado são utilizados; os bits mais significativos são ignorados [SWS_LOG_00258].
• Ausência de thread safety: como LogStream é definido como não thread-safe ([SWS_LOG_00039], [SWS_LOG_00040]), operações concorrentes de leitura ou escrita na mesma instância sem sincronização externa provavelmente levarão a inconsistências de dados ou corrupção do buffer (interpretação). Pergunta Q-30a5037999c96fa2 (aberta)
• Transferência do buffer no Flush: como Flush() não esvazia fisicamente o buffer, mas apenas entrega o conteúdo atual ao framework de logging [SWS_LOG_00039], deve-se considerar, na reutilização, que semanticamente é iniciada uma nova mensagem.