# 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)