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
30namespace OHOS {
31namespace PurgeableMem {
32class PurgeableMemBase {
33public:
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
128protected:
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