1 /* 2 * Copyright (c) 2023 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 /** 17 * @addtogroup memory 18 * 19 * @brief provides memory management capabilities 20 * 21 * provides features include operations such as memory alloction, memory free, and so on 22 * 23 * @since 10 24 * @version 1.0 25 */ 26 27 /** 28 * @file purgeable_memory.h 29 * 30 * @brief provides memory management capabilities of purgeable memory. 31 * 32 * provides features include create, begin read ,end read, begin write, end write, rebuild, and so on. 33 * when using, it is necessary to link libpurgeable_memory_ndk.z.so 34 * 35 * @since 10 36 * @version 1.0 37 */ 38 39 #ifndef OHOS_UTILS_MEMORY_LIBPURGEABLEMEM_C_INCLUDE_PURGEABLE_MEMORY_H 40 #define OHOS_UTILS_MEMORY_LIBPURGEABLEMEM_C_INCLUDE_PURGEABLE_MEMORY_H 41 42 #include <stdbool.h> /* bool */ 43 #include <stddef.h> /* size_t */ 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif /* End of #ifdef __cplusplus */ 48 49 /* 50 * @brief Purgeable mem struct 51 * 52 * @since 10 53 * @version 1.0 54 */ 55 typedef struct PurgMem OH_PurgeableMemory; 56 57 /* 58 * @brief: function pointer, it points to a function which is used to build content of a PurgMem obj. 59 * 60 * 61 * @param void *: data ptr, points to start address of a PurgMem obj's content. 62 * @param size_t: data size of the content. 63 * @param void *: other private parameters. 64 * @return: build content result, true means success, while false is fail. 65 * 66 * @since 10 67 * @version 1.0 68 */ 69 typedef bool (*OH_PurgeableMemory_ModifyFunc)(void *, size_t, void *); 70 71 /* 72 * @brief: create a PurgMem obj. 73 * 74 * 75 * @param size: data size of a PurgMem obj's content. 76 * @param func: function pointer, it is used to recover data when the PurgMem obj's content is purged. 77 * @param funcPara: parameters used by @func. 78 * @return: a PurgMem obj. 79 * 80 * @since 10 81 * @version 1.0 82 */ 83 OH_PurgeableMemory *OH_PurgeableMemory_Create( 84 size_t size, OH_PurgeableMemory_ModifyFunc func, void *funcPara); 85 86 /* 87 * @brief: destroy a PurgMem obj. 88 * 89 * 90 * @param purgObj: a PurgMem obj to be destroyed. 91 * @return: true is success, while false is fail. return true if @purgObj is NULL. 92 * If return true, @purgObj will be set to NULL to avoid Use-After-Free. 93 * 94 * @since 10 95 * @version 1.0 96 */ 97 bool OH_PurgeableMemory_Destroy(OH_PurgeableMemory *purgObj); 98 99 /* 100 * @brief: begin read a PurgMem obj. 101 * 102 * 103 * @param purgObj: a PurgMem obj. 104 * @return: return true if @purgObj's content is present. 105 * If content is purged(no present), system will recover its data, 106 * return false if content is purged and recovered failed. 107 * While return true if content recover success. 108 * OS cannot reclaim the memory of @purgObj's content when this 109 * function return true, until PurgMemEndRead() is called. 110 * 111 * Attension: the return value must be recevied and handled, 112 * since the visiting of this object with the failure result 113 * will cause unsuspected result. 114 * For example: 115 * if (OH_PurgeableMemory_BeginRead()) { 116 * // visit this object 117 * OH_PurgeableMemory_EndRead(); 118 * } 119 * 120 * @since 10 121 * @version 1.0 122 */ 123 bool OH_PurgeableMemory_BeginRead(OH_PurgeableMemory *purgObj); 124 125 /* 126 * @brief: end read a PurgMem obj. 127 * 128 * 129 * @param purgObj: a PurgMem obj. 130 * OS may reclaim the memory of @purgObj's content 131 * at a later time when this function returns. 132 * 133 * @since 10 134 * @version 1.0 135 */ 136 void OH_PurgeableMemory_EndRead(OH_PurgeableMemory *purgObj); 137 138 /* 139 * @brief: begin write a PurgMem obj. 140 * 141 * 142 * @param purgObj: a PurgMem obj. 143 * @return: return true if @purgObj's content is present. 144 * if content is purged(no present), system will recover its data, 145 * return false if content is purged and recovered failed. 146 * While return true if content is successfully recovered. 147 * OS cannot reclaim the memory of @purgObj's content when this 148 * function return true, until PurgMemEndWrite() is called. 149 * 150 * Attension: the return value must be recevied and handled, 151 * since the visiting of this object with the failure result 152 * will cause unsuspected result. 153 * For example: 154 * if (OH_PurgeableMemory_BeginWrite()) { 155 * // visit this object 156 * OH_PurgeableMemory_EndWrite(); 157 * } 158 * 159 * @since 10 160 * @version 1.0 161 */ 162 bool OH_PurgeableMemory_BeginWrite(OH_PurgeableMemory *purgObj); 163 164 /* 165 * @brief: end write a PurgMem obj. 166 * 167 * 168 * @param purgObj: a PurgMem obj. 169 * OS may reclaim the memory of @purgObj's content 170 * at a later time when this function returns. 171 * 172 * @since 10 173 * @version 1.0 174 */ 175 void OH_PurgeableMemory_EndWrite(OH_PurgeableMemory *purgObj); 176 177 /* 178 * @brief: get content ptr of a PurgMem obj. 179 * 180 * 181 * @param purgObj: a PurgMem obj. 182 * @return: return start address of a PurgMem obj's content. 183 * Return NULL if @purgObj is NULL. 184 * This function should be protect by PurgMemBeginRead()/PurgMemEndRead() 185 * or PurgMemBeginWrite()/PurgMemEndWrite() 186 * 187 * @since 10 188 * @version 1.0 189 */ 190 void *OH_PurgeableMemory_GetContent(OH_PurgeableMemory *purgObj); 191 192 /* 193 * @brief: get content size of a PurgMem obj. 194 * 195 * 196 * @param purgObj: a PurgMem obj. 197 * @return: return content size of @purgObj. 198 * Return 0 if @purgObj is NULL. 199 * 200 * @since 10 201 * @version 1.0 202 */ 203 size_t OH_PurgeableMemory_ContentSize(OH_PurgeableMemory *purgObj); 204 205 /* 206 * @brief: append a modify to a PurgMem obj. 207 * 208 * 209 * @param purgObj: a PurgMem obj. 210 * @param size: data size of a PurgMem obj's content. 211 * @param func: function pointer, it will modify content of @PurgMem. 212 * @param funcPara: parameters used by @func. 213 * @return: append result, true is success, while false is fail. 214 * 215 * @since 10 216 * @version 1.0 217 */ 218 bool OH_PurgeableMemory_AppendModify(OH_PurgeableMemory *purgObj, 219 OH_PurgeableMemory_ModifyFunc func, void *funcPara); 220 221 #ifdef __cplusplus 222 } 223 #endif /* End of #ifdef __cplusplus */ 224 #endif /* OHOS_UTILS_MEMORY_LIBPURGEABLEMEM_C_INCLUDE_PURGEABLE_MEMORY_H */