1# 使用智能指针管理动态分配内存对象 2 3## 概述 4 5智能指针是行为类似指针的类，在模拟指针功能的同时提供增强特性，如针对具有动态分配内存对象的自动内存管理等。 6 7* 自动内存管理主要是指对超出生命周期的对象正确并自动地释放其内存空间，以避免出现内存泄漏等相关内存问题。 8* 智能指针对每一个RefBase对象具有两种不同的引用形式。强引用持有对一个对象的直接引用。 具有强引用关系的对象在该强引用关系存在时同样也应当存在，也即该引用关系有效；弱引用持有对一个对象的间接引用。 具有弱引用关系的对象在该弱引用关系存在时并不保证存在。 9 10> 注意：上述描述仅当正确使用智能指针时才成立。 11 12### 实现原理 13 14* 智能指针通过引用计数来实现所指向对象内存的自动管理。每一个可以被智能指针管理的对象都持有一个引用计数器，引用计数器在相关引用计数清0时会调用一个用于销毁该对象的回调函数。 15 16* 引用计数器记录了对应RefBase对象的两种不同引用计数值，以及对于其本身，即RefCounter对象的引用计数值。 17 18## 涉及功能 19 20### OHOS::sptr 21 22**模块:** **SmartPointer** 23 24指向RefBase(或其子类)对象的强引用智能指针。 25 26#### 具体描述 27 28```cpp 29template <typename T > 30class OHOS::sptr; 31``` 32 33指向RefBase(或其子类)对象的强引用智能指针。 34 35**模板参数**: 36 37* **T** 被sptr管理的具体类型。该类必须继承自RefBase基类。 38 39其直接引用RefBase对象。 40 41`#include <refbase.h>` 42 43#### 接口说明 44 45| 返回类型 | 名称 | 46| --------------------------------------- | -------------------------------------------------------------------------------- | 47| | **sptr**() | 48|sptr< T > | template <typename... Args><br>**MakeSptr**(Args&&... args)<br>构造T类型的被管理对象并创建sptr管控，传递参数args为T类型构造函数所需参数<br> **注意:强烈建议使用该方法构造sptr并管控对象，可以避免对象指针对外暴露，将对象的生命周期完全处于智能指针的管控之下** | 49| template <typename O \> <br> | **sptr**(const sptr< O >& other)<br>拷贝构造函数，参数与当前sptr具有不同的管理类型(O) | 50| | **sptr**(const sptr< T >& other)<br>拷贝构造函数。其以参数指定具体管理对象 | 51| | **sptr**(sptr< T >&& other)<br>移动构造函数 | 52| | **sptr**(T* other)<br>构造函数。其以参数指定具体管理对象<br> **注意: 不建议使用对象指针的形式构造sptr对象，这会导致对象的生命周期不完全在sptr的看护下，很可能误用造成对象提前释放** | 53| | **sptr**(WeakRefCount* p, bool force)<br>构造函数。仅用于wptr的promote操作 | 54| | **~sptr**() | 55| void | **clear**()<br>移除当前sptr与所管理对象的引用关系 | 56| void | **ForceSetRefPtr**(T* other)<br>强制更改被管理对象指针的指向 | 57| T* | **GetRefPtr**() const<br>获取sptr管理对象的指针 | 58| | **operator T***() const<br>类型转换运算符 | 59| | **operator bool**() const<br>布尔类型转换运算符。检查sptr对象是否为空对象 | 60| bool | **operator!=**(const sptr< T >& other) const<br>sptr对象间的不等运算符 | 61| bool | **operator!=**(const T* other) const<br>sptr对象与裸指针间的不等运算符 | 62| bool | **operator!=**(const wptr< T >& other) const<br>sptr对象与wptr间的相等运算符 | 63| T& | **operator***() const<br>解引用运算符，其会返回wptr管理的RefBae对象 | 64| T* | **operator->**() const<br>成员选择运算符，其将会返回被sptr管理对象的指定成员 | 65| template <typename O \> <br>sptr< T >& | **operator=**(const sptr< O >& other)<br>拷贝赋值运算符，参数为一个sptr对象，但与当前sptr对象具有不同管理类型 | 66| sptr< T >& | **operator=**(const sptr< T >& other)<br>拷贝赋值运算符，参数与当前sptr对象具有相同管理类型 | 67| sptr< T >& | **operator=**(const wptr< T >& other)<br>拷贝赋值运算符，参数为一个wptr对象，但与当前sptr对象具有相同管理类型 | 68| sptr< T >& | **operator=**(sptr< T >&& other)<br>移动构造运算符 | 69| sptr< T >& | **operator=**(T* other)<br>拷贝赋值运算符，参数为待管理的具体对象<br>**注意: 不建议以指针赋值的形式创建sptr对象，这会导致对象的生命周期不完全在sptr的看护下，很可能误用造成对象提前释放** | 70| bool | **operator==**(const sptr< T >& other) const<br>sptr对象间的相等运算符 | 71| bool | **operator==**(const T* other) const<br>sptr对象与裸指针间的相等运算符 | 72| bool | **operator==**(constwptr< T >& other) const<br>sptr对象与wptr间的相等运算符 | 73 74### OHOS::wptr 75 76**模块:** **SmartPointer** 77 78指向RefBase(或其子类)对象的弱引用智能指针。 79 80#### 具体描述 81 82```cpp 83template <typename T > 84class OHOS::wptr; 85``` 86 87指向RefBase(或其子类)对象的弱引用智能指针。 88 89**模板参数**: 90 91* **T** 被wptr管理的具体类型。该类必须继承自RefBase基类。 92 93其间接引用RefBase对象；直接引用WeakRefCounter对象。 94 95`#include <refbase.h>` 96 97#### 接口说明 98 99| 返回类型 | 名称 | 100| --------------------------------------- | ------------------------------------------------------------------------------------ | 101| | **wptr**() | 102| template <typename O \> <br> | **wptr**(const sptr< O >& other)<br>拷贝构造函数。参数为一个sptr对象，且与当前wptr对象具有不同的管理类型(O) | 103| | **wptr**(const sptr< T >& other)<br>拷贝构造函数。参数为一个sptr对象，但与当前wptr对象具有相同的管理类型 | 104| template <typename O \> <br> | **wptr**(const wptr< O >& other)<br>拷贝构造函数。参数与当前wptr对象具有不同的管理类型 | 105| | **wptr**(const wptr< T >& other)<br>拷贝构造函数。参数与当前wptr对象具有相同的管理类型 | 106| | **wptr**(T* other)<br>构造函数。其以参数指定具体管理对象 | 107| | **~wptr**() | 108| bool | **AttemptIncStrongRef**(const void* objectId) const<br>尝试对被管理对象的强引用计数加一 | 109| T* | **GetRefPtr**() const<br>获取指向被管理RefBase对象的指针 | 110| bool | **operator!=**(const sptr< T >& other) const<br>wptr与输入sptr对象间的不等运算符 | 111| bool | **operator!=**(const T* other) const<br>wptr对象与裸指针间的不等运算符 | 112| bool | **operator!=**(constwptr< T >& other) const<br>wptr对象间的不等运算符 | 113| T& | **operator***() const<br>解引用运算符，其会返回wptr管理的RefBae对象 | 114| T* | **operator->**() const<br>成员选择操作符，其将会返回被wptr管理对象的指定成员 | 115| template <typename O \> <br>wptr< T >& | **operator=**(const sptr< O >& other)<br>拷贝赋值运算符，参数为一个sptr对象，但与当前wptr对象具有不同的管理类型(O) | 116| wptr< T >& | **operator=**(const sptr< T >& other)<br>拷贝赋值运算符，参数为一个sptr对象，但与当前wptr对象具有相同的管理类型(T) | 117| template <typename O \> <br>wptr< T >& | **operator=**(const wptr< O >& other)<br>拷贝赋值运算符，参数为一个wptr对象，但与当前wptr对象具有不同的管理类型(O) | 118| wptr< T >& | **operator=**(const wptr< T >& other)<br>拷贝赋值运算符，参数为一个wptr对象，且与当前wptr对象具有相同的管理类型(T) | 119| template <typename O \> <br>wptr< T >& | **operator=**(O* other)<br>拷贝赋值运算符，参数为待管理的具体对象 | 120| wptr< T >& | **operator=**(T* other)<br>拷贝赋值运算符，参数为待管理的具体对象 | 121| bool | **operator==**(const sptr< T >& other) const<br>wptr与输入sptr对象间的相等运算符 | 122| bool | **operator==**(const T* other) const<br>wptr对象与裸指针间的相等运算符 | 123| bool | **operator==**(const wptr< T >& other) const<br>wptr对象间的相等运算符 | 124| const sptr< T > | **promote**() const<br>将该wptr提升为sptr | 125 126## 使用示例 127 1281. 使用方法(伪代码) 129 130``` 131#include "../include/refbase.h" 132#include <iostream> 133 134using namespace std; 135using namespace OHOS; 136 137// 管理目标类 138class RefBaseTest : public RefBase { 139public: 140 virtual void Access() 141 { 142 cout<<"Access RefBaseTest::Show"<<endl; 143 } 144 145 ~RefBaseTest() override 146 { 147 cout << "RefBaseTest destroyed" << endl; 148 } 149}; 150 151// 管理目标类的子类 152class SubRefBaseTest : public RefBaseTest { 153public: 154 void Access() override 155 { 156 cout<<"Access SubRefBaseTest::Show"<<endl; 157 } 158 159 ~SubRefBaseTest() override 160 { 161 cout << "SubRefBaseTest destroyed" << endl; 162 } 163}; 164 165int main() 166{ 167 // 1. 使用新创建智能指针，管理新创建对象 168 sptr<RefBaseTest> newSptr(new RefBaseTest()); 169 wptr<RefBaseTest> newWptr(new RefBaseTest()); 170 171 // 2. 使用上述智能指针，管理另一个新创建对象 172 // 原管理对象析构 173 newSptr = new RefBaseTest(); 174 newWptr = new RefBaseTest(); 175 176 // 3. 使用新创建智能指针，指向其他现存智能指针管理对象 177 sptr<RefBaseTest> curSptr(newSptr); 178 wptr<RefBaseTest> curWptr(newWptr); 179 180 if (curSptr->GetSptrRefCount() == 2 && curSptr->GetWptrRefCount() == 2 && // 2: count 181 curWptr->GetWptrRefCount() == 1) { 182 cout << "curSptr run as expected" << endl; 183 } 184 185 // 4. 使用现存智能指针管理其托管类型的子类对象 186 sptr<SubRefBaseTest> subSptr(new SubRefBaseTest()); 187 wptr<SubRefBaseTest> subWptr(new SubRefBaseTest()); 188 189 curSptr = subSptr; 190 curWptr = subWptr; 191 192 // 5. 通过->运算符访问成员" 193 curSptr->Access(); 194 curWptr->Access(); 195 196 // 6. 通过*运算符解引用 197 (*curSptr).Access(); 198 (*curSptr).Access(); 199 200 // 7. 两种智能指针可以管理对方所管理的对象 201 sptr<RefBaseTest> scurSptr(new RefBaseTest); 202 wptr<RefBaseTest> scurWptr(new RefBaseTest); 203 204 wptr<RefBaseTest> snewWptr(scurSptr); 205 206 sptr<RefBaseTest> soldSptr(new RefBaseTest); 207 wptr<RefBaseTest> soldWptr(new RefBaseTest); 208 soldSptr = scurWptr; // sptr仅可通过拷贝赋值管理wptr所管理对象 209 soldWptr = scurSptr; // 原本的引用关系将被释放 210 211 if (snewWptr->GetWptrRefCount() == 3 && soldSptr->GetSptrRefCount() == 1 && // 3: count 212 soldWptr->GetWptrRefCount() == 3) { // 3: count 213 cout << "Smart Pointer assignment run as expected" << endl; 214 } 215 // 8. wptr可升级为sptr 216 sptr<RefBaseTest> spromotedWptr = snewWptr.promote(); // 升级失败时返回空sptr对象，即未管理具体对象的sptr对象 217 if (spromotedWptr->GetSptrRefCount() == 2 && spromotedWptr->GetWptrRefCount() == 4) { // 2, 4: count 218 cout << "Promote run as expected" << endl; 219 } 220 221 return 0; 222} 223``` 224 2252. 测试用例编译运行方法 226 227- 测试用例代码参见 base/test/unittest/common/utils_refbase_test.cpp 228 229- 使用开发者自测试框架，使用方法参见：[开发自测试执行框架-测试用例执行](https://gitee.com/openharmony/testfwk_developer_test#%E6%B5%8B%E8%AF%95%E7%94%A8%E4%BE%8B%E6%89%A7%E8%A1%8C) 230 231- 使用以下具体命令以运行`refbase.h`对应测试用例 232 233```bash 234run -t UT -tp utils -ts UtilsRefBaseTest 235``` 236 2373. debug功能 238RefTracker作为debug工具被添加入refbase文件中，以便开发者对RefBase相关问题进行定位。该功能需要重新编译动态库替换系统原有动态库来上机使用（如是静态依赖则需开发者独立审视使能方法）。 239- 全局追踪 240 241全局追踪功能通过编译宏控制，可以追踪全局的RefBase及其子类的轨迹，但同时会对整机性能造成影响。 242全局追踪中我们提供了立即打印模式及非立即打印模式。立即打印模式会在每次引用计数发生变化时对计数进行打印。非立即打印模式会在RefBase及其子类对象析构时对轨迹进行打印。 243 244全局追踪、立即打印编译命令： 245``` 246./build.sh --product-name xxx --ccache --build-target commonlibrary/c_utils/base:utils --gn-args c_utils_debug_refbase=true --gn-args c_utils_track_all=true --gn-args c_utils_print_track_at_once=true 247``` 248全局追踪、非立即打印编译命令： 249``` 250./build.sh --product-name xxx --ccache --build-target commonlibrary/c_utils/base:utils --gn-args c_utils_debug_refbase=true --gn-args c_utils_track_all=true 251``` 252- 独立追踪 253 254独立追踪功能同样能通过编译宏控制。我们为开发者提供了RefBase::EnableTracker()接口来对某个具体实例使能追踪功能。独立追踪对性能影响很小，可以忽略不计。在独立追踪中我们能同样提供了立即打印及非立即打印模式。 255 256独立追踪、立即打印编译命令： 257``` 258./build.sh --product-name xxx --ccache --build-target commonlibrary/c_utils/base:utils --gn-args c_utils_debug_refbase=true --gn-args c_utils_print_track_at_once=true 259``` 260独立追踪、非立即打印编译命令： 261``` 262./build.sh --product-name xxx --ccache --build-target commonlibrary/c_utils/base:utils --gn-args c_utils_debug_refbase=true 263``` 264 265- 使用方法 266 267编译动态库，编译产物路径为`./out/xxx/commonlibrary/c_utils/libutils.z.so`。 268 269编译产物需要推入系统进行替换，64位系统位于`/system/lib64/`，32位系统位于`/system/lib/`。 270 271追踪结果通过log打印。格式如下： 272``` 273// 立即打印 274(sptr pointer) start tracking 275(sptr pointer) call (RefBase pointer). strong: x weak: x refcnnt: x 276... 277(sptr pointer) call (RefBase pointer). strong: x weak: x refcnnt: x 278(sptr pointer) end tracking 279 280// 非立即打印 281(sptr pointer) start backtrace 282(sptr pointer) call (RefBase pointer). strong: x weak: x refcnnt: x PID: xxx TID: xxx 283... 284(sptr pointer) call (RefBase pointer). strong: x weak: x refcnnt: x PID: xxx TID: xxx 285(sptr pointer) end backtrace 286``` 287 288## 常见问题 289 2901. **使用本实现智能指针时，同时使用裸指针或std标准库智能指针(std::shared_ptr)** 291 292 * 会造成管理冲突，导致非法访问以及未定义行为，如内存重复释放。 293 * 因此也不推荐先创建裸指针后，再使用智能指针管理。 294```c++ 295RefBase* a = new RefBase(); 296sptr<RefBase> s = a; 297// 或 298sptr<RefBase> s(a); // 裸指针a容易被误delete,造成sptr功能失常 299``` 300 3012. **智能指针需构造在栈上，管理的对象需要在堆上(动态分配对象)** 302 303 * 智能指针若构造在堆上则不符合定义。 304 * 管理对象若构造在栈上，则会自动释放，错误绕开智能指针管控。 305 3063. **智能指针不保证线程安全**，使用者需保证线程安全以避免同时对同一个sptr对象赋值等操作 307 3084. **避免通过隐式转换构造智能指针对象** 309 310 * 易造成误解。 311 * 因编译器优化程度具有不确定的行为，易造成问题。 312 3135. **不建议使用对象指针构造智能指针对象** 314 315 * 外部提前以指针形式释放对象后，继续通过智能指针中使用 316 * sptr引用计数为0释放对象，对象指针依旧在外被继续使用 317 318```cpp 319Refbase *a = new Refbase(arg1, arg2); 320sptr<Refbase> sp1 = a; // 不建议，对象指针a暴露在外，存在风险 321sptr<Refbase> sp2(a); // 不建议，对象指针a暴露在外，存在风险 322sptr<Refbase> sp3 = sptr<Refbase>::MakeSptr(arg1, arg2); // 建议，在内部构造Refbase对象，直接交与sptr管控使用 323``` 3246. **wptr使用注意** 325 326 * 在未设置**ExtendObjectLifetime**的情况下，wptr不参与被管理对象的生命周期控制，对象生命周期由sptr的引用计数控制，但在极特殊情况下存在例外 327 328```cpp 329// 由于历史设计原因，可以在sptr不存在的情况下，基于对象指针创建wptr对象。 330// 在未设置ExtendObjectLifetime，且无sptr被创建的特殊少见情况下，为了防止内存泄漏，在wptr引用计数归0时会释放管理对象 331Refbase *a = new Refbase(arg1, arg2); 332wptr<Refbase> wp1(a); 333wp1 = nullptr; // 弱引用计数归0，对象释放，应避免再次手动释放 334 335wptr<Refbase> wp2 = new Refbase(arg1, arg2); 336wp2 = nullptr; // 弱引用计数归0，对象释放，这种情况无法手动释放, 如果wptr不能控制对象释放则必然会发生内存泄漏 337```