docs: rebuild Debug API content
This commit is contained in:
@@ -1,31 +1,43 @@
|
||||
# Logger::AddSink
|
||||
|
||||
添加元素或建立关联。
|
||||
把一个日志输出目标注册到全局 `Logger`。
|
||||
|
||||
```cpp
|
||||
void AddSink(std::unique_ptr<ILogSink> sink);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/Logger.h`，当前页面用于固定 `Logger` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `sink` - 参数语义详见头文件声明。
|
||||
当前实现会在互斥区内把 `sink` 移入内部 `std::vector<std::unique_ptr<ILogSink>>`。注册后：
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
- `Logger` 接管对象生命周期。
|
||||
- 之后的每次 `Log` 都会把日志分发给该 sink。
|
||||
- 不会因为未初始化而失败；`AddSink` 本身不依赖 `Initialize`。
|
||||
|
||||
**示例：**
|
||||
## 参数
|
||||
|
||||
- `sink` - 新的日志输出目标，所有权会转移给 `Logger`。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 当前实现对 sink 列表写入加锁。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/Logger.h>
|
||||
using namespace XCEngine::Debug;
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::Logger object;
|
||||
// 根据上下文补齐参数后调用 Logger::AddSink(...)。
|
||||
(void)object;
|
||||
}
|
||||
Logger::Get().Initialize();
|
||||
Logger::Get().AddSink(std::make_unique<ConsoleLogSink>());
|
||||
Logger::Get().AddSink(std::make_unique<FileLogSink>("engine.log"));
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Logger.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](Logger.md)
|
||||
- [RemoveSink](RemoveSink.md)
|
||||
- [ILogSink](../ILogSink/ILogSink.md)
|
||||
|
||||
@@ -1,32 +1,46 @@
|
||||
# Logger::Debug
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
以 `Debug` 级别记录一条日志。
|
||||
|
||||
```cpp
|
||||
void Debug(LogCategory category, const Containers::String& message);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/Logger.h`，当前页面用于固定 `Logger` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `category` - 参数语义详见头文件声明。
|
||||
- `message` - 参数语义详见头文件声明。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
|
||||
**示例：**
|
||||
这是 `Logger::Log` 的便捷封装，等价于：
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/Logger.h>
|
||||
Log(LogLevel::Debug, category, message);
|
||||
```
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::Logger object;
|
||||
// 根据上下文补齐参数后调用 Logger::Debug(...)。
|
||||
(void)object;
|
||||
}
|
||||
它不会自动填充 `file`、`line` 或 `function`。如果你需要源码位置，请改用 `XE_LOG` 宏或直接调用 `Log` 的完整签名。
|
||||
|
||||
## 参数
|
||||
|
||||
- `category` - 日志分类。
|
||||
- `message` - 日志文本。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 与 [Log](Log.md) 相同。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
XCEngine::Debug::Logger::Get().Debug(
|
||||
XCEngine::Debug::LogCategory::Rendering,
|
||||
"Pipeline state updated"
|
||||
);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Logger.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](Logger.md)
|
||||
- [Log](Log.md)
|
||||
- [Verbose](Verbose.md)
|
||||
- [Info](Info.md)
|
||||
|
||||
@@ -1,32 +1,45 @@
|
||||
# Logger::Error
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
以 `Error` 级别记录一条日志。
|
||||
|
||||
```cpp
|
||||
void Error(LogCategory category, const Containers::String& message);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/Logger.h`，当前页面用于固定 `Logger` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `category` - 参数语义详见头文件声明。
|
||||
- `message` - 参数语义详见头文件声明。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
|
||||
**示例：**
|
||||
这是 `Logger::Log` 的便捷封装，等价于：
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/Logger.h>
|
||||
Log(LogLevel::Error, category, message);
|
||||
```
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::Logger object;
|
||||
// 根据上下文补齐参数后调用 Logger::Error(...)。
|
||||
(void)object;
|
||||
}
|
||||
当前实现只记录错误，不会抛异常或改变控制流。
|
||||
|
||||
## 参数
|
||||
|
||||
- `category` - 日志分类。
|
||||
- `message` - 错误文本。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 与 [Log](Log.md) 相同。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
XCEngine::Debug::Logger::Get().Error(
|
||||
XCEngine::Debug::LogCategory::FileSystem,
|
||||
"Failed to open asset file"
|
||||
);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Logger.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](Logger.md)
|
||||
- [Log](Log.md)
|
||||
- [Fatal](Fatal.md)
|
||||
|
||||
@@ -1,32 +1,45 @@
|
||||
# Logger::Fatal
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
以 `Fatal` 级别记录一条日志。
|
||||
|
||||
```cpp
|
||||
void Fatal(LogCategory category, const Containers::String& message);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/Logger.h`，当前页面用于固定 `Logger` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `category` - 参数语义详见头文件声明。
|
||||
- `message` - 参数语义详见头文件声明。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
|
||||
**示例：**
|
||||
这是 `Logger::Log` 的便捷封装，等价于：
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/Logger.h>
|
||||
Log(LogLevel::Fatal, category, message);
|
||||
```
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::Logger object;
|
||||
// 根据上下文补齐参数后调用 Logger::Fatal(...)。
|
||||
(void)object;
|
||||
}
|
||||
需要特别注意：在当前版本中，`Fatal` 只是最高严重级别的日志，不会自动终止程序、触发断言中断或抛出异常。`XE_ASSERT` 也是基于这个行为实现的。
|
||||
|
||||
## 参数
|
||||
|
||||
- `category` - 日志分类。
|
||||
- `message` - 致命错误文本。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 与 [Log](Log.md) 相同。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
XCEngine::Debug::Logger::Get().Fatal(
|
||||
XCEngine::Debug::LogCategory::General,
|
||||
"Unexpected unrecoverable state"
|
||||
);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Logger.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](Logger.md)
|
||||
- [Log](Log.md)
|
||||
- [Error](Error.md)
|
||||
|
||||
@@ -1,29 +1,44 @@
|
||||
# Logger::Get
|
||||
|
||||
获取相关状态或对象。
|
||||
获取进程级全局 `Logger` 实例。
|
||||
|
||||
```cpp
|
||||
static Logger& Get();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/Logger.h`，当前页面用于固定 `Logger` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
|
||||
**返回：** `Logger&` - 返回值语义详见头文件声明。
|
||||
|
||||
**示例：**
|
||||
当前实现使用函数内静态对象保存单例：
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/Logger.h>
|
||||
static Logger instance;
|
||||
```
|
||||
|
||||
void Example() {
|
||||
auto& instance = XCEngine::Debug::Logger::Get();
|
||||
(void)instance;
|
||||
}
|
||||
因此：
|
||||
|
||||
- 你拿到的是同一个 `Logger` 实例引用。
|
||||
- 该方法本身不会自动初始化 sink，也不会重置过滤配置。
|
||||
|
||||
## 参数
|
||||
|
||||
- 无。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `Logger&` - 全局日志分发器引用。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- C++ 对函数内静态对象初始化提供线程安全保证，但 `Logger` 的后续配置和使用仍需遵守各自方法的线程语义。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
XCEngine::Debug::Logger& logger = XCEngine::Debug::Logger::Get();
|
||||
logger.Initialize();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Logger.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](Logger.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,32 +1,45 @@
|
||||
# Logger::Info
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
以 `Info` 级别记录一条日志。
|
||||
|
||||
```cpp
|
||||
void Info(LogCategory category, const Containers::String& message);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/Logger.h`，当前页面用于固定 `Logger` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `category` - 参数语义详见头文件声明。
|
||||
- `message` - 参数语义详见头文件声明。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
|
||||
**示例：**
|
||||
这是 `Logger::Log` 的便捷封装，等价于：
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/Logger.h>
|
||||
Log(LogLevel::Info, category, message);
|
||||
```
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::Logger object;
|
||||
// 根据上下文补齐参数后调用 Logger::Info(...)。
|
||||
(void)object;
|
||||
}
|
||||
它适合记录重要但正常的运行事件，例如启动完成、资源路径、当前设备信息等。
|
||||
|
||||
## 参数
|
||||
|
||||
- `category` - 日志分类。
|
||||
- `message` - 日志文本。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 与 [Log](Log.md) 相同。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
XCEngine::Debug::Logger::Get().Info(
|
||||
XCEngine::Debug::LogCategory::General,
|
||||
"Editor Application starting..."
|
||||
);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Logger.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](Logger.md)
|
||||
- [Log](Log.md)
|
||||
- [Warning](Warning.md)
|
||||
|
||||
@@ -1,30 +1,49 @@
|
||||
# Logger::Initialize
|
||||
|
||||
初始化内部状态。
|
||||
把 `Logger` 标记为已初始化。
|
||||
|
||||
```cpp
|
||||
void Initialize();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/Logger.h`，当前页面用于固定 `Logger` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前实现是幂等的：
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
- 如果已经初始化，直接返回。
|
||||
- 如果尚未初始化，仅把内部 `m_initialized` 设为 `true`。
|
||||
|
||||
**示例：**
|
||||
它不会做以下事情：
|
||||
|
||||
- 不会添加默认 sink。
|
||||
- 不会清空已有 sink。
|
||||
- 不会重置最小级别或 category 开关。
|
||||
|
||||
因此，推荐把它理解为“进入可用状态”的轻量标记，而不是完整的日志系统自举流程。
|
||||
|
||||
## 参数
|
||||
|
||||
- 无。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 当前实现没有显式同步初始化流程；如果多线程首次同时写日志，`Log` 的自动初始化路径虽然通常能工作，但仍建议在启动阶段显式调用一次。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/Logger.h>
|
||||
using namespace XCEngine::Debug;
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::Logger object;
|
||||
// 根据上下文补齐参数后调用 Logger::Initialize(...)。
|
||||
(void)object;
|
||||
}
|
||||
Logger::Get().Initialize();
|
||||
Logger::Get().AddSink(std::make_unique<ConsoleLogSink>());
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Logger.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](Logger.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
- [Log](Log.md)
|
||||
|
||||
@@ -1,36 +1,77 @@
|
||||
# Logger::Log
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
构造一条 `LogEntry` 并把它分发给所有已注册 sink。
|
||||
|
||||
```cpp
|
||||
void Log(LogLevel level, LogCategory category, const Containers::String& message, const char* file = nullptr, int32_t line = 0, const char* function = nullptr);
|
||||
void Log(
|
||||
LogLevel level,
|
||||
LogCategory category,
|
||||
const Containers::String& message,
|
||||
const char* file = nullptr,
|
||||
int32_t line = 0,
|
||||
const char* function = nullptr
|
||||
);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/Logger.h`，当前页面用于固定 `Logger` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `level` - 参数语义详见头文件声明。
|
||||
- `category` - 参数语义详见头文件声明。
|
||||
- `message` - 参数语义详见头文件声明。
|
||||
- `file` - 参数语义详见头文件声明。
|
||||
- `line` - 参数语义详见头文件声明。
|
||||
- `function` - 参数语义详见头文件声明。
|
||||
当前实现依次执行以下步骤：
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
1. 如果 `Logger` 尚未初始化，先调用 `Initialize()`。
|
||||
2. 如果 `level < m_minimumLevel`，直接丢弃日志。
|
||||
3. 如果 category 对应的启用位为关闭状态，直接丢弃日志。
|
||||
4. 构造 `LogEntry`，填充：
|
||||
- `level`
|
||||
- `category`
|
||||
- `message`
|
||||
- `file`
|
||||
- `line`
|
||||
- `function`
|
||||
- 当前秒级时间戳
|
||||
- 当前线程哈希值
|
||||
5. 在互斥区内遍历所有 sink 并调用其 `Log(entry)`。
|
||||
|
||||
**示例：**
|
||||
需要注意：
|
||||
|
||||
- 如果没有注册任何 sink，日志会被静默丢弃。
|
||||
- 当前时间戳粒度是“秒”，不是毫秒或微秒。
|
||||
- 当前线程 ID 是哈希结果，不保证与系统线程号一致。
|
||||
|
||||
## 参数
|
||||
|
||||
- `level` - 日志级别。
|
||||
- `category` - 日志分类。
|
||||
- `message` - 日志文本。
|
||||
- `file` - 可选的源文件路径。
|
||||
- `line` - 可选的源码行号。
|
||||
- `function` - 可选的函数名。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- sink 分发过程在互斥区内执行。
|
||||
- `SetMinimumLevel` 和 `SetCategoryEnabled` 当前无锁，因此在高并发日志期间动态修改配置时要自行承担竞争风险。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/Logger.h>
|
||||
using namespace XCEngine::Debug;
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::Logger object;
|
||||
// 根据上下文补齐参数后调用 Logger::Log(...)。
|
||||
(void)object;
|
||||
}
|
||||
Logger::Get().Log(
|
||||
LogLevel::Warning,
|
||||
LogCategory::General,
|
||||
"Fallback code path selected",
|
||||
__FILE__,
|
||||
__LINE__,
|
||||
__FUNCTION__
|
||||
);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Logger.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](Logger.md)
|
||||
- [Verbose](Verbose.md)
|
||||
- [XE_LOG 宏所在类型页](Logger.md)
|
||||
|
||||
@@ -6,38 +6,79 @@
|
||||
|
||||
**头文件**: `XCEngine/Debug/Logger.h`
|
||||
|
||||
**描述**: 定义 `XCEngine/Debug` 子目录中的 `Logger` public API。
|
||||
**描述**: 构造日志记录、应用全局过滤并把日志分发到多个 sink。
|
||||
|
||||
## 概述
|
||||
|
||||
`Logger.h` 是 `XCEngine/Debug` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
|
||||
`Logger` 是 XCEngine 当前日志系统的中心节点。业务代码、测试程序和工具层并不直接操作控制台或文件，而是先把消息交给 `Logger`，再由它把统一格式的 `LogEntry` 分发给已注册的 `ILogSink`。
|
||||
|
||||
## 声明概览
|
||||
这类设计的好处是：
|
||||
|
||||
| 声明 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `Logger` | `class` | 头文件中的公开声明。 |
|
||||
- 输出目标可以随运行环境变化，而业务日志调用点保持不变。
|
||||
- 全局级别过滤和 category 开关只需要维护一份。
|
||||
- 可以在编辑器、命令行测试和文件日志之间复用同一条日志链路。
|
||||
|
||||
## 公共方法
|
||||
## 生命周期
|
||||
|
||||
| 方法 | 描述 |
|
||||
- [Get](Get.md) 返回进程级单例。
|
||||
- [Initialize](Initialize.md) 只设置初始化标志，不会自动添加默认 sink。
|
||||
- [Shutdown](Shutdown.md) 会 `Flush` 所有 sink 并清空 sink 列表。
|
||||
- [Log](Log.md) 在第一次被调用时会自动调用 `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](Get.md) | 获取相关状态或对象。 |
|
||||
| [Initialize](Initialize.md) | 初始化内部状态。 |
|
||||
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
|
||||
| [AddSink](AddSink.md) | 添加元素或建立关联。 |
|
||||
| [RemoveSink](RemoveSink.md) | 移除元素或解除关联。 |
|
||||
| [Log](Log.md) | 公开方法，详见头文件声明。 |
|
||||
| [Verbose](Verbose.md) | 公开方法，详见头文件声明。 |
|
||||
| [Debug](Debug.md) | 公开方法，详见头文件声明。 |
|
||||
| [Info](Info.md) | 公开方法，详见头文件声明。 |
|
||||
| [Warning](Warning.md) | 公开方法，详见头文件声明。 |
|
||||
| [Error](Error.md) | 公开方法，详见头文件声明。 |
|
||||
| [Fatal](Fatal.md) | 公开方法，详见头文件声明。 |
|
||||
| [SetMinimumLevel](SetMinimumLevel.md) | 设置相关状态或配置。 |
|
||||
| [SetCategoryEnabled](SetCategoryEnabled.md) | 设置相关状态或配置。 |
|
||||
| [Get](Get.md) | 获取全局 `Logger` 实例。 |
|
||||
| [Initialize](Initialize.md) | 初始化日志系统状态。 |
|
||||
| [Shutdown](Shutdown.md) | 刷新并移除所有 sink。 |
|
||||
| [AddSink](AddSink.md) | 注册一个新的日志输出目标。 |
|
||||
| [RemoveSink](RemoveSink.md) | 根据原始指针移除 sink。 |
|
||||
| [Log](Log.md) | 构造 `LogEntry` 并分发到所有 sink。 |
|
||||
| [Verbose](Verbose.md) | 发送 `Verbose` 级日志。 |
|
||||
| [Debug](Debug.md) | 发送 `Debug` 级日志。 |
|
||||
| [Info](Info.md) | 发送 `Info` 级日志。 |
|
||||
| [Warning](Warning.md) | 发送 `Warning` 级日志。 |
|
||||
| [Error](Error.md) | 发送 `Error` 级日志。 |
|
||||
| [Fatal](Fatal.md) | 发送 `Fatal` 级日志。 |
|
||||
| [SetMinimumLevel](SetMinimumLevel.md) | 设置全局最小日志级别。 |
|
||||
| [SetCategoryEnabled](SetCategoryEnabled.md) | 打开或关闭某个日志分类。 |
|
||||
|
||||
## 真实使用位置
|
||||
|
||||
当前代码库中，`Logger` 已经被用于：
|
||||
|
||||
- 编辑器启动流程，为控制台、编辑器面板和文件同时输出日志。
|
||||
- RHI 集成测试，为控制台和文件记录帧调试信息。
|
||||
- `RenderDocCapture`、截图工具和资源管理等低层模块的错误与警告输出。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [当前目录](../Debug.md) - 返回 `Debug` 平行目录
|
||||
- [API 总索引](../../../main.md) - 返回顶层索引
|
||||
- [当前模块](../Debug.md)
|
||||
- [ILogSink](../ILogSink/ILogSink.md)
|
||||
- [ConsoleLogSink](../ConsoleLogSink/ConsoleLogSink.md)
|
||||
- [FileLogSink](../FileLogSink/FileLogSink.md)
|
||||
- [LogEntry](../LogEntry/LogEntry.md)
|
||||
- [Logging Architecture](../../../_guides/Debug/Logging-Architecture.md)
|
||||
|
||||
@@ -1,31 +1,47 @@
|
||||
# Logger::RemoveSink
|
||||
|
||||
移除元素或解除关联。
|
||||
按原始指针移除一个已注册的 sink。
|
||||
|
||||
```cpp
|
||||
void RemoveSink(ILogSink* sink);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/Logger.h`，当前页面用于固定 `Logger` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `sink` - 参数语义详见头文件声明。
|
||||
当前实现会在互斥区内线性扫描 sink 列表，找到第一个 `it->get() == sink` 的元素后将其删除并停止遍历。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
删除后：
|
||||
|
||||
**示例：**
|
||||
- sink 对象会立刻析构。
|
||||
- 对应指针立即失效。
|
||||
|
||||
如果传入空指针或未找到匹配项，当前实现会静默返回。
|
||||
|
||||
## 参数
|
||||
|
||||
- `sink` - 之前注册到 `Logger` 的 sink 原始指针。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 当前实现对移除操作加锁。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/Logger.h>
|
||||
using namespace XCEngine::Debug;
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::Logger object;
|
||||
// 根据上下文补齐参数后调用 Logger::RemoveSink(...)。
|
||||
(void)object;
|
||||
}
|
||||
auto sink = std::make_unique<ConsoleLogSink>();
|
||||
ConsoleLogSink* sinkPtr = sink.get();
|
||||
|
||||
Logger::Get().AddSink(std::move(sink));
|
||||
Logger::Get().RemoveSink(sinkPtr);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Logger.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](Logger.md)
|
||||
- [AddSink](AddSink.md)
|
||||
|
||||
@@ -1,32 +1,43 @@
|
||||
# Logger::SetCategoryEnabled
|
||||
|
||||
设置相关状态或配置。
|
||||
打开或关闭某个日志分类。
|
||||
|
||||
```cpp
|
||||
void SetCategoryEnabled(LogCategory category, bool enabled);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/Logger.h`，当前页面用于固定 `Logger` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `category` - 参数语义详见头文件声明。
|
||||
- `enabled` - 参数语义详见头文件声明。
|
||||
当前实现会把 `category` 对应的启用位直接写入内部数组。之后所有 `Log` 调用都会先检查这个开关，再决定是否分发该分类日志。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
这是一种非常轻量的 category 过滤方式，但也意味着：
|
||||
|
||||
**示例：**
|
||||
- 当前实现没有加锁。
|
||||
- 枚举值数量与数组长度耦合。
|
||||
|
||||
## 参数
|
||||
|
||||
- `category` - 需要开关的日志分类。
|
||||
- `enabled` - `true` 表示启用，`false` 表示禁用。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 建议在初始化阶段配置，而不是在多个线程持续写日志时频繁修改。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/Logger.h>
|
||||
using namespace XCEngine::Debug;
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::Logger object;
|
||||
// 根据上下文补齐参数后调用 Logger::SetCategoryEnabled(...)。
|
||||
(void)object;
|
||||
}
|
||||
Logger::Get().SetCategoryEnabled(LogCategory::Rendering, false);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Logger.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](Logger.md)
|
||||
- [SetMinimumLevel](SetMinimumLevel.md)
|
||||
- [LogCategory](../LogCategory/LogCategory.md)
|
||||
|
||||
@@ -1,31 +1,40 @@
|
||||
# Logger::SetMinimumLevel
|
||||
|
||||
设置相关状态或配置。
|
||||
设置全局日志分发的最小级别。
|
||||
|
||||
```cpp
|
||||
void SetMinimumLevel(LogLevel level);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/Logger.h`，当前页面用于固定 `Logger` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `level` - 参数语义详见头文件声明。
|
||||
当前实现直接把内部 `m_minimumLevel` 赋值为 `level`。之后所有 `Log` 调用都会先比较 `entry.level < m_minimumLevel`，不满足要求的日志在构造 sink 输出前就会被丢弃。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
这属于全局过滤；sink 仍然可以在此基础上继续做自己的本地过滤。
|
||||
|
||||
**示例：**
|
||||
## 参数
|
||||
|
||||
- `level` - 允许继续分发的最低级别。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 当前实现没有加锁。
|
||||
- 更适合作为启动配置，而不是高频运行时热更新项。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/Logger.h>
|
||||
using namespace XCEngine::Debug;
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::Logger object;
|
||||
// 根据上下文补齐参数后调用 Logger::SetMinimumLevel(...)。
|
||||
(void)object;
|
||||
}
|
||||
Logger::Get().SetMinimumLevel(LogLevel::Warning);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Logger.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](Logger.md)
|
||||
- [SetCategoryEnabled](SetCategoryEnabled.md)
|
||||
- [ConsoleLogSink::SetMinimumLevel](../ConsoleLogSink/SetMinimumLevel.md)
|
||||
|
||||
@@ -1,30 +1,45 @@
|
||||
# Logger::Shutdown
|
||||
|
||||
关闭并清理内部状态。
|
||||
刷新并移除所有已注册 sink。
|
||||
|
||||
```cpp
|
||||
void Shutdown();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/Logger.h`，当前页面用于固定 `Logger` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前实现依次做三件事：
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
1. 遍历所有 sink 并调用 `Flush()`。
|
||||
2. 清空 sink 列表。
|
||||
3. 把 `m_initialized` 设回 `false`。
|
||||
|
||||
**示例：**
|
||||
需要特别注意：
|
||||
|
||||
- 当前不会重置 `m_minimumLevel`。
|
||||
- 当前不会重置 category 启用表。
|
||||
- 当前没有在锁内执行整个关闭流程，因此应在受控停机阶段调用。
|
||||
|
||||
## 参数
|
||||
|
||||
- 无。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 请在其它线程不再调用 `Log` 后执行 `Shutdown`。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/Logger.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::Logger object;
|
||||
// 根据上下文补齐参数后调用 Logger::Shutdown(...)。
|
||||
(void)object;
|
||||
}
|
||||
XCEngine::Debug::Logger::Get().Shutdown();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Logger.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](Logger.md)
|
||||
- [Initialize](Initialize.md)
|
||||
- [AddSink](AddSink.md)
|
||||
|
||||
@@ -1,32 +1,45 @@
|
||||
# Logger::Verbose
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
以 `Verbose` 级别记录一条日志。
|
||||
|
||||
```cpp
|
||||
void Verbose(LogCategory category, const Containers::String& message);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/Logger.h`，当前页面用于固定 `Logger` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `category` - 参数语义详见头文件声明。
|
||||
- `message` - 参数语义详见头文件声明。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
|
||||
**示例：**
|
||||
这是 `Logger::Log` 的便捷封装，等价于：
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/Logger.h>
|
||||
Log(LogLevel::Verbose, category, message);
|
||||
```
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::Logger object;
|
||||
// 根据上下文补齐参数后调用 Logger::Verbose(...)。
|
||||
(void)object;
|
||||
}
|
||||
适合输出高频、细粒度的开发期调试信息。默认不带源码位置信息。
|
||||
|
||||
## 参数
|
||||
|
||||
- `category` - 日志分类。
|
||||
- `message` - 日志文本。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 与 [Log](Log.md) 相同。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
XCEngine::Debug::Logger::Get().Verbose(
|
||||
XCEngine::Debug::LogCategory::Threading,
|
||||
"Worker thread woke up"
|
||||
);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Logger.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](Logger.md)
|
||||
- [Log](Log.md)
|
||||
- [Debug](Debug.md)
|
||||
|
||||
@@ -1,32 +1,45 @@
|
||||
# Logger::Warning
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
以 `Warning` 级别记录一条日志。
|
||||
|
||||
```cpp
|
||||
void Warning(LogCategory category, const Containers::String& message);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/Logger.h`，当前页面用于固定 `Logger` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `category` - 参数语义详见头文件声明。
|
||||
- `message` - 参数语义详见头文件声明。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
|
||||
**示例：**
|
||||
这是 `Logger::Log` 的便捷封装，等价于：
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/Logger.h>
|
||||
Log(LogLevel::Warning, category, message);
|
||||
```
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::Logger object;
|
||||
// 根据上下文补齐参数后调用 Logger::Warning(...)。
|
||||
(void)object;
|
||||
}
|
||||
它适合记录“当前还能继续运行，但状态值得关注”的情况。
|
||||
|
||||
## 参数
|
||||
|
||||
- `category` - 日志分类。
|
||||
- `message` - 警告文本。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 与 [Log](Log.md) 相同。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
XCEngine::Debug::Logger::Get().Warning(
|
||||
XCEngine::Debug::LogCategory::General,
|
||||
"Created OpenGL context without debug bit"
|
||||
);
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](Logger.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](Logger.md)
|
||||
- [Log](Log.md)
|
||||
- [Error](Error.md)
|
||||
|
||||
Reference in New Issue
Block a user