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 * @since 10 112 * @version 1.0 113 */ 114 bool OH_PurgeableMemory_BeginRead(OH_PurgeableMemory *purgObj); 115 116 /* 117 * @brief: end read a PurgMem obj. 118 * 119 * 120 * @param purgObj: a PurgMem obj. 121 * OS may reclaim the memory of @purgObj's content 122 * at a later time when this function returns. 123 * 124 * @since 10 125 * @version 1.0 126 */ 127 void OH_PurgeableMemory_EndRead(OH_PurgeableMemory *purgObj); 128 129 /* 130 * @brief: begin write a PurgMem obj. 131 * 132 * 133 * @param purgObj: a PurgMem obj. 134 * @return: return true if @purgObj's content is present. 135 * if content is purged(no present), system will recover its data, 136 * return false if content is purged and recovered failed. 137 * While return true if content is successfully recovered. 138 * OS cannot reclaim the memory of @purgObj's content when this 139 * function return true, until PurgMemEndWrite() is called. 140 * 141 * @since 10 142 * @version 1.0 143 */ 144 bool OH_PurgeableMemory_BeginWrite(OH_PurgeableMemory *purgObj); 145 146 /* 147 * @brief: end write a PurgMem obj. 148 * 149 * 150 * @param purgObj: a PurgMem obj. 151 * OS may reclaim the memory of @purgObj's content 152 * at a later time when this function returns. 153 * 154 * @since 10 155 * @version 1.0 156 */ 157 void OH_PurgeableMemory_EndWrite(OH_PurgeableMemory *purgObj); 158 159 /* 160 * @brief: get content ptr of a PurgMem obj. 161 * 162 * 163 * @param purgObj: a PurgMem obj. 164 * @return: return start address of a PurgMem obj's content. 165 * Return NULL if @purgObj is NULL. 166 * This function should be protect by PurgMemBeginRead()/PurgMemEndRead() 167 * or PurgMemBeginWrite()/PurgMemEndWrite() 168 * 169 * @since 10 170 * @version 1.0 171 */ 172 void *OH_PurgeableMemory_GetContent(OH_PurgeableMemory *purgObj); 173 174 /* 175 * @brief: get content size of a PurgMem obj. 176 * 177 * 178 * @param purgObj: a PurgMem obj. 179 * @return: return content size of @purgObj. 180 * Return 0 if @purgObj is NULL. 181 * 182 * @since 10 183 * @version 1.0 184 */ 185 size_t OH_PurgeableMemory_ContentSize(OH_PurgeableMemory *purgObj); 186 187 /* 188 * @brief: append a modify to a PurgMem obj. 189 * 190 * 191 * @param purgObj: a PurgMem obj. 192 * @param size: data size of a PurgMem obj's content. 193 * @param func: function pointer, it will modify content of @PurgMem. 194 * @param funcPara: parameters used by @func. 195 * @return: append result, true is success, while false is fail. 196 * 197 * @since 10 198 * @version 1.0 199 */ 200 bool OH_PurgeableMemory_AppendModify(OH_PurgeableMemory *purgObj, 201 OH_PurgeableMemory_ModifyFunc func, void *funcPara); 202 203 #ifdef __cplusplus 204 } 205 #endif /* End of #ifdef __cplusplus */ 206 #endif /* OHOS_UTILS_MEMORY_LIBPURGEABLEMEM_C_INCLUDE_PURGEABLE_MEMORY_H */