Purgeable Memory Development

When to Use

OpenHarmony provides Purgeable Memory management, which enables you to use related APIs to create PurgeableMemory objects to manage purgeable memory.

You can use the native APIs to apply for and release purgeable memory.

The following scenarios are common for the development of purgeable memory management:

  • Apply for a PurgeableMemory object and write data to the object.
  • Release the PurgeableMemory object when it is no longer required.

Available APIs

API Description
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.
bool OH_PurgeableMemory_Destroy(OH_PurgeableMemory *purgObj) Destroys a PurgeableMemory object.
bool OH_PurgeableMemory_BeginRead(OH_PurgeableMemory *purgObj) Begins a read operation on a PurgeableMemory object.
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.
bool OH_PurgeableMemory_BeginWrite(OH_PurgeableMemory *purgObj) Begins a write operation on a PurgeableMemory object.
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.
void *OH_PurgeableMemory_GetContent(OH_PurgeableMemory *purgObj) Obtains the memory data of a PurgeableMemory object.
size_t OH_PurgeableMemory_ContentSize(OH_PurgeableMemory *purgObj) Obtains the memory data size of a PurgeableMemory object.
bool OH_PurgeableMemory_AppendModify(OH_PurgeableMemory *purgObj, OH_PurgeableMemory_ModifyFunc func, void *funcPara) Adds a function for modifying a PurgeableMemory object.

How to Develop

The 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.

  1. Declare the rules for creating a PurgeableMemory object.

    // Declare the parameters of the constructor.
    struct ParaData{
        int start;
        int end;
    };
    
    // Declare a function for modifying the object.
    bool FactorialFunc(void* data, size_t size, void* param){
        bool ret = true;
        ParaData *pdata = (ParaData*) param;
        int* oriData = (int*)data;
        int i = pdata->start;
        while(i<pdata->end){
            *oriData *= i;
            i++;
        }
        return ret;
    }
    
    // Declare the parameters of the extended function for modifying the object.
    struct AppendParaData{
        int newPara;
    };
    
    // Declare the extended function for modifying the object.
    bool AddFunc(void* data, size_t size, void* param){
        bool ret = true;
        int *oriDatap = (int*) data;
        AppendParaData* apData = (AppendParaData*)param;
        *oriDatap += apData->newPara;
        return ret;
    }
    
  2. Create a PurgeableMemory object.

    // Define the memory data size to 4 MB.
    #define DATASIZE (4 * 1024 * 1024)
    
    // Declare the parameters of the constructor.
    struct ParaData pdata = {1,2};
    
    // Create a PurgeableMemory object.
    OH_PurgeableMemory* pPurgmem = OH_PurgeableMemory_Create(DATASIZE, FactorialFunc, &pdata);
    
  3. Perform a read operation on the PurgeableMemory object.

    // Define an object type based on the service requirements.
    class ReqObj;
    
    // Begin a read operation on the object.
    OH_PurgeableMemory_BeginRead(pPurgmem);
    
    // Obtain the object size.
    size_t size = OH_PurgeableMemory_ContentSize(pPurgmem);
    
    // Obtain the object content.
    ReqObj* pReqObj = (ReqObj*) OH_PurgeableMemory_GetContent(pPurgmem);
    
    // End the read operation on the object.
    OH_PurgeableMemory_EndRead(pPurgmem);
    
  4. Perform a write operation on the PurgeableMemory object.

     // Define an object type based on the service requirements.
    class ReqObj;
    
    // Begin a write operation on the object.
    OH_PurgeableMemory_BeginWrite(pPurgmem);
    
    // Obtain the object data.
    ReqObj* pReqObj = (ReqObj*) OH_PurgeableMemory_GetContent(pPurgmem);
    
    // Declare the parameters of the extended constructor.
    struct AppendParaData apdata = {1};
    
    // Update the rules for recreating the object.
    OH_PurgeableMemory_AppendModify(pPurgmem, AddFunc, &apdata);
    
    // Stop writing data to the object.
    OH_PurgeableMemory_EndWrite(pPurgmem);
    
  5. Destroy the PurgeableMemory object.

    // Destroy the object.
    OH_PurgeableMemory_Destroy(pPurgmem);