docs: rebuild Debug API content
This commit is contained in:
@@ -1,29 +1,36 @@
|
||||
# FileLogSink::FileLogSink()
|
||||
# FileLogSink::Constructor
|
||||
|
||||
构造对象。
|
||||
构造一个把日志追加写入文件的 sink。
|
||||
|
||||
```cpp
|
||||
FileLogSink(const Containers::String& filePath);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/FileLogSink.h`，当前页面用于固定 `FileLogSink` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `filePath` - 参数语义详见头文件声明。
|
||||
当前实现会保存 `filePath`，并立即尝试通过 `Core::FileWriter` 以追加模式打开该文件。即使第一次打开失败，对象仍然会保留路径，后续在 `Log` 时继续重试打开。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 参数
|
||||
|
||||
**示例：**
|
||||
- `filePath` - 日志文件路径。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 构造本身不加锁；通常在启动阶段创建并交给 `Logger` 持有。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/FileLogSink.h>
|
||||
using namespace XCEngine::Debug;
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::FileLogSink object;
|
||||
}
|
||||
Logger::Get().AddSink(std::make_unique<FileLogSink>("editor.log"));
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](FileLogSink.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](FileLogSink.md)
|
||||
- [Log](Log.md)
|
||||
|
||||
@@ -1,29 +1,34 @@
|
||||
# FileLogSink::~FileLogSink()
|
||||
# FileLogSink::Destructor
|
||||
|
||||
销毁对象并释放相关资源。
|
||||
销毁文件日志 sink 并关闭底层文件。
|
||||
|
||||
```cpp
|
||||
~FileLogSink() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/FileLogSink.h`，当前页面用于固定 `FileLogSink` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前实现直接调用 `m_writer.Close()`。如果该 sink 仍由 `Logger` 持有，通常会在 `Logger::Shutdown` 清空 sink 列表时自动触发析构。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 参数
|
||||
|
||||
**示例：**
|
||||
- 无。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 应在对象不再参与日志分发后销毁。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/FileLogSink.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::FileLogSink object;
|
||||
// 对象离开作用域时会自动触发析构。
|
||||
}
|
||||
XCEngine::Debug::Logger::Get().Shutdown();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](FileLogSink.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](FileLogSink.md)
|
||||
- [ILogSink::Destructor](../ILogSink/Destructor.md)
|
||||
|
||||
@@ -6,28 +6,56 @@
|
||||
|
||||
**头文件**: `XCEngine/Debug/FileLogSink.h`
|
||||
|
||||
**描述**: 定义 `XCEngine/Debug` 子目录中的 `FileLogSink` public API。
|
||||
**描述**: 将日志追加写入文件，并在失败时回退到 `stderr`。
|
||||
|
||||
## 概述
|
||||
|
||||
`FileLogSink.h` 是 `XCEngine/Debug` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
|
||||
`FileLogSink` 负责把 `LogEntry` 序列化成文本并落盘。它适合编辑器、集成测试和长时间运行的工具程序，因为这类场景通常需要保留会话级日志以便复盘。
|
||||
|
||||
## 声明概览
|
||||
当前实现中的关键行为：
|
||||
|
||||
| 声明 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `FileLogSink` | `class` | 继承自 `ILogSink` 的公开声明。 |
|
||||
- 构造时尝试以追加模式打开目标文件。
|
||||
- 每次写入后立即 `Flush`，优先保证可追溯性，而不是吞吐量。
|
||||
- 如果文件句柄不可用，会在 `Log` 时尝试重新打开。
|
||||
- 如果重新打开或写入失败，会把错误和原始日志内容写到 `stderr`。
|
||||
|
||||
## 公共方法
|
||||
## 生命周期
|
||||
|
||||
| 方法 | 描述 |
|
||||
- [Constructor](Constructor.md) 保存目标路径并尝试打开文件。
|
||||
- [Destructor](Destructor.md) 关闭底层 `FileWriter`。
|
||||
- [Flush](Flush.md) 将缓冲区刷到磁盘。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- `FileLogSink` 自身没有显式加锁。
|
||||
- 通过 `Logger` 使用时，调用会被 `Logger` 串行化。
|
||||
- 当前实现使用 `std::localtime` 生成时间文本；如果绕过 `Logger` 并发调用，线程安全性由调用方承担。
|
||||
|
||||
## 输出格式
|
||||
|
||||
当前实现输出格式为：
|
||||
|
||||
```text
|
||||
[YYYY-MM-DD HH:MM:SS] [LEVEL] [Category] message
|
||||
```
|
||||
|
||||
注意：
|
||||
|
||||
- 使用的是 `LogEntry::timestamp` 的本地时间表示。
|
||||
- 当前不会把 `file`、`line`、`function` 或 `threadId` 写入文件。
|
||||
|
||||
## 公开方法
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| [FileLogSink()](Constructor.md) | 构造对象。 |
|
||||
| [~FileLogSink()](Destructor.md) | 销毁对象并释放相关资源。 |
|
||||
| [Log](Log.md) | 公开方法，详见头文件声明。 |
|
||||
| [Flush](Flush.md) | 公开方法，详见头文件声明。 |
|
||||
| [Constructor](Constructor.md) | 构造文件日志 sink。 |
|
||||
| [Destructor](Destructor.md) | 析构 sink 并关闭文件。 |
|
||||
| [Log](Log.md) | 将日志条目写入文件。 |
|
||||
| [Flush](Flush.md) | 刷新底层文件。 |
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [当前目录](../Debug.md) - 返回 `Debug` 平行目录
|
||||
- [API 总索引](../../../main.md) - 返回顶层索引
|
||||
- [当前模块](../Debug.md)
|
||||
- [Logger](../Logger/Logger.md)
|
||||
- [ILogSink](../ILogSink/ILogSink.md)
|
||||
- [Logging Architecture](../../../_guides/Debug/Logging-Architecture.md)
|
||||
|
||||
@@ -1,30 +1,37 @@
|
||||
# FileLogSink::Flush
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
把底层文件缓冲区刷新到磁盘。
|
||||
|
||||
```cpp
|
||||
void Flush() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/FileLogSink.h`，当前页面用于固定 `FileLogSink` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：** 无。
|
||||
当前实现直接转发到 `Core::FileWriter::Flush()`。如果文件尚未成功打开，`FileWriter` 会返回 `false`，但 `FileLogSink::Flush` 本身不会上报错误。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
需要注意的是，当前 `FileLogSink::Log` 在每次写入后已经主动调用一次 `Flush`，因此手动调用更多是为了表达语义，而不是补齐缺失步骤。
|
||||
|
||||
**示例：**
|
||||
## 参数
|
||||
|
||||
- 无。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 通过 `Logger` 使用时通常是串行的。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/FileLogSink.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::FileLogSink object;
|
||||
// 根据上下文补齐参数后调用 FileLogSink::Flush(...)。
|
||||
(void)object;
|
||||
}
|
||||
XCEngine::Debug::FileLogSink sink("engine.log");
|
||||
sink.Flush();
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](FileLogSink.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](FileLogSink.md)
|
||||
- [Log](Log.md)
|
||||
|
||||
@@ -1,31 +1,51 @@
|
||||
# FileLogSink::Log
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
将日志条目写入文件，并在失败时回退到 `stderr`。
|
||||
|
||||
```cpp
|
||||
void Log(const LogEntry& entry) override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/Debug/FileLogSink.h`，当前页面用于固定 `FileLogSink` 类目录下的方法级 canonical 路径。
|
||||
## 行为说明
|
||||
|
||||
**参数：**
|
||||
- `entry` - 参数语义详见头文件声明。
|
||||
当前实现流程如下：
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
1. 如果文件未打开，先尝试按保存的路径重新打开。
|
||||
2. 如果打开失败，把错误和原始日志写到 `stderr`，然后返回。
|
||||
3. 把 `entry.timestamp` 按本地时间格式化为 `YYYY-MM-DD HH:MM:SS`。
|
||||
4. 以 `[时间] [级别] [分类] message` 的形式写入文件。
|
||||
5. 写入后立即 `Flush`。
|
||||
|
||||
**示例：**
|
||||
当前不会写入：
|
||||
|
||||
- `file`
|
||||
- `line`
|
||||
- `function`
|
||||
- `threadId`
|
||||
|
||||
## 参数
|
||||
|
||||
- `entry` - 待落盘的日志条目。
|
||||
|
||||
## 返回值
|
||||
|
||||
- 无。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- sink 自身无锁。
|
||||
- 通过 `Logger` 分发时为串行调用。
|
||||
|
||||
## 示例
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/Debug/FileLogSink.h>
|
||||
using namespace XCEngine::Debug;
|
||||
|
||||
void Example() {
|
||||
XCEngine::Debug::FileLogSink object;
|
||||
// 根据上下文补齐参数后调用 FileLogSink::Log(...)。
|
||||
(void)object;
|
||||
}
|
||||
Logger::Get().AddSink(std::make_unique<FileLogSink>("runtime.log"));
|
||||
Logger::Get().Info(LogCategory::General, "Runtime started");
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](FileLogSink.md)
|
||||
- [返回模块目录](../Debug.md)
|
||||
- [返回类型总览](FileLogSink.md)
|
||||
- [Flush](Flush.md)
|
||||
|
||||
Reference in New Issue
Block a user