# SmartPtr

**命名空间**: `XCEngine::Core`

**类型**: `header-overview`

**头文件**: `XCEngine/Core/SmartPtr.h`

**描述**: 定义 `std::shared_ptr` / `std::unique_ptr` 的引擎内别名，以及 `MakeRef()` / `MakeUnique()` 工厂函数。

## 角色概述

`SmartPtr.h` 是当前代码库里最直接、也最现代的一层所有权约定：

- `Ref<T>` = `std::shared_ptr<T>`
- `UniqueRef<T>` = `std::unique_ptr<T>`
- `MakeRef<T>()` = `std::make_shared<T>()`
- `MakeUnique<T>()` = `std::make_unique<T>()`

这让代码在保持引擎命名风格的同时，仍然直接复用标准库语义。

## 当前实现行为

### 1. 这是薄封装，不是自定义智能指针系统

当前头文件里没有自定义控制块、intrusive hook、调试统计或特殊 deleter 逻辑。它只是别名与便捷工厂函数。

这意味着：

- `Ref<T>` 的行为完全等同 `std::shared_ptr<T>`
- `UniqueRef<T>` 的行为完全等同 `std::unique_ptr<T>`

### 2. `MakeRef()` / `MakeUnique()` 只是便捷入口

当前实现直接转发到标准库：

- `MakeRef()` -> `std::make_shared`
- `MakeUnique()` -> `std::make_unique`

`tests/core/test_core.cpp` 已覆盖：

- 默认构造
- 拷贝共享
- 移动语义
- `nullptr` 检查

### 3. 已有真实调用点

当前源码里至少能看到：

- `ResourceManager` 使用 `Core::MakeUnique<AsyncLoader>()`

这说明它不是纯风格占位，而是已经进入实际实现。

## 与 RefCounted 的关系

这是这个头文件最容易被误解的地方。

当前 [RefCounted](../RefCounted/RefCounted.md) 是侵入式手工引用计数基类，而 `Ref<T>` 是标准库 `shared_ptr`。两者当前没有自动打通。

最安全的理解方式是：

- `Ref<T>` / `UniqueRef<T>` 是当前更常规的 C++ RAII 工具
- `RefCounted` 是单独存在的一套 intrusive RC 机制

如果没有明确适配层，不要把继承自 `RefCounted` 的对象直接当成 `Ref<T>` 体系的一部分来想当然混用。

## 线程语义

- 线程语义沿用标准库智能指针本身的语义。
- 文档不额外扩展任何引擎层线程保证。

## 当前实现限制

- 没有自定义内存统计、调试名或对象池集成。
- 没有和 `RefCounted` 的统一 ownership 框架。
- 头文件本身不提供额外行为，只提供命名和风格统一。

## 相关指南

- [Core Foundations: Ownership, Events, And Layers](../../../_guides/Core/Core-Foundations-Ownership-Events-And-Layers.md)

## 相关文档

- [当前模块](../Core.md)
- [RefCounted](../RefCounted/RefCounted.md)
- [Types](../Types/Types.md)
- [API 总索引](../../../main.md)