1 /* 2 * Copyright (c) 2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef OHOS_UTILS_MEMORY_LIBPURGEABLEMEM_C_INCLUDE_PURGEABLE_MEM_C_H 17 #define OHOS_UTILS_MEMORY_LIBPURGEABLEMEM_C_INCLUDE_PURGEABLE_MEM_C_H 18 19 #include <stdbool.h> /* bool */ 20 #include <stddef.h> /* size_t */ 21 22 #ifdef __cplusplus 23 #if __cplusplus 24 extern "C" { 25 #endif /* End of #if __cplusplus */ 26 #endif /* End of #ifdef __cplusplus */ 27 28 /* Purgeable mem struct */ 29 struct PurgMem; 30 31 /* 32 * Function pointer, it points to a function which build content of a PurgMem obj. 33 * Input: void *: data ptr, points to start address of a PurgMem obj's content. 34 * Input: size_t: data size of the content. 35 * Input: void *: other private parameters. 36 * Return: build content result, true means success, while false is fail. 37 */ 38 typedef bool (*PurgMemModifyFunc)(void *, size_t, void *); 39 40 /* 41 * PurgMemCreate: create a PurgMem obj. 42 * Input: @size: data size of a PurgMem obj's content. 43 * Input: @func: function pointer, it recover data when the PurgMem obj's content is purged. 44 * Input: @funcPara: parameters used by @func. 45 * Return: a PurgMem obj. 46 */ 47 struct PurgMem *PurgMemCreate(size_t size, PurgMemModifyFunc func, void *funcPara); 48 49 /* 50 * PurgMemDestroy: destroy a PurgMem obj. 51 * Input: @purgObj: a PurgMem obj to be destroyed. 52 * Return: true is success, while false is fail. return true if @purgObj is NULL. 53 * If return true, @purgObj will be set to NULL to avoid Use-After-Free. 54 */ 55 bool PurgMemDestroy(struct PurgMem *purgObj); 56 57 /* 58 * PurgMemBeginRead: begin read a PurgMem obj. 59 * Input: @purgObj: a PurgMem obj. 60 * Return: return true if @purgObj's content is present. 61 * If content is purged(no present), system will recover its data, 62 * return false if content is purged and recover failed. 63 * While return true if content recover success. 64 * OS cannot reclaim the memory of @purgObj's content when this 65 * function return true, until PurgMemEndRead() is called. 66 */ 67 bool PurgMemBeginRead(struct PurgMem *purgObj); 68 69 /* 70 * PurgMemEndRead: end read a PurgMem obj. 71 * Input: @purgObj: a PurgMem obj. 72 * OS may reclaim the memory of @purgObj's content 73 * at a later time when this function returns. 74 */ 75 void PurgMemEndRead(struct PurgMem *purgObj); 76 77 /* 78 * PurgMemBeginWrite: begin write a PurgMem obj. 79 * Input: @purgObj: a PurgMem obj. 80 * Return: return true if @purgObj's content is present. 81 * if content is purged(no present), system will recover its data, 82 * return false if content is purged and recover failed. 83 * While return true if content recover success. 84 * OS cannot reclaim the memory of @purgObj's content when this 85 * function return true, until PurgMemEndWrite() is called. 86 */ 87 bool PurgMemBeginWrite(struct PurgMem *purgObj); 88 89 /* 90 * PurgMemEndWrite: end write a PurgMem obj. 91 * Input: @purgObj: a PurgMem obj. 92 * OS may reclaim the memory of @purgObj's content 93 * at a later time when this function returns. 94 */ 95 void PurgMemEndWrite(struct PurgMem *purgObj); 96 97 /* 98 * PurgMemGetContent: get content ptr of a PurgMem obj. 99 * Input: @purgObj: a PurgMem obj. 100 * Return: return start address of a PurgMem obj's content. 101 * Return NULL if @purgObj is NULL. 102 * This function should be protect by PurgMemBeginRead()/PurgMemEndRead() 103 * or PurgMemBeginWrite()/PurgMemEndWrite() 104 */ 105 void *PurgMemGetContent(struct PurgMem *purgObj); 106 107 /* 108 * PurgMemGetContentSize: get content size of a PurgMem obj. 109 * Input: @purgObj: a PurgMem obj. 110 * Return: return content size of @purgObj. 111 * Return 0 if @purgObj is NULL. 112 */ 113 size_t PurgMemGetContentSize(struct PurgMem *purgObj); 114 115 /* 116 * PurgMemAppendModify: append a modify to a PurgMem obj. 117 * Input: @purgObj: a PurgMem obj. 118 * Input: @size: data size of a PurgMem obj's content. 119 * Input: @func: function pointer, it will modify content of @PurgMem. 120 * Input: @funcPara: parameters used by @func. 121 * Return: append result, true is success, while false is fail. 122 */ 123 bool PurgMemAppendModify(struct PurgMem *purgObj, PurgMemModifyFunc func, void *funcPara); 124 125 #ifdef __cplusplus 126 #if __cplusplus 127 } 128 #endif /* End of #if __cplusplus */ 129 #endif /* End of #ifdef __cplusplus */ 130 131 #endif /* OHOS_UTILS_MEMORY_LIBPURGEABLEMEM_C_INCLUDE_PURGEABLE_MEM_C_H */ 132