1# 内存管理purgeable内存开发指导
2
3## 场景介绍
4
5OpenHarmony提供Purgeable Memory内存管理机制，开发者可以使用相关接口创建PurgeableMemory对象，从而管理purgeable内存。
6
7
8开发者可以通过本指导了解在OpenHarmony应用中，如何使用Native层相关接口操作purgeable内存。功能包括purgeable内存的申请、释放等。
9
10
11针对Purgeable Memory内存管理机制，常见的开发场景如下：
12
13* 通过该机制提供的`NAPI`接口申请管理PurgeableMemory对象，并将数据内容写入该对象。
14* 使用完毕后释放。
15
16## 接口说明
17
18| 接口名 | 描述 |
19| -------- | -------- |
20| OH_PurgeableMemory \*OH_PurgeableMemory_Create(size_t size, OH_PurgeableMemory_ModifyFunc func, void \*funcPara) | 创建PurgeableMemory对象，每次调用都会产生一个新的PurgeableMemory对象。 |
21| bool OH_PurgeableMemory_Destroy(OH_PurgeableMemory \*purgObj) | 对PurgeableMemory对象进行析构操作。 |
22| bool OH_PurgeableMemory_BeginRead(OH_PurgeableMemory \*purgObj) | 对PurgeableMemory对象进行读访问。 |
23| void OH_PurgeableMemory_EndRead(OH_PurgeableMemory \*purgObj) | 读操作结束，将PurgeableMemory对象的引用计数减1，当引用计数为0的时候， 该PurgeableMemory对象可以被系统回收。 |
24|bool OH_PurgeableMemory_BeginWrite(OH_PurgeableMemory \*purgObj) | 对PurgeableMemory对象进行写访问。|
25|void OH_PurgeableMemory_EndWrite(OH_PurgeableMemory \*purgObj)|写操作结束，将PurgeableMemory对象的引用计数减1，当引用计数为0的时候，该PurgeableMemory对象可以被系统回收。|
26|void \*OH_PurgeableMemory_GetContent(OH_PurgeableMemory \*purgObj)|获取PurgeableMemory对象内存数据。|
27|size_t OH_PurgeableMemory_ContentSize(OH_PurgeableMemory \*purgObj)|获取PurgeableMemory对象内存数据大小。|
28|bool OH_PurgeableMemory_AppendModify(OH_PurgeableMemory \*purgObj, OH_PurgeableMemory_ModifyFunc func, void \*funcPara)|添加PurgeableMemory对象的修改方法。|
29
30
31## Purgeable Memory应用开发步骤
32
33以下步骤描述了在**OpenHarmony**中如何使用`Purgeable Memory`提供的`NAPI`接口，申请PurgeableMemory对象，并将内容写入PurgeableMemory对象后，对相应对象进行读写访问。
34
351. 声明PurgeableMemory对象创建规则。
36    ```c++
37    // 声明构建函数的参数
38    struct ParaData{
39        int start;
40        int end;
41    };
42
43    // 声明一个使用ModifyFunc
44    bool FactorialFunc(void* data, size_t size, void* param){
45        bool ret = true;
46        ParaData *pdata = (ParaData*) param;
47        int* oriData = (int*)data;
48        int i = pdata->start;
49        while (i < pdata->end) {
50            *oriData *= i;
51            i++;
52        }
53        return ret;
54    }
55
56    // 声明修改PurgeableMemory对象扩展函数的参数
57    struct AppendParaData{
58        int newPara;
59    };
60
61    // 声明修改PurgeableMemory对象的扩展函数
62    bool AddFunc(void* data, size_t size, void* param){
63        bool ret = true;
64        int *oriDatap = (int*) data;
65        AppendParaData* apData = (AppendParaData*)param;
66        *oriDatap += apData->newPara;
67        return ret;
68    }
69    ```
702. 创建PurgeableMemory对象。
71    ```c++
72    // 声明一个4MB的PurgeableMemory对象大小
73    #define DATASIZE (4 * 1024 * 1024)
74
75    // 声明创建函数的参数
76    struct ParaData pdata = {1,2};
77
78    // 创建一个PurgeableMemory对象
79    OH_PurgeableMemory* pPurgmem = OH_PurgeableMemory_Create(DATASIZE, FactorialFunc, &pdata);
80    ```
81
823. 读访问PurgeableMemory对象。
83    ```c++
84    //业务定义对象类型
85    class ReqObj;
86
87    // 读取对象
88    if(OH_PurgeableMemory_BeginRead(pPurgmem)) {
89        // 获取PurgeableMemory对象大小
90        size_t size = OH_PurgeableMemory_ContentSize(pPurgmem);
91
92        // 获取PurgeableMemory对象内容
93        ReqObj* pReqObj = (ReqObj*) OH_PurgeableMemory_GetContent(pPurgmem);
94
95        // 读取PurgeableMemory对象结束
96        OH_PurgeableMemory_EndRead(pPurgmem);
97    }
98    ```
99
1004. 写访问PurgeableMemory对象。
101    ```c++
102     //业务定义对象类型
103    class ReqObj;
104
105    // 修改PurgeableMemory对象
106    if(OH_PurgeableMemory_BeginWrite(pPurgmem)) {
107        // 获取PurgeableMemory对象数据
108        ReqObj* pReqObj = (ReqObj*) OH_PurgeableMemory_GetContent(pPurgmem);
109
110        // 声明扩展创建函数的参数
111        struct AppendParaData apdata = {1};
112
113        // 更新PurgeableMemory对象重建规则
114        OH_PurgeableMemory_AppendModify(pPurgmem, AddFunc, &apdata);
115
116        // 修改PurgeableMemory对象结束
117        OH_PurgeableMemory_EndWrite(pPurgmem);
118    }
119    ```
120
1215. 销毁PurgeableMemory对象。
122    ```c++
123    // 销毁对象
124    OH_PurgeableMemory_Destroy(pPurgmem);
125    // 置空指针防止UAF
126    pPurgmem = nullptr;
127    ```