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