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_NN_CACHE_H 18 #define ANDROID_NN_CACHE_H 19 20 #include "BlobCache.h" 21 22 #include <functional> 23 #include <memory> 24 #include <mutex> 25 #include <string> 26 27 // ---------------------------------------------------------------------------- 28 namespace android { 29 // ---------------------------------------------------------------------------- 30 31 class NNCache { 32 public: 33 34 typedef BlobCache::Select Select; 35 typedef BlobCache::Capacity Capacity; 36 typedef BlobCache::Policy Policy; 37 defaultPolicy()38 static Policy defaultPolicy() { return BlobCache::defaultPolicy(); } 39 40 // get returns a pointer to the singleton NNCache object. This 41 // singleton object will never be destroyed. 42 static NNCache* get(); 43 44 // initialize puts the NNCache into an initialized state, such 45 // that it is able to insert and retrieve entries from the cache. 46 // When not in the initialized state the getBlob and setBlob 47 // methods will return without performing any cache operations. 48 // 49 // The NNCache will cache key/value pairs with key and value sizes 50 // less than or equal to maxKeySize and maxValueSize, 51 // respectively. The total combined size of ALL cache entries (key 52 // sizes plus value sizes) will not exceed maxTotalSize. 53 void initialize(size_t maxKeySize, size_t maxValueSize, size_t maxTotalSize, 54 Policy policy = defaultPolicy()); 55 56 // terminate puts the NNCache back into the uninitialized state. When 57 // in this state the getBlob and setBlob methods will return without 58 // performing any cache operations. 59 void terminate(); 60 61 // setBlob attempts to insert a new key/value blob pair into the cache. 62 void setBlob(const void* key, ssize_t keySize, const void* value, 63 ssize_t valueSize); 64 65 // getBlob attempts to retrieve the value blob associated with a given key 66 // blob from cache. 67 ssize_t getBlob(const void* key, ssize_t keySize, 68 void* value, ssize_t valueSize); 69 ssize_t getBlob(const void* key, ssize_t keySize, 70 void** value, std::function<void*(size_t)> alloc); 71 template <typename T> getBlob(const void * key,size_t keySize,T ** value,std::function<void * (size_t)> alloc)72 ssize_t getBlob(const void* key, size_t keySize, 73 T** value, std::function<void*(size_t)> alloc) { 74 void *valueVoid; 75 const ssize_t size = getBlob(key, keySize, &valueVoid, alloc); 76 *value = static_cast<T*>(valueVoid); 77 return size; 78 } 79 80 // setCacheFilename sets the name of the file that should be used to store 81 // cache contents from one program invocation to another. 82 void setCacheFilename(const char* filename); 83 84 private: 85 // Creation and (the lack of) destruction is handled internally. 86 NNCache(); 87 ~NNCache(); 88 89 // Copying is disallowed. 90 NNCache(const NNCache&) = delete; 91 void operator=(const NNCache&) = delete; 92 93 // getBlobCacheLocked returns the BlobCache object being used to store the 94 // key/value blob pairs. If the BlobCache object has not yet been created, 95 // this will do so, loading the serialized cache contents from disk if 96 // possible. 97 BlobCache* getBlobCacheLocked(); 98 99 // saveBlobCache attempts to save the current contents of mBlobCache to 100 // disk. 101 void saveBlobCacheLocked(); 102 103 // loadBlobCache attempts to load the saved cache contents from disk into 104 // mBlobCache. 105 void loadBlobCacheLocked(); 106 107 // mInitialized indicates whether the NNCache is in the initialized 108 // state. It is initialized to false at construction time, and gets set to 109 // true when initialize is called. It is set back to false when terminate 110 // is called. When in this state, the cache behaves as normal. When not, 111 // the getBlob and setBlob methods will return without performing any cache 112 // operations. 113 bool mInitialized; 114 115 // mMaxKeySize is the maximum key size that will be cached. 116 size_t mMaxKeySize; 117 118 // mMaxValueSize is the maximum value size that will be cached. 119 size_t mMaxValueSize; 120 121 // mMaxTotalSize is the maximum size that all cache entries can occupy. This 122 // includes space for both keys and values. 123 size_t mMaxTotalSize; 124 125 // mPolicy is the policy for cleaning the cache. 126 Policy mPolicy; 127 128 // mBlobCache is the cache in which the key/value blob pairs are stored. It 129 // is initially NULL, and will be initialized by getBlobCacheLocked the 130 // first time it's needed. 131 std::unique_ptr<BlobCache> mBlobCache; 132 133 // mFilename is the name of the file for storing cache contents in between 134 // program invocations. It is initialized to an empty string at 135 // construction time, and can be set with the setCacheFilename method. An 136 // empty string indicates that the cache should not be saved to or restored 137 // from disk. 138 std::string mFilename; 139 140 // mSavePending indicates whether or not a deferred save operation is 141 // pending. Each time a key/value pair is inserted into the cache via 142 // setBlob, a deferred save is initiated if one is not already pending. 143 // This will wait some amount of time and then trigger a save of the cache 144 // contents to disk. 145 bool mSavePending; 146 147 // mMutex is the mutex used to prevent concurrent access to the member 148 // variables. It must be locked whenever the member variables are accessed. 149 mutable std::mutex mMutex; 150 151 // sCache is the singleton NNCache object. 152 static NNCache sCache; 153 }; 154 155 // ---------------------------------------------------------------------------- 156 }; // namespace android 157 // ---------------------------------------------------------------------------- 158 159 #endif // ANDROID_NN_CACHE_H 160