diff --git a/zh-cn/application-dev/napi/Readme-CN.md b/zh-cn/application-dev/napi/Readme-CN.md index 9af3ee7711908264fc5e071361c3895d632e1265..531349cc978d59ec54dec66ee4837a50b179feba 100644 --- a/zh-cn/application-dev/napi/Readme-CN.md +++ b/zh-cn/application-dev/napi/Readme-CN.md @@ -6,4 +6,5 @@ - [Rawfile开发指导](rawfile-guidelines.md) - [NativeWindow开发指导](native-window-guidelines.md) - [使用MindSpore Lite引擎进行模型推理](mindspore-lite-guidelines.md) -- [Neural Network Runtime对接AI推理框架开发指导](neural-network-runtime-guidelines.md) \ No newline at end of file +- [Neural Network Runtime对接AI推理框架开发指导](neural-network-runtime-guidelines.md) +- [Purgeable memory开发指导](purgeable-memory-guidelines.md) \ No newline at end of file diff --git a/zh-cn/application-dev/napi/purgeable-memory-guidelines.md b/zh-cn/application-dev/napi/purgeable-memory-guidelines.md new file mode 100644 index 0000000000000000000000000000000000000000..d86d9c47447ffd303a779161089550817e3f52ce --- /dev/null +++ b/zh-cn/application-dev/napi/purgeable-memory-guidelines.md @@ -0,0 +1,121 @@ +# 内存管理purgeable内存开发指导 + +## 场景介绍 + +开发者可以通过本指导了解在OpenHarmony应用中,如何使用Native purgeablememory接口操作purgeable内存。功能包括purgeable内存申请、释放。 + + +针对Purgeable memory,常见的开发场景如下: + +* 通过`Purgeablmemory`提供的`NAPI`接口申请PurgeableMemory对象,并将数据内容写入PurgeableMemory对象。 +* 使用完毕后使用 + +## 接口说明 + +| 接口名 | 描述 | +| -------- | -------- | +| OH_PurgeableMemory \*OH_PurgeableMemory_Create(size_t size, OH_PurgeableMemory_ModifyFunc func, void \*funcPara) | 创建Purgeable memory对象,每次调用都会产生一个新的Purgeable memory对象。 | +| bool OH_PurgeableMemory_Destroy(OH_PurgeableMemory \*purgObj) | 将Purgeable memory对象会被析构掉。 | +| bool OH_PurgeableMemory_BeginRead(OH_PurgeableMemory \*purgObj) | 对purgeable对象进行读访问。 | +| void OH_PurgeableMemory_EndRead(OH_PurgeableMemory \*purgObj) | 读操作结束,将Purgeable对象的引用计数减1,当引用计数为0的时候, 该Purgeable memory对象可以被系统回收。 | +| bool OH_PurgeableMemory_BeginWrite(OH_PurgeableMemory \*purgObj) | 通过NativeWindow对象申请一块NativeWindowBuffer,用以内容生产。 | +|bool OH_PurgeableMemory_BeginWrite(OH_PurgeableMemory \*purgObj) | 对purgeable对象进行写访问。| +|void OH_PurgeableMemory_EndWrite(OH_PurgeableMemory \*purgObj)|写操作结束,将Purgeable对象的引用计数减1,当引用计数为0的时候,该Purgeable memory对象可以被系统回收。| +|void \*OH_PurgeableMemory_GetContent(OH_PurgeableMemory \*purgObj)|获取PurgeableMemory对象内存数据。| +|size_t OH_PurgeableMemory_ContentSize(OH_PurgeableMemory \*purgObj)|获取PurgeableMemory对象内存数据大小。| +|bool OH_PurgeableMemory_AppendModify(OH_PurgeableMemory \*purgObj, OH_PurgeableMemory_ModifyFunc func, void \*funcPara)|添加PurgeableMemory对象的修改方法。| + +详细的接口说明请参考[purgeable_memory](../reference/native-apis/_purgeable_memory.md)。 + +## Purgeable应用开发步骤 + +以下步骤描述了在**OpenHarmony**中如何使用`PurgeableMemory`提供的`NAPI`接口,申请Purgeable Memory对象,并将内容写入Purgeable对象后,对相应对象进行读写访问。 + +1. 声明purgeable 对象创建规则 + ```c++ + // 声明构建函数的参数 + struct ParaData{ + int start; + int end; + } + + // 声明一个使用ModifyFunc + bool FactorialFunc(void* data, size_t size, void* param){ + bool ret = true; + int oriData = *(int*)(data); + int i = param->start; + while(iend){ + oriData *= i; + } + *data = oriData; + if(oriData < 0) + ret = false; + return ret; + } + + // 声明修改purgeable对象扩展函数的参数 + struct AppendParaData{ + int newPara; + } + + // 声明修改purgeable对象的扩展函数 + bool AddFunc(void* data, size_t size, void* param){ + bool ret = true; + int oriData = *(int*)(data); + oriData += param->newPara; + *data = oriData; + return ret; + } + ``` +2. 创建Purgeable对象 + ```c++ + // 声明一个4MB的purgeable对象大小 + #define DATASIZE (4 * 1024 * 1024) + + // 声明创建函数的参数 + struct ParaData pdata = {1,2}; + + // 创建一个Purgeable对象 + OH_PurgableMmory* pPurgmem = OH_PurgableMmory_Create(DATASIZE, FactorialFunc, &pdata); + ``` + +3. 读访问Purgeable 对象 + ```c++ + // 读取对象 + OH_PurgeableMemory_BeginRead(pPurgmem); + + // 获取purgeable对象大小 + size_t size = OH_PurgeableMemory_ContentSize(pPurgmem); + + // 获取purgeable对象内容 + ReqObj* pReqObj = (ReqObj*) OH_PurgeableMemory_GetContent(pPurgmem); + + // 读取purgeable对象结束 + OH_PurgeableMemory_EndRead(pPurgmem); + ``` + +4. 写访问Purgeable对象 + ```c++ + // 修改Purgeable对象 + OH_PurgeableMemory_BeginWrite(pPurgmem) + + // 获取purgeable对象数据 + ReqObj* pReqObj = (ReqObj*) OH_PurgeableMemory_GetContent(pPurgmem); + + // 声明扩展创建函数的参数 + struct AppendParaData apdata = {1}; + + // 更新purgeable 对象重建规则 + OH_PurgeableMemory_AppendModify(pPurgmem, AddFunc, &apdata); + + // 修改purgeable对象结束 + OH_PurgeableMemory_EndWrite(pPurgmem); + ``` + +5. 销毁Purgeable对象 + ```c++ + // 销毁对象 + OH_PurgeableMemory_Destroy(pPurgmem); + ``` + +## 相关实例 \ No newline at end of file diff --git a/zh-cn/application-dev/reference/native-apis/_purgeable_memory.md b/zh-cn/application-dev/reference/native-apis/_purgeable_memory.md new file mode 100644 index 0000000000000000000000000000000000000000..8328ab5b46d174adc61cd26df0b922ea7428ebf2 --- /dev/null +++ b/zh-cn/application-dev/reference/native-apis/_purgeable_memory.md @@ -0,0 +1,299 @@ +# Purgeable Memory + + +提供Purgeable Memory Native功能,主要用来开发purgeable应用。 + + +\@syscap SystemCapability.CommonLibrary.Memory.PurgeableMemory + + +**起始版本:** + + +10 + + +## 汇总 + + +### 文件 + + | 文件名称 | 描述 | +| -------- | -------- | +| [purgeable_memory.h](purgeable_memory.md) | 定义获取和使用PurgeableMemory的相关函数。 + + +### 结构体 + + | 结构体名称 | 描述 | +| -------- | -------- | +| [OH_PurgeableMemory](purgeable_memory.md) | 表示Purgeable对象 | + + +### 函数 + +| 函数名称 | 描述 | +| -------- | -------- | +|OH_PurgeableMemory_Create (size_t size, OH_PurgeableMemory_ModifyFunc func, void \*funcPara) | 创建Purgeable Memory实例,每次调用都会产生一个新的Purgeable Memory实例 | +|bool OH_PurgeableMemory_Destroy(OH_PurgeableMemory \*purgObj)| 将Purgeable memory对象会被析构掉| +|bool OH_PurgeableMemory_BeginRead(OH_PurgeableMemory \*purgObj)|对purgeable对象进行读访问| +|void OH_PurgeableMemory_EndRead(OH_PurgeableMemory \*purgObj)|读操作结束,将Purgeable对象的引用计数减1,当引用计数为0的时候, 该Purgeable memory对象可以被系统回收| +|bool OH_PurgeableMemory_BeginWrite(OH_PurgeableMemory \*purgObj)|通过NativeWindow对象申请一块NativeWindowBuffer,用以内容生产| +|bool OH_PurgeableMemory_BeginWrite(OH_PurgeableMemory \*purgObj)|对purgeable对象进行写访问| +|void OH_PurgeableMemory_EndWrite(OH_PurgeableMemory \*purgObj)|写操作结束,将Purgeable对象的引用计数减1,当引用计数为0的时候,该Purgeable memory对象可以被系统回收| +|void \*OH_PurgeableMemory_GetContent(OH_PurgeableMemory \*purgObj)|获取PurgeableMemory对象内存数据| +|size_t OH_PurgeableMemory_ContentSize(OH_PurgeableMemory \*purgObj)|获取PurgeableMemory对象内存数据大小| +|bool OH_PurgeableMemory_AppendModify(OH_PurgeableMemory \*purgObj, OH_PurgeableMemory_ModifyFunc func, void *funcPara)|添加PurgeableMemory对象的修改方法| + + + +## 详细描述 + +## 函数说明 + + +### OH_PurgeableMemory_Create() + +``` +OH_PurgeableMemory *OH_PurgeableMemory_Create(size_t size, OH_PurgeableMemory_ModifyFunc func, void *funcPara) +``` + +**描述:** + +创建Purgeable Memory实例,每次调用都会产生一个新的Purgeable Memory实例。 + +\@syscap SystemCapability.CommonLibrary.Memory.PurgeableMemory + +**参数:** + +| 名称 | 描述 | +| -------- | -------- | +| size | 参数是描述purgeable对象大小的变量,类型为size_t; | +| func | 参数是一个指向创建函数OH_PurgeableMemory_ModifyFunc的指针,类型为sptr<OH_PurgeableMemory_ModifyFunc> | +| funcPara | 参数是指向创建函数参数func的指针,类型可自定义 | + +**返回:** + +返回一个指针,指向OH_PurgeableMemory的结构体实例。 + +**起始版本:** + +10 + + +### OH_PurgeableMemory_Destroy() + + +``` +bool OH_PurgeableMemory_Destroy(OH_PurgeableMemory *purgObj) +``` + +**描述:** + +将Purgeable memory对象会被析构掉。 + +\@syscap SystemCapability.CommonLibrary.Memory.PurgeableMemory + +**参数:** + + | 名称 | 描述 | +| -------- | -------- | +| purgObj | 参数是一个指向待访问的PurgeableMemory对象的指针,类型为sptr<OH_PurgeableMemory> | + +**返回:** + + 如果PurgeableMemory内存数据准备好则返回true;如果PurgeableMemory内存数据已被回收且重建失败则返回false。 + +**起始版本:** + +10 + + +### OH_PurgeableMemory_BeginRead() + + +``` +bool OH_PurgeableMemory_BeginRead(OH_PurgeableMemory *purgObj) +``` + +**描述:** + +开始读取PurgeableMemory对象。检查PurgeableMemory是否被回收,若被回收则调用重建方法进行重建。 + +\@syscap SystemCapability.CommonLibrary.Memory.PurgeableMemory + +**参数:** + + | 名称 | 描述 | +| -------- | -------- | +| purgObj | 参数是一个指向待访问的PurgeableMemory对象的指针,类型为sptr<OH_PurgeableMemory> | + +**返回** + + 如果PurgeableMemory内存数据准备好则返回ture;如果PurgeableMemory内存数据已被回收且重建失败则返回false。 + +**起始版本:** + +10 + + +### OH_PurgeableMemory_EndRead() + + +``` +void OH_PurgeableMemory_EndRead(OH_PurgeableMemory *purgObj) +``` + +**描述:** + +结束读取PurgeableMemory对象。表示系统可回收该PurgeableMemory对象内存数据。 + +\@syscap SystemCapability.CommonLibrary.Memory.PurgeableMemory + +**参数:** + + | 名称 | 描述 | +| -------- | -------- | +| purgObj | 参数是一个指向待访问的PurgeableMemory对象的指针,类型为sptr<OH_PurgeableMemory> | + +**起始版本:** + +10 + + +### OH_PurgeableMemory_BeginWrite() + + +``` +bool OH_PurgeableMemory_BeginWrite(OH_PurgeableMemory *purgObj) +``` + +**描述:** + +开始修改PurgeableMemory对象。检查PurgeableMemory是否被回收,若被回收则调用重建方法进行重建。 + +\@syscap SystemCapability.CommonLibrary.Memory.PurgeableMemory + +**参数:** + + | 名称 | 描述 | +| -------- | -------- | +| purgObj | 参数是一个指向待访问的PurgeableMemory对象的指针,类型为sptr<OH_PurgeableMemory> | + +**返回:** + + 如果PurgeableMemory内存数据准备好则返回ture;如果PurgeableMemory内存数据已被回收且重建失败则返回false。 + +**起始版本:** + +10 + + +### OH_PurgeableMemory_EndWrite() + + +``` +void OH_PurgeableMemory_EndWrite(OH_PurgeableMemory *purgObj) +``` + +**描述:** + +结束修改PurgeableMemory对象。表示系统可回收该PurgeableMemory对象内存数据。 + +\@syscap SystemCapability.CommonLibrary.Memory.PurgeableMemory + +**参数:** + + | 名称 | 描述 | +| -------- | -------- | +| purgObj | 参数是一个指向待访问的PurgeableMemory对象的指针,类型为sptr<OH_PurgeableMemory> | + +**起始版本:** + +10 + + +### OH_PurgeableMemory_GetContent() + + +``` +void *OH_PurgeableMemory_GetContent(OH_PurgeableMemory *purgObj) +``` + +**描述:** + +获取PurgeableMemory对象内存数据 + +\@syscap SystemCapability.CommonLibrary.Memory.PurgeableMemory + +**参数:** + + | 名称 | 描述 | +| -------- | -------- | +| purgObj | 参数是一个指向待访问的PurgeableMemory对象的指针,类型为sptr<OH_PurgeableMemory> | + +**返回:** + +返回PurgeableMemory对象内存地址。 + +**起始版本:** + +10 + + +### OH_PurgeableMemory_ContentSize() + + +``` +size_t OH_PurgeableMemory_ContentSize(OH_PurgeableMemory *purgObj) +``` + +**描述:** + +获取PurgeableMemory对象内存数据大小。 + +\@syscap SystemCapability.CommonLibrary.Memory.PurgeableMemory + +**参数:** + + | 名称 | 描述 | +| -------- | -------- | +| purgObj | 参数是一个指向待访问的PurgeableMemory对象的指针,类型为sptr<OH_PurgeableMemory> | + +**返回:** + +返回PurgeableMemory对象内存数据大小,类型为size_t。 + +**起始版本:** + +10 + + +### OH_PurgeableMemory_AppendModify() + + +``` +bool OH_PurgeableMemory_AppendModify(OH_PurgeableMemory *purgObj, OH_PurgeableMemory_ModifyFunc func, void *funcPara) +``` + +**描述:** + +添加PurgeableMemory对象的修改方法,保证重建的数据是最新的数据。 + +\@syscap SystemCapability.CommonLibrary.Memory.PurgeableMemory + +**参数:** + + | 名称 | 描述 | +| -------- | -------- | +| size | 参数是描述purgeable对象大小的变量,类型为size_t; | +| func | 参数是一个指向创建函数OH_PurgeableMemory_ModifyFunc的指针,类型为sptr<OH_PurgeableMemory_ModifyFunc> | +| funcPara | 参数是指向创建函数参数func的指针,类型可自定义 | + +**返回:** + +设置成功返回true,否则返回false。 + +**起始版本:** + +10 \ No newline at end of file