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
24extern "C" {
25#endif /* End of #if __cplusplus */
26#endif /* End of #ifdef __cplusplus */
27
28/* Purgeable mem struct */
29struct 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 */
38typedef 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 */
47struct 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 */
55bool 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 */
67bool 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 */
75void 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 */
87bool 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 */
95void 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 */
105void *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 */
113size_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 */
123bool 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