62 lines
1.9 KiB
Markdown
62 lines
1.9 KiB
Markdown
# FileLogSink
|
|
|
|
**命名空间**: `XCEngine::Debug`
|
|
|
|
**类型**: `class`
|
|
|
|
**头文件**: `XCEngine/Debug/FileLogSink.h`
|
|
|
|
**描述**: 将日志追加写入文件，并在失败时回退到 `stderr`。
|
|
|
|
## 概述
|
|
|
|
`FileLogSink` 负责把 `LogEntry` 序列化成文本并落盘。它适合编辑器、集成测试和长时间运行的工具程序，因为这类场景通常需要保留会话级日志以便复盘。
|
|
|
|
当前实现中的关键行为：
|
|
|
|
- 构造时尝试以追加模式打开目标文件。
|
|
- 每次写入后立即 `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` 写入文件。
|
|
|
|
## 公开方法
|
|
|
|
| 方法 | 说明 |
|
|
|------|------|
|
|
| [Constructor](Constructor.md) | 构造文件日志 sink。 |
|
|
| [Destructor](Destructor.md) | 析构 sink 并关闭文件。 |
|
|
| [Log](Log.md) | 将日志条目写入文件。 |
|
|
| [Flush](Flush.md) | 刷新底层文件。 |
|
|
|
|
## 相关文档
|
|
|
|
- [当前模块](../Debug.md)
|
|
- [Logger](../Logger/Logger.md)
|
|
- [ILogSink](../ILogSink/ILogSink.md)
|
|
- [Logging Architecture](../../../_guides/Debug/Logging-Architecture.md)
|