XCEngine/docs/api/XCEngine/Core/SmartPtr/SmartPtr.md

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 是侵入式手工引用计数基类，而 Ref<T> 是标准库 shared_ptr。两者当前没有自动打通。

最安全的理解方式是：

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

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

线程语义

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

当前实现限制

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

相关指南

• Core Foundations: Ownership, Events, And Layers

相关文档

• 当前模块
• RefCounted
• Types
• API 总索引