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

Name	typedef Keyword	Description
typedef bool (OH_PurgeableMemory_ModifyFunc)(void , size_t, void *)	OH_PurgeableMemory_ModifyFunc	Pointer to a function used to construct the content of a purgeable memory object.
OH_PurgeableMemory OH_PurgeableMemory_Create(size_t size, OH_PurgeableMemory_ModifyFunc func, void funcPara)	-	Creates a PurgMem object.
bool OH_PurgeableMemory_Destroy(OH_PurgeableMemory *purgObj)	-	Destroys a PurgMem object.
bool OH_PurgeableMemory_BeginRead(OH_PurgeableMemory *purgObj)	-	Starts reading a PurgMem object.
void OH_PurgeableMemory_EndRead(OH_PurgeableMemory *purgObj)	-	Stops reading a PurgMem object.
bool OH_PurgeableMemory_BeginWrite(OH_PurgeableMemory *purgObj)	-	Starts writing a PurgMem object.
void OH_PurgeableMemory_EndWrite(OH_PurgeableMemory *purgObj)	-	Stops writing a PurgMem object.
void OH_PurgeableMemory_GetContent(OH_PurgeableMemory purgObj)	-	Obtains the content of a PurgMem object.
size_t OH_PurgeableMemory_ContentSize(OH_PurgeableMemory *purgObj)	-	Obtains the content size of a PurgMem object.
bool OH_PurgeableMemory_AppendModify(OH_PurgeableMemory purgObj, OH_PurgeableMemory_ModifyFunc func, void funcPara)	-	Appends the modification to a PurgMem object.

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.

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.

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