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 #ifndef OHOS_UTILS_MEMORY_LIBPURGEABLEMEM_CPP_INCLUDE_PURGEABLE_MEM_BASE_H
17 #define OHOS_UTILS_MEMORY_LIBPURGEABLEMEM_CPP_INCLUDE_PURGEABLE_MEM_BASE_H
18 
19 #ifndef OHOS_MAXIMUM_PURGEABLE_MEMORY
20 #define OHOS_MAXIMUM_PURGEABLE_MEMORY ((1024) * (1024) * (1024)) /* 1G */
21 #endif /* OHOS_MAXIMUM_PURGEABLE_MEMORY */
22 
23 #include <memory> /* unique_ptr */
24 #include <shared_mutex> /* shared_mutex */
25 #include <string>
26 
27 #include "purgeable_mem_builder.h"
28 #include "ux_page_table.h"
29 
30 namespace OHOS {
31 namespace PurgeableMem {
32 class PurgeableMemBase {
33 public:
34     /*
35      * BeginRead: begin read the PurgeableMem obj.
36      * Return:  return true if the obj's content is present.
37      *          If content is purged(no present), system will recover its data,
38      *          return false if content is purged and recover failed.
39      *          While return true if content recover success.
40      * OS cannot reclaim the memory of the obj's content when this
41      * function return true, until EndRead() is called.
42      *
43      * Attension: the return value must be recevied and handled,
44      *            since the visiting of this object with the failure result
45      *            will cause unsuspected result.
46      * For example:
47      *               if (BeginRead()) {
48      *                   // visit this object
49      *                   EndRead();
50      *               }
51      */
52     bool BeginRead();
53 
54     /*
55      * EndRead: end read the PurgeableMem obj.
56      * OS may reclaim the memory of its content
57      * at a later time when this function returns.
58      */
59     void EndRead();
60 
61     /*
62      * BeginRead: begin write the PurgeableMem obj.
63      * Return:  return true if the obj's content is present.
64      *          If content is purged(no present), system will recover its data,
65      *          return false if content is purged and recover failed.
66      *          While return true if content recover success.
67      * OS cannot reclaim the memory of the obj's content when this
68      * function return true, until EndWrite() is called.
69      *
70      * Attension: the return value must be recevied and handled,
71      *            since the visiting of this object with the failure result
72      *            will cause unsuspected result.
73      * For example:
74      *               if (BeginWrite()) {
75      *                   // visit this object
76      *                   EndWrite();
77      *               }
78      */
79 
80     bool BeginWrite();
81 
82     /*
83      * EndWrite: end write the PurgeableMem obj.
84      * OS may reclaim the memory of its content
85      * at a later time when this function returns.
86      */
87     void EndWrite();
88 
89     /*
90      * ModifyContentByBuilder: append a PurgeableMemBuilder obj to the PurgeableMem obj.
91      * Input:   @modifier: unique_ptr of PurgeableMemBuilder, it will modify content of this obj.
92      * Return:  modify result, true is success, while false is fail.
93      * This function should be protected by BeginWrite()/EndWrite().
94      */
95     bool ModifyContentByBuilder(std::unique_ptr<PurgeableMemBuilder> modifier);
96 
97     /*
98      * GetContent: get content ptr of the PurgeableMem obj.
99      * Return:  return the content ptr, which is start address of the obj's content.
100      * This function should be protected by BeginRead()/EndRead()
101      * or BeginWrite()/EndWrite().
102      */
103     void *GetContent();
104 
105     /*
106      * GetContentSize: get content size of the PurgeableMem obj.
107      * Return:  return content size of the obj's content.
108      */
109     size_t GetContentSize();
110 
111     /*
112      * ResizeData: resize size of the PurgeableMem obj.
113      */
114     virtual void ResizeData(size_t newSize);
115     void SetRebuildSuccessCallback(std::function<void()> &callback);
116     bool IsDataValid();
117     void SetDataValid(bool target);
118 
119     PurgeableMemBase();
120     virtual ~PurgeableMemBase();
121     PurgeableMemBase(const PurgeableMemBase&) = delete;
122     PurgeableMemBase& operator = (PurgeableMemBase&) = delete;
123     PurgeableMemBase(PurgeableMemBase&&) noexcept = delete;
124     PurgeableMemBase& operator = (PurgeableMemBase&&) noexcept = delete;
125     virtual int GetPinStatus() const;
126     virtual bool Pin();
127 
128 protected:
129     void *dataPtr_ = nullptr;
130     std::mutex dataLock_;
131     bool isDataValid_ {true};
132     size_t dataSizeInput_ = 0;
133     std::unique_ptr<PurgeableMemBuilder> builder_ = nullptr;
134     unsigned int buildDataCount_ = 0;
135     bool BuildContent();
136     bool IfNeedRebuild();
137     virtual bool Unpin();
138     virtual bool IsPurged();
139     virtual void AfterRebuildSucc();
140     virtual std::string ToString() const;
141 };
142 } /* namespace PurgeableMem */
143 } /* namespace OHOS */
144 #endif /* OHOS_UTILS_MEMORY_LIBPURGEABLEMEM_CPP_INCLUDE_PURGEABLE_MEM_BASE_H */
145