66 lines
2.6 KiB
Markdown
66 lines
2.6 KiB
Markdown
# Profiler
|
|
|
|
**命名空间**: `XCEngine::Debug`
|
|
|
|
**类型**: `class (singleton)`
|
|
|
|
**头文件**: `XCEngine/Debug/Profiler.h`
|
|
|
|
**描述**: 提供轻量级 CPU 埋点入口，用于记录成对的 profile 区段。
|
|
|
|
## 概述
|
|
|
|
`Profiler` 的 API 形状明显面向“开发期埋点”和“后续时间线导出”场景，但当前实现仍处于非常早期的阶段。它已经能够记录一组成对的 `BeginProfile` / `EndProfile` 调用时长，却还没有提供读取样本、可视化时间线或导出 Chrome Trace 的完整工作流。
|
|
|
|
可以把它理解为：
|
|
|
|
- 设计方向上类似轻量版的引擎内 CPU 埋点器；
|
|
- 但当前能力远不等同于 Unity Profiler 这类成熟的分析器。
|
|
|
|
## 当前实现能力
|
|
|
|
- [BeginProfile](BeginProfile.md) / [EndProfile](EndProfile.md) 会把区段时长记录到内部样本数组。
|
|
- [BeginFrame](BeginFrame.md) 只记录一帧开始时间。
|
|
- [EndFrame](EndFrame.md) 当前会直接清空样本数组。
|
|
- [MarkEvent](MarkEvent.md)、[SetMarker](SetMarker.md) 和 [ExportChromeTracing](ExportChromeTracing.md) 目前都是空实现。
|
|
|
|
## 生命周期
|
|
|
|
- [Get](Get.md) 返回进程级单例。
|
|
- [Initialize](Initialize.md) 只设置初始化标志。
|
|
- [Shutdown](Shutdown.md) 清空样本与栈状态。
|
|
|
|
## 线程语义
|
|
|
|
- 当前实现没有任何锁，也不是按线程分桶存储。
|
|
- `m_profileStack` 是单个全局栈，因此 `BeginProfile` / `EndProfile` 只应在同一线程、同一调用栈上成对使用。
|
|
- 如果多个线程并发使用同一个 `Profiler`，样本次序和栈配对都可能被破坏。
|
|
|
|
## 宏
|
|
|
|
- `XE_PROFILE_BEGIN(name)` 开始一个具名区段。
|
|
- `XE_PROFILE_END()` 结束最近一次开始的区段。
|
|
- `XE_PROFILE_FUNCTION()` 使用当前函数名作为区段名。
|
|
|
|
这些宏是最适合当前实现的接入方式，因为它们几乎不引入额外样板代码。
|
|
|
|
## 公开方法
|
|
|
|
| 方法 | 说明 |
|
|
|------|------|
|
|
| [Get](Get.md) | 获取全局 `Profiler` 实例。 |
|
|
| [Initialize](Initialize.md) | 初始化 profiler 状态。 |
|
|
| [Shutdown](Shutdown.md) | 清空内部记录。 |
|
|
| [BeginProfile](BeginProfile.md) | 开始一个 profile 区段。 |
|
|
| [EndProfile](EndProfile.md) | 结束最近一个区段并记录时长。 |
|
|
| [BeginFrame](BeginFrame.md) | 标记帧开始。 |
|
|
| [EndFrame](EndFrame.md) | 结束当前帧并清空当前样本。 |
|
|
| [MarkEvent](MarkEvent.md) | 预留的事件标记接口。 |
|
|
| [SetMarker](SetMarker.md) | 预留的 marker 接口。 |
|
|
| [ExportChromeTracing](ExportChromeTracing.md) | 预留的导出接口。 |
|
|
|
|
## 相关文档
|
|
|
|
- [当前模块](../Debug.md)
|
|
- [Profiler Workflow](../../../_guides/Debug/Profiler-Workflow.md)
|