purgeable_memory.h
Overview
Provides APIs for managing the purgeable memory.
For example, you can create a purgeable memory, start or end the memory reading/writing, and rebuild the memory.
Link to the libpurgeable_memory_ndk.z.so file when you use the API.
File to include: <purgeable_memory/purgeable_memory.h>
Library: libpurgeable_memory_ndk.z.so
System capability: SystemCapability.Kernel.Memory
Since: 10
Related module: memory
Summary
Structs
| Name | typedef Keyword | Description |
|---|---|---|
| PurgMem | OH_PurgeableMemory | Defines a purgeable memory struct. |
Functions
Function Description
OH_PurgeableMemory_ModifyFunc()
typedef bool (*OH_PurgeableMemory_ModifyFunc)(void *, size_t, void *)
Description
Pointer to a function used to construct the content of a purgeable memory object.
Since: 10
Parameters
| Name | Description |
|---|---|
| void * | Pointer to the start address of the content of a purgeable memory object. |
| size_t | Data size of the content. |
| void * | Pointer to other private parameters. |
Returns
| Type | Description |
|---|---|
| bool | Whether the content is successfully constructed. The value true indicates that the operation is successful, and false indicates the opposite. |
OH_PurgeableMemory_Create()
OH_PurgeableMemory *OH_PurgeableMemory_Create(size_t size, OH_PurgeableMemory_ModifyFunc func, void *funcPara)
Description
Creates a PurgMem object.
Since: 10
Parameters
| Name | Description |
|---|---|
| size_t size | Data size of the content of a purgeable memory object. |
| OH_PurgeableMemory_ModifyFunc func | Function used to restore data when the content of a purgeable memory object is cleared. |
| void *funcPara | Pointer to the parameter used by @func. |
Returns
| Type | Description |
|---|---|
| OH_PurgeableMemory * | Returns the purgeable memory object created. |
OH_PurgeableMemory_Destroy()
bool OH_PurgeableMemory_Destroy(OH_PurgeableMemory *purgObj)
Description
Destroys a PurgMem object.
Since: 10
Parameters
| Name | Description |
|---|---|
| OH_PurgeableMemory *purgObj | Pointer to the purgeable memory object to be destroyed. |
Returns
| Type | Description |
|---|---|
| bool | Whether the destruction is successful. The value true indicates that the destruction is successful, and false indicates the opposite. Returns true if the purgeable memory object is NULL. Returns true if the destruction is successful. The purgeable memory object is set to NULL to avoid Use-After-Free. |
OH_PurgeableMemory_BeginRead()
bool OH_PurgeableMemory_BeginRead(OH_PurgeableMemory *purgObj)
Description
Starts reading a PurgMem object.
Since: 10
Parameters
| Name | Description |
|---|---|
| OH_PurgeableMemory *purgObj | Pointer to the purgeable memory object. |
Returns
| Type | Description |
|---|---|
| bool | Whether the reading is successful. Returns true if the content of the purgeable memory object exists. If the content is cleared (that is, the content does not exist), the system attempts to restore the data. Returns false if the restore fails. Returns true if the restore is successful. When this function returns true, the system cannot reclaim the memory of the content of the purgeable memory object until OH_PurgeableMemory_EndRead() is called. |
OH_PurgeableMemory_EndRead()
void OH_PurgeableMemory_EndRead(OH_PurgeableMemory *purgObj)
Description
Stops reading a PurgMem object.
Since: 10
Parameters
| Name | Description |
|---|---|
| OH_PurgeableMemory *purgObj | Pointer to the purgeable memory object. When this function ends, the OS may reclaim the memory of the content of the purgeable memory object later. |
OH_PurgeableMemory_BeginWrite()
bool OH_PurgeableMemory_BeginWrite(OH_PurgeableMemory *purgObj)
Description
Starts writing a PurgMem object.
Since: 10
Parameters
| Name | Description |
|---|---|
| OH_PurgeableMemory *purgObj | Pointer to the purgeable memory object. |
Returns
| Type | Description |
|---|---|
| bool | Whether the content of the purgeable memory object exists. Returns true if the content exists. If the content is cleared, the system restores its data. Returns false if the content is cleared and the restore fails. Returns true if the restore is successful. When this function returns true, the OS cannot reclaim the memory of the content of the purgeable memory object until OH_PurgeableMemory_EndWrite() is called. |
OH_PurgeableMemory_EndWrite()
void OH_PurgeableMemory_EndWrite(OH_PurgeableMemory *purgObj)
Description
Stops writing a PurgMem object.
Since: 10
Parameters
| Name | Description |
|---|---|
| OH_PurgeableMemory *purgObj | Pointer to the purgeable memory object. When this function ends, the OS may reclaim the memory of the content of the purgeable memory object later. |
OH_PurgeableMemory_GetContent()
void *OH_PurgeableMemory_GetContent(OH_PurgeableMemory *purgObj)
Description
Obtains the content of a PurgMem object.
Since: 10
Parameters
| Name | Description |
|---|---|
| OH_PurgeableMemory *purgObj | Pointer to the purgeable memory object. |
Returns
| Type | Description |
|---|---|
| void * | Returns the start address of the content of the purgeable memory object. Returns NULL if the purgeable memory object is NULL. This function should be protected by OH_PurgeableMemory_BeginRead()/OH_PurgeableMemory_EndRead() or OH_PurgeableMemory_BeginWrite()/OH_PurgeableMemory_EndWrite(). |
OH_PurgeableMemory_ContentSize()
size_t OH_PurgeableMemory_ContentSize(OH_PurgeableMemory *purgObj)
Description
Obtains the content size of a PurgMem object.
Since: 10
Parameters
| Name | Description |
|---|---|
| OH_PurgeableMemory *purgObj | Pointer to the purgeable memory object. |
Returns
| Type | Description |
|---|---|
| size_t | Returns the content size of the purgeable memory object obtained. Returns 0 if the purgeable memory object is NULL. |
OH_PurgeableMemory_AppendModify()
bool OH_PurgeableMemory_AppendModify(OH_PurgeableMemory *purgObj, OH_PurgeableMemory_ModifyFunc func, void *funcPara)
Description
Appends the modification to a PurgMem object.
Since: 10
Parameters
| Name | Description |
|---|---|
| OH_PurgeableMemory *purgObj | Pointer to the purgeable memory object. |
| OH_PurgeableMemory_ModifyFunc func | Function used to modify the content of a purgeable memory object. |
| void *funcPara | Pointer to the parameter used by @func. |
Returns
| Type | Description |
|---|---|
| bool | Returns the operation result. The value true indicates that the operation is successful, and false indicates the opposite. |