1# Purgeable Memory Development 2 3## When to Use 4 5OpenHarmony provides Purgeable Memory management, which enables you to use related APIs to create **PurgeableMemory** objects to manage purgeable memory. 6 7 8You can use the native APIs to apply for and release purgeable memory. 9 10 11The following scenarios are common for the development of purgeable memory management: 12 13* Apply for a **PurgeableMemory** object and write data to the object. 14* Release the **PurgeableMemory** object when it is no longer required. 15 16## Available APIs 17 18| API| Description| 19| -------- | -------- | 20| OH_PurgeableMemory \*OH_PurgeableMemory_Create(size_t size, OH_PurgeableMemory_ModifyFunc func, void \*funcPara) | Creates a **PurgeableMemory** object. A new **PurgeableMemory** object is generated each time this API is called.| 21| bool OH_PurgeableMemory_Destroy(OH_PurgeableMemory \*purgObj) | Destroys a **PurgeableMemory** object.| 22| bool OH_PurgeableMemory_BeginRead(OH_PurgeableMemory \*purgObj) | Begins a read operation on a **PurgeableMemory** object.| 23| void OH_PurgeableMemory_EndRead(OH_PurgeableMemory \*purgObj) | Ends a read operation on a **PurgeableMemory** object and decreases the reference count of the object by 1. When the reference count reaches 0, the object can be reclaimed by the system.| 24|bool OH_PurgeableMemory_BeginWrite(OH_PurgeableMemory \*purgObj) | Begins a write operation on a **PurgeableMemory** object.| 25|void OH_PurgeableMemory_EndWrite(OH_PurgeableMemory \*purgObj)|Ends a write operation on a **PurgeableMemory** object and decreases the reference count of the object by 1. When the reference count reaches 0, the object can be reclaimed by the system.| 26|void \*OH_PurgeableMemory_GetContent(OH_PurgeableMemory \*purgObj)|Obtains the memory data of a **PurgeableMemory** object.| 27|size_t OH_PurgeableMemory_ContentSize(OH_PurgeableMemory \*purgObj)|Obtains the memory data size of a **PurgeableMemory** object.| 28|bool OH_PurgeableMemory_AppendModify(OH_PurgeableMemory \*purgObj, OH_PurgeableMemory_ModifyFunc func, void \*funcPara)|Adds a function for modifying a **PurgeableMemory** object.| 29 30 31## How to Develop 32 33The following walks you through on how to use the native purgeable memory APIs to apply for a **PurgeableMemory** object, write data to the object, and read data from the object. 34 351. Declare the rules for creating a **PurgeableMemory** object. 36 ```c++ 37 // Declare the parameters of the constructor. 38 struct ParaData{ 39 int start; 40 int end; 41 }; 42 43 // Declare a function for modifying the object. 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 // Declare the parameters of the extended function for modifying the object. 57 struct AppendParaData{ 58 int newPara; 59 }; 60 61 // Declare the extended function for modifying the object. 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. Create a **PurgeableMemory** object. 71 ```c++ 72 // Define the memory data size to 4 MB. 73 #define DATASIZE (4 * 1024 * 1024) 74 75 // Declare the parameters of the constructor. 76 struct ParaData pdata = {1,2}; 77 78 // Create a PurgeableMemory object. 79 OH_PurgeableMemory* pPurgmem = OH_PurgeableMemory_Create(DATASIZE, FactorialFunc, &pdata); 80 ``` 81 823. Perform a read operation on the **PurgeableMemory** object. 83 ```c++ 84 // Define an object type based on the service requirements. 85 class ReqObj; 86 87 // Begin a read operation on the object. 88 OH_PurgeableMemory_BeginRead(pPurgmem); 89 90 // Obtain the object size. 91 size_t size = OH_PurgeableMemory_ContentSize(pPurgmem); 92 93 // Obtain the object content. 94 ReqObj* pReqObj = (ReqObj*) OH_PurgeableMemory_GetContent(pPurgmem); 95 96 // End the read operation on the object. 97 OH_PurgeableMemory_EndRead(pPurgmem); 98 ``` 99 1004. Perform a write operation on the **PurgeableMemory** object. 101 ```c++ 102 // Define an object type based on the service requirements. 103 class ReqObj; 104 105 // Begin a write operation on the object. 106 OH_PurgeableMemory_BeginWrite(pPurgmem); 107 108 // Obtain the object data. 109 ReqObj* pReqObj = (ReqObj*) OH_PurgeableMemory_GetContent(pPurgmem); 110 111 // Declare the parameters of the extended constructor. 112 struct AppendParaData apdata = {1}; 113 114 // Update the rules for recreating the object. 115 OH_PurgeableMemory_AppendModify(pPurgmem, AddFunc, &apdata); 116 117 // Stop writing data to the object. 118 OH_PurgeableMemory_EndWrite(pPurgmem); 119 ``` 120 1215. Destroy the **PurgeableMemory** object. 122 ```c++ 123 // Destroy the object. 124 OH_PurgeableMemory_Destroy(pPurgmem); 125 ``` 126