3.7 KiB
3.7 KiB
Logger
命名空间: XCEngine::Debug
类型: class (singleton)
头文件: XCEngine/Debug/Logger.h
描述: 构造日志记录、应用全局过滤并把日志分发到多个 sink。
概述
Logger 是 XCEngine 当前日志系统的中心节点。业务代码、测试程序和工具层并不直接操作控制台或文件，而是先把消息交给 Logger，再由它把统一格式的 LogEntry 分发给已注册的 ILogSink。
这类设计的好处是：
- 输出目标可以随运行环境变化，而业务日志调用点保持不变。
- 全局级别过滤和 category 开关只需要维护一份。
- 可以在编辑器、命令行测试和文件日志之间复用同一条日志链路。
生命周期
- Get 返回进程级单例。
- Initialize 只设置初始化标志，不会自动添加默认 sink。
- Shutdown 会
Flush所有 sink 并清空 sink 列表。 - Log 在第一次被调用时会自动调用
Initialize。
推荐做法：
- 在程序启动阶段显式
Initialize并注册 sink。 - 在受控退出阶段调用
Shutdown，避免与其它线程仍在写日志时并发销毁。
线程语义
AddSink、RemoveSink和Log通过内部Mutex保护 sink 列表访问。SetMinimumLevel和SetCategoryEnabled当前没有加锁，更适合作为初始化阶段配置，而不是高频热更新开关。Shutdown当前也没有在锁内遍历 sink；应在其它线程不再写日志时调用。
所有权
AddSink接收std::unique_ptr<ILogSink>，所有权转移给Logger。RemoveSink只按裸指针匹配已注册对象；如果调用方未来需要移除某个 sink，必须在移交所有权前保留一份原始指针。
宏与便捷接口
XE_LOG(category, level, message)会把__FILE__、__LINE__和__FUNCTION__一并传给Logger::Log。XE_ASSERT(condition, message)在条件失败时只记录一条Fatal级别日志；当前实现不会中断程序、抛异常或触发调试断点。Verbose、Debug、Info、Warning、Error、Fatal都是Log的便捷封装，但默认不带源码位置信息。
公开方法
| 方法 | 说明 |
|---|---|
| Get | 获取全局 Logger 实例。 |
| Initialize | 初始化日志系统状态。 |
| Shutdown | 刷新并移除所有 sink。 |
| AddSink | 注册一个新的日志输出目标。 |
| RemoveSink | 根据原始指针移除 sink。 |
| Log | 构造 LogEntry 并分发到所有 sink。 |
| Verbose | 发送 Verbose 级日志。 |
| Debug | 发送 Debug 级日志。 |
| Info | 发送 Info 级日志。 |
| Warning | 发送 Warning 级日志。 |
| Error | 发送 Error 级日志。 |
| Fatal | 发送 Fatal 级日志。 |
| SetMinimumLevel | 设置全局最小日志级别。 |
| SetCategoryEnabled | 打开或关闭某个日志分类。 |
真实使用位置
当前代码库中，Logger 已经被用于：
- 编辑器启动流程，为控制台、编辑器面板和文件同时输出日志。
- RHI 集成测试，为控制台和文件记录帧调试信息。
RenderDocCapture、截图工具和资源管理等低层模块的错误与警告输出。