gui_logging.h

Go to the documentation of this file.

#pragma once
 
// Structured logging (engine design docs 02 and 28): each message is a fixed-size
// record - category, severity, a static message template with `{}` placeholders and
// up to kMaxLogArgs typed arguments. Formatting happens lazily, at the sink.
//
// Records land in an in-memory ring of recent history (read by the editor's console,
// newest-last, with a sequence number for incremental reads) and are handed to every
// registered sink. A built-in console sink mirrors them to stdout / stderr and, on
// Windows, the debugger output.
//
// Emitting never allocates: text arguments are copied into the record's own fixed
// buffer (truncated if they don't fit), so dynamic strings such as file paths are safe
// to pass. The message template and category name must be static strings.
 
#include <stdint.h>
#include <span>
#include <string_view>
#include <type_traits>
 
#include <gui_core/gui_hash.h>
 
namespace tachyon::Diagnostics
{
 
    enum class LogSeverity : uint8_t { Trace = 0, Debug, Info, Warning, Error, Critical };
 
    const char* LogSeverityName(LogSeverity severity);

    struct LogCategory
    {
        uint64_t         id   = 0;    
        std::string_view name;        
    };

    constexpr LogCategory MakeLogCategory(std::string_view staticName)
    {
        return { Hash::CalculateConst(staticName), staticName };
    }

    struct LogArg
    {
        enum class Kind : uint8_t { None = 0, Int, Uint, Float, Text };
 
        Kind kind = Kind::None;   
        union
        {
            int64_t  i = 0;
            uint64_t u;
            double   f;
        };
        std::string_view text;            
        uint16_t         textOffset = 0; 
        uint16_t         textLength = 0; 
    };
 
    template<typename T>
    LogArg MakeLogArg(const T& value)
    {
        LogArg arg;
        if constexpr (std::is_same_v<T, bool>)
        {
            arg.kind = LogArg::Kind::Text;
            arg.text = value ? "true" : "false";
        }
        else if constexpr (std::is_enum_v<T>)
        {
            arg.kind = LogArg::Kind::Int;
            arg.i    = static_cast<int64_t>(value);
        }
        else if constexpr (std::is_integral_v<T> && std::is_signed_v<T>)
        {
            arg.kind = LogArg::Kind::Int;
            arg.i    = value;
        }
        else if constexpr (std::is_integral_v<T>)
        {
            arg.kind = LogArg::Kind::Uint;
            arg.u    = value;
        }
        else if constexpr (std::is_floating_point_v<T>)
        {
            arg.kind = LogArg::Kind::Float;
            arg.f    = static_cast<double>(value);
        }
        else
        {
            static_assert(std::is_convertible_v<const T&, std::string_view>, "unsupported log argument type");
            arg.kind = LogArg::Kind::Text;
            arg.text = std::string_view(value);
        }
        return arg;
    }
 
    inline constexpr int kMaxLogArgs        = 4;
    inline constexpr int kLogTextCapacity   = 384; 
    inline constexpr int kLogRingCapacity   = 1024;
    inline constexpr int kMaxLogSinks       = 8;

    struct LogRecord
    {
        uint64_t         sequence       = 0; 
        int64_t          timestampNanos = 0; 
        uint64_t         threadId       = 0; 
        LogCategory      category;           
        LogSeverity      severity       = LogSeverity::Info; 
        std::string_view messageTemplate;    
        const char*      file           = ""; 
        uint32_t         line           = 0; 
        uint8_t          argCount       = 0; 
        LogArg           args[kMaxLogArgs];  
        char             text[kLogTextCapacity]; 
    };
 
    std::string_view LogArgText(const LogRecord& record, const LogArg& arg);

    size_t FormatLogMessage(const LogRecord& record, std::span<char> out);

    void        SetMinimumLogSeverity(LogSeverity severity);
    LogSeverity GetMinimumLogSeverity();

    void SetLogConsoleOutput(bool enabled);

    using LogSinkFn = void (*)(const LogRecord& record, void* context);
    bool AddLogSink(LogSinkFn sink, void* context);
    void RemoveLogSink(LogSinkFn sink, void* context);

    void LogMessage(LogCategory category, LogSeverity severity, std::string_view messageTemplate,
                    std::span<const LogArg> args, const char* file = "", uint32_t line = 0);

    void ReportMisuse(LogCategory category, const char* message);
    void ResetMisuseReports();

    uint64_t LatestLogSequence();

    uint32_t CopyRecentLogRecords(std::span<LogRecord> out);

    template<typename... Args>
    void Log(LogCategory category, LogSeverity severity, const char* file, uint32_t line,
             std::string_view messageTemplate, const Args&... args)
    {
        static_assert(sizeof...(Args) <= kMaxLogArgs, "too many log arguments");
        if (severity < GetMinimumLogSeverity())
            return;
        const LogArg packed[sizeof...(Args) + 1] = { MakeLogArg(args)..., LogArg{} };
        LogMessage(category, severity, messageTemplate, std::span<const LogArg>(packed, sizeof...(Args)), file, line);
    }

}
 
#define TACHYON_LOG_TRACE(category, ...)    ::tachyon::Diagnostics::Log(category, ::tachyon::Diagnostics::LogSeverity::Trace,    __FILE__, __LINE__, __VA_ARGS__)
#define TACHYON_LOG_DEBUG(category, ...)    ::tachyon::Diagnostics::Log(category, ::tachyon::Diagnostics::LogSeverity::Debug,    __FILE__, __LINE__, __VA_ARGS__)
#define TACHYON_LOG_INFO(category, ...)     ::tachyon::Diagnostics::Log(category, ::tachyon::Diagnostics::LogSeverity::Info,     __FILE__, __LINE__, __VA_ARGS__)
#define TACHYON_LOG_WARNING(category, ...)  ::tachyon::Diagnostics::Log(category, ::tachyon::Diagnostics::LogSeverity::Warning,  __FILE__, __LINE__, __VA_ARGS__)
#define TACHYON_LOG_ERROR(category, ...)    ::tachyon::Diagnostics::Log(category, ::tachyon::Diagnostics::LogSeverity::Error,    __FILE__, __LINE__, __VA_ARGS__)
#define TACHYON_LOG_CRITICAL(category, ...) ::tachyon::Diagnostics::Log(category, ::tachyon::Diagnostics::LogSeverity::Critical, __FILE__, __LINE__, __VA_ARGS__)