XCEngine/docs/api/XCEngine/Debug/Profiler/Profiler.md

Profiler

命名空间: XCEngine::Debug

类型: class (singleton)

头文件: XCEngine/Debug/Profiler.h

描述: 提供轻量级 CPU 埋点入口，用于记录成对的 profile 区段。

概述

Profiler 的 API 形状明显面向“开发期埋点”和“后续时间线导出”场景，但当前实现仍处于非常早期的阶段。它已经能够记录一组成对的 BeginProfile / EndProfile 调用时长，却还没有提供读取样本、可视化时间线或导出 Chrome Trace 的完整工作流。

可以把它理解为：

• 设计方向上类似轻量版的引擎内 CPU 埋点器；
• 但当前能力远不等同于 Unity Profiler 这类成熟的分析器。

当前实现能力

• BeginProfile / EndProfile 会把区段时长记录到内部样本数组。
• BeginFrame 只记录一帧开始时间。
• EndFrame 当前会直接清空样本数组。
• MarkEvent、SetMarker 和 ExportChromeTracing 目前都是空实现。

生命周期

• Get 返回进程级单例。
• Initialize 只设置初始化标志。
• Shutdown 清空样本与栈状态。

线程语义

• 当前实现没有任何锁，也不是按线程分桶存储。
• m_profileStack 是单个全局栈，因此 BeginProfile / EndProfile 只应在同一线程、同一调用栈上成对使用。
• 如果多个线程并发使用同一个 Profiler，样本次序和栈配对都可能被破坏。

宏

• XE_PROFILE_BEGIN(name) 开始一个具名区段。
• XE_PROFILE_END() 结束最近一次开始的区段。
• XE_PROFILE_FUNCTION() 使用当前函数名作为区段名。

这些宏是最适合当前实现的接入方式，因为它们几乎不引入额外样板代码。

公开方法

方法	说明
Get	获取全局 Profiler 实例。
Initialize	初始化 profiler 状态。
Shutdown	清空内部记录。
BeginProfile	开始一个 profile 区段。
EndProfile	结束最近一个区段并记录时长。
BeginFrame	标记帧开始。
EndFrame	结束当前帧并清空当前样本。
MarkEvent	预留的事件标记接口。
SetMarker	预留的 marker 接口。
ExportChromeTracing	预留的导出接口。

相关文档

• 当前模块
• Profiler Workflow