1 /*
2  ** Copyright 2011, The Android Open Source Project
3  **
4  ** Licensed under the Apache License, Version 2.0 (the "License");
5  ** you may not use this file except in compliance with the License.
6  ** You may obtain a copy of the License at
7  **
8  **     http://www.apache.org/licenses/LICENSE-2.0
9  **
10  ** Unless required by applicable law or agreed to in writing, software
11  ** distributed under the License is distributed on an "AS IS" BASIS,
12  ** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  ** See the License for the specific language governing permissions and
14  ** limitations under the License.
15  */
16 
17 #ifndef ANDROID_EGL_CACHE_H
18 #define ANDROID_EGL_CACHE_H
19 
20 #include <EGL/egl.h>
21 #include <EGL/eglext.h>
22 
23 #include <memory>
24 #include <mutex>
25 #include <string>
26 
27 #include "FileBlobCache.h"
28 #include "MultifileBlobCache.h"
29 
30 namespace android {
31 
32 class egl_display_t;
33 
34 class EGLAPI egl_cache_t {
35 public:
36     enum class EGLCacheMode {
37         Monolithic,
38         Multifile,
39     };
40 
41     // get returns a pointer to the singleton egl_cache_t object.  This
42     // singleton object will never be destroyed.
43     static egl_cache_t* get();
44 
45     // initialize puts the egl_cache_t into an initialized state, such that it
46     // is able to insert and retrieve entries from the cache.  This should be
47     // called when EGL is initialized.  When not in the initialized state the
48     // getBlob and setBlob methods will return without performing any cache
49     // operations.
50     void initialize(egl_display_t* display);
51 
52     // terminate puts the egl_cache_t back into the uninitialized state.  When
53     // in this state the getBlob and setBlob methods will return without
54     // performing any cache operations.
55     void terminate();
56 
57     // setBlob attempts to insert a new key/value blob pair into the cache.
58     // This will be called by the hardware vendor's EGL implementation via the
59     // EGL_ANDROID_blob_cache extension.
60     void setBlob(const void* key, EGLsizeiANDROID keySize, const void* value,
61         EGLsizeiANDROID valueSize);
62 
63     // getBlob attempts to retrieve the value blob associated with a given key
64     // blob from cache.  This will be called by the hardware vendor's EGL
65     // implementation via the EGL_ANDROID_blob_cache extension.
66     EGLsizeiANDROID getBlob(const void* key, EGLsizeiANDROID keySize,
67         void* value, EGLsizeiANDROID valueSize);
68 
69     // setCacheFilename sets the name of the file that should be used to store
70     // cache contents from one program invocation to another.
71     void setCacheFilename(const char* filename);
72 
73     // Allow setting monolithic or multifile modes
74     void setCacheMode(EGLCacheMode cacheMode);
75 
76     // Allow the fixed cache limit to be overridden
77     void setCacheLimit(int64_t cacheByteLimit);
78 
79     // Return the byte total for cache file(s)
80     size_t getCacheSize();
81 
82 private:
83     // Creation and (the lack of) destruction is handled internally.
84     egl_cache_t();
85     ~egl_cache_t();
86 
87     // Copying is disallowed.
88     egl_cache_t(const egl_cache_t&); // not implemented
89     void operator=(const egl_cache_t&); // not implemented
90 
91     // Check system properties to determine which blobcache mode should be used
92     void updateMode();
93 
94     // getBlobCacheLocked returns the BlobCache object being used to store the
95     // key/value blob pairs.  If the BlobCache object has not yet been created,
96     // this will do so, loading the serialized cache contents from disk if
97     // possible.
98     BlobCache* getBlobCacheLocked();
99 
100     // Get or create the multifile blobcache
101     MultifileBlobCache* getMultifileBlobCacheLocked();
102 
103     // mInitialized indicates whether the egl_cache_t is in the initialized
104     // state.  It is initialized to false at construction time, and gets set to
105     // true when initialize is called.  It is set back to false when terminate
106     // is called.  When in this state, the cache behaves as normal.  When not,
107     // the getBlob and setBlob methods will return without performing any cache
108     // operations.
109     bool mInitialized;
110 
111     // mBlobCache is the cache in which the key/value blob pairs are stored.  It
112     // is initially NULL, and will be initialized by getBlobCacheLocked the
113     // first time it's needed.
114     std::unique_ptr<FileBlobCache> mBlobCache;
115 
116     // The multifile version of blobcache allowing larger contents to be stored
117     std::unique_ptr<MultifileBlobCache> mMultifileBlobCache;
118 
119     // mFilename is the name of the file for storing cache contents in between
120     // program invocations.  It is initialized to an empty string at
121     // construction time, and can be set with the setCacheFilename method.  An
122     // empty string indicates that the cache should not be saved to or restored
123     // from disk.
124     std::string mFilename;
125 
126     // mSavePending indicates whether or not a deferred save operation is
127     // pending.  Each time a key/value pair is inserted into the cache via
128     // setBlob, a deferred save is initiated if one is not already pending.
129     // This will wait some amount of time and then trigger a save of the cache
130     // contents to disk.
131     bool mSavePending;
132 
133     // mMutex is the mutex used to prevent concurrent access to the member
134     // variables. It must be locked whenever the member variables are accessed.
135     mutable std::mutex mMutex;
136 
137     // sCache is the singleton egl_cache_t object.
138     static egl_cache_t sCache;
139 
140     // Whether to use multiple files to store cache entries
141     bool mMultifileMode;
142 
143     // Cache limit
144     size_t mCacheByteLimit;
145 };
146 
147 }; // namespace android
148 
149 #endif // ANDROID_EGL_CACHE_H
150