• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 */