!19540 翻译完成：19003+19145 内存管理新增Purgeable Memory 接口文档

Merge pull request !19540 from wusongqing/TR19003

en/application-dev/napi/Readme-EN.md

 # Native APIs
 
-- [Introduction to Native APIs](introduction.md)
 - [Using Native APIs in Application Projects](napi-guidelines.md)
 - [Drawing Development](drawing-guidelines.md)
 - [Raw File Development](rawfile-guidelines.md)
 - [Native Window Development](native-window-guidelines.md)
 - [Using MindSpore Lite for Model Inference](mindspore-lite-guidelines.md)
-- [Connecting the Neural Network Runtime to an AI Inference Framework](neural-network-runtime-guidelines.md)
\ No newline at end of file
+- [Connecting the Neural Network Runtime to an AI Inference Framework](neural-network-runtime-guidelines.md)
+- [Purgeable Memory Development](purgeable-memory-guidelines.md)

en/application-dev/napi/purgeable-memory-guidelines.md

+# Purgeable Memory Development
+
+## When to Use
+
+You can use the native purgeable memory APIs to apply for and release purgeable memory.
+
+
+The following scenarios are common for native purgeable memory development:
+
+* 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 steps describe 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.
+    ```c++
+    // 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;
+         int oriData = *(int*)(data);
+         int i = param->start;
+         while(i<param->end){
+            oriData *= i;
+         }
+         *data = oriData;
+         if(oriData < 0)
+            ret = false;
+         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 oriData = *(int*)(data);
+         oriData += param->newPara;
+         *data = oriData;
+         return ret;
+    }
+    ```
+2. Create a **PurgeableMemory** object.
+    ```c++
+    // 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_PurgableMmory* pPurgmem = OH_PurgableMmory_Create(DATASIZE, FactorialFunc, &pdata);
+    ```
+
+3. Perfrom a read operation on the **PurgeableMemory** object.
+    ```c++
+    // 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 a read operation on the object.
+    OH_PurgeableMemory_EndRead(pPurgmem);
+    ```
+
+4. Perform a write operation on the **PurgeableMemory** object.
+    ```c++
+    // 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.
+    ```c++
+    // Destroy the object.
+    OH_PurgeableMemory_Destroy(pPurgmem);
+    ```

en/application-dev/reference/native-apis/Readme-EN.md

@@ -18,6 +18,7 @@
   - [HuksKeyApi](_huks_key_api.md)
   - [HuksParamSetApi](_huks_param_set_api.md)
   - [HuksTypeApi](_huks_type_api.md)
+  - [Memory](memory.md)
 - Header Files
   - [drawing_bitmap.h](drawing__bitmap_8h.md)
   - [drawing_brush.h](drawing__brush_8h.md)
@@ -56,6 +57,7 @@
   - [native_huks_api.h](native__huks__api_8h.md)
   - [native_huks_param.h](native__huks__param_8h.md)
   - [native_huks_type.h](native__huks__type_8h.md)
+  - [purgeable_memory.h](purgeable__memory_8h.md)
 - Structs
   - [OH_Drawing_BitmapFormat](_o_h___drawing___bitmap_format.md)
   - [OH_NativeXComponent_Callback](_o_h___native_x_component___callback.md)

en/application-dev/reference/native-apis/memory.md

+# Memory
+
+
+## Overview
+
+Provides APIs for memory management.
+
+@Syscap SystemCapability.CommonLibrary.PurgeableMemory
+
+**Since**
+
+10
+
+
+## Summary
+
+
+### Files
+
+| Name| Description|
+| -------- | -------- |
+| [purgeable_memory.h](purgeable__memory_8h.md) | Declares the APIs for managing purgeable memory at the native layer.|
+
+
+### Types
+
+| Name| Description|
+| -------- | -------- |
+| [OH_PurgeableMemory](#oh_purgeablememory) | Defines the type name of the **OH_PurgeableMemory** data.|
+| (\*[OH_PurgeableMemory_ModifyFunc](#oh_purgeablememory_modifyfunc)) (void \*, size_t, void \*) | Defines the function for rebuilding purgeable memory data.|
+
+
+### Functions
+
+| Name| Description|
+| -------- | -------- |
+| \*[OH_PurgeableMemory_Create](#oh_purgeablememory_create) (size_t size, [OH_PurgeableMemory_ModifyFunc](#oh_purgeablememory_modifyfunc) func, void \*funcPara) | Creates a **PurgeableMemory** object.|
+| [OH_PurgeableMemory_Destroy](#oh_purgeablememory_destroy) ([OH_PurgeableMemory](#oh_purgeablememory) \*purgObj) | Destroys a **PurgeableMemory** object.|
+| [OH_PurgeableMemory_BeginRead](#oh_purgeablememory_beginread) ([OH_PurgeableMemory](#oh_purgeablememory) \*purgObj) | Starts a read operation on a **PurgeableMemory** object. If purgeable memory is reclaimed, the rebuilding function is called to rebuild it.|
+| [OH_PurgeableMemory_EndRead](#oh_purgeablememory_endread) ([OH_PurgeableMemory](#oh_purgeablememory) \*purgObj) | Ends a read operation on a **PurgeableMemory** object. Now the system can reclaim purgeable memory.|
+| [OH_PurgeableMemory_BeginWrite](#oh_purgeablememory_beginwrite) ([OH_PurgeableMemory](#oh_purgeablememory) \*purgObj) | Begins a write operation on the **PurgeableMemory** object. If purgeable memory is reclaimed, the rebuilding function is called to rebuild it.|
+| [OH_PurgeableMemory_EndWrite](#oh_purgeablememory_endwrite) ([OH_PurgeableMemory](#oh_purgeablememory) \*purgObj) | Ends a write operation on the **PurgeableMemory** object. Now the system can reclaim purgeable memory.|
+| [OH_PurgeableMemory_GetContent](#oh_purgeablememory_getcontent) ([OH_PurgeableMemory](#oh_purgeablememory) \*purgObj) | Obtains the memory data of a **PurgeableMemory** object.|
+| [OH_PurgeableMemory_ContentSize](#oh_purgeablememory_contentsize) ([OH_PurgeableMemory](#oh_purgeablememory) \*purgObj) | Obtains the memory data size of a **PurgeableMemory** object.|
+| [OH_PurgeableMemory_AppendModify](#oh_purgeablememory_appendmodify) ([OH_PurgeableMemory](#oh_purgeablememory) \*purgObj, [OH_PurgeableMemory_ModifyFunc](#oh_purgeablememory_modifyfunc) func, void \*funcPara) | Adds a function for modifying a **PurgeableMemory** object.|
+
+
+## Type Description
+
+
+### OH_PurgeableMemory
+
+
+```
+typedef struct OH_PurgeableMemoryOH_PurgeableMemory
+```
+
+**Description**
+
+Defines the type name of the **OH_PurgeableMemory** data.
+
+**Since**
+
+10
+
+
+### OH_PurgeableMemory_ModifyFunc
+
+
+```
+typedef bool(* OH_PurgeableMemory_ModifyFunc) (void *, size_t, void *)
+```
+
+**Description**
+
+Defines the function for rebuilding purgeable memory data.
+
+**Parameters**
+
+| Name| Description|
+| -------- | -------- |
+| void \* | Pointer to the address of purgeable memory.|
+| size_t | Size of the memory data to rebuild.|
+| void \* | Pointer to the parameters used for rebuilding.|
+
+**Returns**
+
+Returns a success message if the operation is successful; returns a failure message otherwise.
+
+**Since**
+
+10
+
+
+## Function Description
+
+
+### OH_PurgeableMemory_AppendModify()
+
+
+```
+bool OH_PurgeableMemory_AppendModify (OH_PurgeableMemory * purgObj, OH_PurgeableMemory_ModifyFunc func, void * funcPara )
+```
+
+**Description**
+
+Adds a function for modifying a **PurgeableMemory** object.
+
+**Parameters**
+
+| Name| Description|
+| -------- | -------- |
+| purgObj | Pointer to the **PurgeableMemory** object.|
+| func | Function pointer to the modify function, which is used for further modification after the purgeable memory data is rebuilt.|
+| funcPara | Pointer to the parameters of the modify function.|
+
+**Returns**
+
+Returns a success message if the operation is successful; returns a failure message otherwise.
+
+**Since**
+
+10
+
+
+### OH_PurgeableMemory_BeginRead()
+
+
+```
+bool OH_PurgeableMemory_BeginRead (OH_PurgeableMemory * purgObj)
+```
+
+**Description**
+
+Starts a read operation on a **PurgeableMemory** object. If purgeable memory is reclaimed, the rebuilding function is called to rebuild it.
+
+**Parameters**
+
+| Name| Description|
+| -------- | -------- |
+| purgObj | Pointer to the **PurgeableMemory** object.|
+
+**Returns**
+
+Returns a success message if the purgeable memory data is ready; returns a failure message if purgeable memory has been reclaimed and fails to be rebuilt.
+
+**Since**
+
+10
+
+
+### OH_PurgeableMemory_BeginWrite()
+
+
+```
+bool OH_PurgeableMemory_BeginWrite (OH_PurgeableMemory * purgObj)
+```
+
+**Description**
+
+Begins a write operation on the **PurgeableMemory** object. If purgeable memory is reclaimed, the rebuilding function is called to rebuild it.
+
+**Parameters**
+
+| Name| Description|
+| -------- | -------- |
+| purgObj | Pointer to the **PurgeableMemory** object.|
+
+**Returns**
+
+Returns a success message if the purgeable memory data is ready; returns a failure message if purgeable memory has been reclaimed and fails to be rebuilt.
+
+**Since**
+
+10
+
+
+### OH_PurgeableMemory_ContentSize()
+
+
+```
+size_t OH_PurgeableMemory_ContentSize (OH_PurgeableMemory * purgObj)
+```
+
+**Description**
+
+Obtains the memory data size of a **PurgeableMemory** object.
+
+**Parameters**
+
+| Name| Description|
+| -------- | -------- |
+| purgObj | Pointer to the **PurgeableMemory** object. |
+
+**Returns**
+
+Returns the memory data size.
+
+**Since**
+
+10
+
+
+### OH_PurgeableMemory_Create()
+
+
+```
+OH_PurgeableMemory* OH_PurgeableMemory_Create (size_t size, OH_PurgeableMemory_ModifyFunc func, void * funcPara )
+```
+
+**Description**
+
+Creates a **PurgeableMemory** object.
+
+**Parameters**
+
+| Name| Description|
+| -------- | -------- |
+| size | Size of the **PurgeableMemory** object.|
+| func | Function pointer to the rebuilding function, which is used to restore the reclaimed purgeable memory data.|
+| funcPara | Pointer to the parameters of the rebuilding function.|
+
+**Returns**
+
+Returns the **PurgeableMemory** object.
+
+**Since**
+
+10
+
+
+### OH_PurgeableMemory_Destroy()
+
+
+```
+bool OH_PurgeableMemory_Destroy (OH_PurgeableMemory * purgObj)
+```
+
+**Description**
+
+Destroys a **PurgeableMemory** object.
+
+**Parameters**
+
+| Name| Description|
+| -------- | -------- |
+| purgObj | Pointer to the **PurgeableMemory** object.|
+
+**Returns**
+
+Returns a success message if the operation is successful; returns a failure message otherwise. If no value is passed, a failure message is returned. If a success message is returned, the value of **purgObj** will be cleared to avoid Use-After-Free (UAF).
+
+**Since**
+
+10
+
+
+### OH_PurgeableMemory_EndRead()
+
+
+```
+void OH_PurgeableMemory_EndRead (OH_PurgeableMemory * purgObj)
+```
+
+**Description**
+
+Ends a read operation on a **PurgeableMemory** object. Now the system can reclaim purgeable memory.
+
+**Parameters**
+
+| Name| Description|
+| -------- | -------- |
+| purgObj | Pointer to the **PurgeableMemory** object.|
+
+**Since**
+
+10
+
+
+### OH_PurgeableMemory_EndWrite()
+
+
+```
+void OH_PurgeableMemory_EndWrite (OH_PurgeableMemory * purgObj)
+```
+
+**Description**
+
+Ends a write operation on the **PurgeableMemory** object. Now the system can reclaim purgeable memory.
+
+**Parameters**
+
+| Name| Description|
+| -------- | -------- |
+| purgObj | Pointer to the **PurgeableMemory** object.|
+
+**Since**
+
+10
+
+
+### OH_PurgeableMemory_GetContent()
+
+
+```
+void* OH_PurgeableMemory_GetContent (OH_PurgeableMemory * purgObj)
+```
+
+**Description**
+
+Obtains the memory data of a **PurgeableMemory** object.
+
+**Parameters**
+
+| Name| Description|
+| -------- | -------- |
+| purgObj | Pointer to the **PurgeableMemory** object. |
+
+**Returns**
+
+Returns the pointer to the purgeable memory address.
+
+**Since**
+
+10

en/application-dev/reference/native-apis/purgeable__memory_8h.md

+# purgeable_memory.h
+
+
+## Overview
+
+Declares the APIs for managing purgeable memory at the native layer.
+
+**Since**
+
+10
+
+**Related Modules**
+
+[Memory](memory.md)
+
+
+## Summary
+
+
+### Types
+
+| Name| Description|
+| -------- | -------- |
+| [OH_PurgeableMemory](memory.md#oh_purgeablememory) | Defines the type name of the **OH_PurgeableMemory** data.|
+| (\*[OH_PurgeableMemory_ModifyFunc](memory.md#oh_purgeablememory_modifyfunc)) (void \*, size_t, void \*) | Defines the function for rebuilding purgeable memory data.|
+
+
+### Functions
+
+| Name| Description|
+| -------- | -------- |
+| \*[OH_PurgeableMemory_Create](memory.md#oh_purgeablememory_create) (size_t size, [OH_PurgeableMemory_ModifyFunc](memory.md#oh_purgeablememory_modifyfunc) func, void \*funcPara) | Creates a **PurgeableMemory** object.|
+| [OH_PurgeableMemory_Destroy](memory.md#oh_purgeablememory_destroy) ([OH_PurgeableMemory](memory.md#oh_purgeablememory) \*purgObj) | Destroys a **PurgeableMemory** object.|
+| [OH_PurgeableMemory_BeginRead](memory.md#oh_purgeablememory_beginread) ([OH_PurgeableMemory](memory.md#oh_purgeablememory) \*purgObj) | Starts a read operation on a **PurgeableMemory** object. If purgeable memory is reclaimed, the rebuilding function is called to rebuild it.|
+| [OH_PurgeableMemory_EndRead](memory.md#oh_purgeablememory_endread) ([OH_PurgeableMemory](memory.md#oh_purgeablememory) \*purgObj) | Ends a read operation on a **PurgeableMemory** object. Now the system can reclaim purgeable memory.|
+| [OH_PurgeableMemory_BeginWrite](memory.md#oh_purgeablememory_beginwrite) ([OH_PurgeableMemory](memory.md#oh_purgeablememory) \*purgObj) | Begins a write operation on the **PurgeableMemory** object. If purgeable memory is reclaimed, the rebuilding function is called to rebuild it.|
+| [OH_PurgeableMemory_EndWrite](memory.md#oh_purgeablememory_endwrite) ([OH_PurgeableMemory](memory.md#oh_purgeablememory) \*purgObj) | Ends a write operation on the **PurgeableMemory** object. Now the system can reclaim purgeable memory.|
+| [OH_PurgeableMemory_GetContent](memory.md#oh_purgeablememory_getcontent) ([OH_PurgeableMemory](memory.md#oh_purgeablememory) \*purgObj) | Obtains the memory data of a **PurgeableMemory** object.|
+| [OH_PurgeableMemory_ContentSize](memory.md#oh_purgeablememory_contentsize) ([OH_PurgeableMemory](memory.md#oh_purgeablememory) \*purgObj) | Obtains the memory data size of a **PurgeableMemory** object.|
+| [OH_PurgeableMemory_AppendModify](memory.md#oh_purgeablememory_appendmodify) ([OH_PurgeableMemory](memory.md#oh_purgeablememory) \*purgObj, [OH_PurgeableMemory_ModifyFunc](memory.md#oh_purgeablememory_modifyfunc) func, void \*funcPara) | Adds a function for modifying a **PurgeableMemory** object.|