Line data Source code
1 : /*
2 : * Copyright 2013 Google Inc.
3 : *
4 : * Use of this source code is governed by a BSD-style license that can be
5 : * found in the LICENSE file.
6 : */
7 :
8 : #ifndef SkResourceCache_DEFINED
9 : #define SkResourceCache_DEFINED
10 :
11 : #include "SkBitmap.h"
12 : #include "SkMessageBus.h"
13 : #include "SkTDArray.h"
14 :
15 : class SkCachedData;
16 : class SkDiscardableMemory;
17 : class SkTraceMemoryDump;
18 :
19 : /**
20 : * Cache object for bitmaps (with possible scale in X Y as part of the key).
21 : *
22 : * Multiple caches can be instantiated, but each instance is not implicitly
23 : * thread-safe, so if a given instance is to be shared across threads, the
24 : * caller must manage the access itself (e.g. via a mutex).
25 : *
26 : * As a convenience, a global instance is also defined, which can be safely
27 : * access across threads via the static methods (e.g. FindAndLock, etc.).
28 : */
29 : class SkResourceCache {
30 : public:
31 0 : struct Key {
32 : /** Key subclasses must call this after their own fields and data are initialized.
33 : * All fields and data must be tightly packed.
34 : * @param nameSpace must be unique per Key subclass.
35 : * @param sharedID == 0 means ignore this field, does not support group purging.
36 : * @param dataSize is size of fields and data of the subclass, must be a multiple of 4.
37 : */
38 : void init(void* nameSpace, uint64_t sharedID, size_t dataSize);
39 :
40 : /** Returns the size of this key. */
41 : size_t size() const {
42 : return fCount32 << 2;
43 : }
44 :
45 : void* getNamespace() const { return fNamespace; }
46 0 : uint64_t getSharedID() const { return ((uint64_t)fSharedID_hi << 32) | fSharedID_lo; }
47 :
48 : // This is only valid after having called init().
49 0 : uint32_t hash() const { return fHash; }
50 :
51 0 : bool operator==(const Key& other) const {
52 0 : const uint32_t* a = this->as32();
53 0 : const uint32_t* b = other.as32();
54 0 : for (int i = 0; i < fCount32; ++i) { // (This checks fCount == other.fCount first.)
55 0 : if (a[i] != b[i]) {
56 0 : return false;
57 : }
58 : }
59 0 : return true;
60 : }
61 :
62 : private:
63 : int32_t fCount32; // local + user contents count32
64 : uint32_t fHash;
65 : // split uint64_t into hi and lo so we don't force ourselves to pad on 32bit machines.
66 : uint32_t fSharedID_lo;
67 : uint32_t fSharedID_hi;
68 : void* fNamespace; // A unique namespace tag. This is hashed.
69 : /* uint32_t fContents32[] */
70 :
71 0 : const uint32_t* as32() const { return (const uint32_t*)this; }
72 : };
73 :
74 : struct Rec {
75 : typedef SkResourceCache::Key Key;
76 :
77 0 : Rec() {}
78 0 : virtual ~Rec() {}
79 :
80 0 : uint32_t getHash() const { return this->getKey().hash(); }
81 :
82 : virtual const Key& getKey() const = 0;
83 : virtual size_t bytesUsed() const = 0;
84 :
85 : // Called if the cache needs to purge/remove/delete the Rec. Default returns true.
86 : // Subclass may return false if there are outstanding references to it (e.g. bitmaps).
87 : // Will only be deleted/removed-from-the-cache when this returns true.
88 0 : virtual bool canBePurged() { return true; }
89 :
90 : // A rec is first created/initialized, and then added to the cache. As part of the add(),
91 : // the cache will callback into the rec with postAddInstall, passing in whatever payload
92 : // was passed to add/Add.
93 : //
94 : // This late-install callback exists because the process of add-ing might end up deleting
95 : // the new rec (if an existing rec in the cache has the same key and cannot be purged).
96 : // If the new rec will be deleted during add, the pre-existing one (with the same key)
97 : // will have postAddInstall() called on it instead, so that either way an "install" will
98 : // happen during the add.
99 0 : virtual void postAddInstall(void*) {}
100 :
101 : // for memory usage diagnostics
102 : virtual const char* getCategory() const = 0;
103 0 : virtual SkDiscardableMemory* diagnostic_only_getDiscardable() const { return nullptr; }
104 :
105 : private:
106 : Rec* fNext;
107 : Rec* fPrev;
108 :
109 : friend class SkResourceCache;
110 : };
111 :
112 : // Used with SkMessageBus
113 : struct PurgeSharedIDMessage {
114 0 : PurgeSharedIDMessage(uint64_t sharedID) : fSharedID(sharedID) {}
115 :
116 : uint64_t fSharedID;
117 : };
118 :
119 : typedef const Rec* ID;
120 :
121 : /**
122 : * Callback function for find(). If called, the cache will have found a match for the
123 : * specified Key, and will pass in the corresponding Rec, along with a caller-specified
124 : * context. The function can read the data in Rec, and copy whatever it likes into context
125 : * (casting context to whatever it really is).
126 : *
127 : * The return value determines what the cache will do with the Rec. If the function returns
128 : * true, then the Rec is considered "valid". If false is returned, the Rec will be considered
129 : * "stale" and will be purged from the cache.
130 : */
131 : typedef bool (*FindVisitor)(const Rec&, void* context);
132 :
133 : /**
134 : * Returns a locked/pinned SkDiscardableMemory instance for the specified
135 : * number of bytes, or nullptr on failure.
136 : */
137 : typedef SkDiscardableMemory* (*DiscardableFactory)(size_t bytes);
138 :
139 : /*
140 : * The following static methods are thread-safe wrappers around a global
141 : * instance of this cache.
142 : */
143 :
144 : /**
145 : * Returns true if the visitor was called on a matching Key, and the visitor returned true.
146 : *
147 : * Find() will search the cache for the specified Key. If no match is found, return false and
148 : * do not call the FindVisitor. If a match is found, return whatever the visitor returns.
149 : * Its return value is interpreted to mean:
150 : * true : Rec is valid
151 : * false : Rec is "stale" -- the cache will purge it.
152 : */
153 : static bool Find(const Key& key, FindVisitor, void* context);
154 : static void Add(Rec*, void* payload = nullptr);
155 :
156 : typedef void (*Visitor)(const Rec&, void* context);
157 : // Call the visitor for every Rec in the cache.
158 : static void VisitAll(Visitor, void* context);
159 :
160 : static size_t GetTotalBytesUsed();
161 : static size_t GetTotalByteLimit();
162 : static size_t SetTotalByteLimit(size_t newLimit);
163 :
164 : static size_t SetSingleAllocationByteLimit(size_t);
165 : static size_t GetSingleAllocationByteLimit();
166 : static size_t GetEffectiveSingleAllocationByteLimit();
167 :
168 : static void PurgeAll();
169 :
170 : static void TestDumpMemoryStatistics();
171 :
172 : /** Dump memory usage statistics of every Rec in the cache using the
173 : SkTraceMemoryDump interface.
174 : */
175 : static void DumpMemoryStatistics(SkTraceMemoryDump* dump);
176 :
177 : /**
178 : * Returns the DiscardableFactory used by the global cache, or nullptr.
179 : */
180 : static DiscardableFactory GetDiscardableFactory();
181 :
182 : static SkCachedData* NewCachedData(size_t bytes);
183 :
184 : static void PostPurgeSharedID(uint64_t sharedID);
185 :
186 : /**
187 : * Call SkDebugf() with diagnostic information about the state of the cache
188 : */
189 : static void Dump();
190 :
191 : ///////////////////////////////////////////////////////////////////////////
192 :
193 : /**
194 : * Construct the cache to call DiscardableFactory when it
195 : * allocates memory for the pixels. In this mode, the cache has
196 : * not explicit budget, and so methods like getTotalBytesUsed()
197 : * and getTotalByteLimit() will return 0, and setTotalByteLimit
198 : * will ignore its argument and return 0.
199 : */
200 : SkResourceCache(DiscardableFactory);
201 :
202 : /**
203 : * Construct the cache, allocating memory with malloc, and respect the
204 : * byteLimit, purging automatically when a new image is added to the cache
205 : * that pushes the total bytesUsed over the limit. Note: The limit can be
206 : * changed at runtime with setTotalByteLimit.
207 : */
208 : explicit SkResourceCache(size_t byteLimit);
209 : ~SkResourceCache();
210 :
211 : /**
212 : * Returns true if the visitor was called on a matching Key, and the visitor returned true.
213 : *
214 : * find() will search the cache for the specified Key. If no match is found, return false and
215 : * do not call the FindVisitor. If a match is found, return whatever the visitor returns.
216 : * Its return value is interpreted to mean:
217 : * true : Rec is valid
218 : * false : Rec is "stale" -- the cache will purge it.
219 : */
220 : bool find(const Key&, FindVisitor, void* context);
221 : void add(Rec*, void* payload = nullptr);
222 : void visitAll(Visitor, void* context);
223 :
224 0 : size_t getTotalBytesUsed() const { return fTotalBytesUsed; }
225 0 : size_t getTotalByteLimit() const { return fTotalByteLimit; }
226 :
227 : /**
228 : * This is respected by SkBitmapProcState::possiblyScaleImage.
229 : * 0 is no maximum at all; this is the default.
230 : * setSingleAllocationByteLimit() returns the previous value.
231 : */
232 : size_t setSingleAllocationByteLimit(size_t maximumAllocationSize);
233 : size_t getSingleAllocationByteLimit() const;
234 : // returns the logical single allocation size (pinning against the budget when the cache
235 : // is not backed by discardable memory.
236 : size_t getEffectiveSingleAllocationByteLimit() const;
237 :
238 : /**
239 : * Set the maximum number of bytes available to this cache. If the current
240 : * cache exceeds this new value, it will be purged to try to fit within
241 : * this new limit.
242 : */
243 : size_t setTotalByteLimit(size_t newLimit);
244 :
245 : void purgeSharedID(uint64_t sharedID);
246 :
247 0 : void purgeAll() {
248 0 : this->purgeAsNeeded(true);
249 0 : }
250 :
251 0 : DiscardableFactory discardableFactory() const { return fDiscardableFactory; }
252 :
253 : SkCachedData* newCachedData(size_t bytes);
254 :
255 : /**
256 : * Call SkDebugf() with diagnostic information about the state of the cache
257 : */
258 : void dump() const;
259 :
260 : private:
261 : Rec* fHead;
262 : Rec* fTail;
263 :
264 : class Hash;
265 : Hash* fHash;
266 :
267 : DiscardableFactory fDiscardableFactory;
268 :
269 : size_t fTotalBytesUsed;
270 : size_t fTotalByteLimit;
271 : size_t fSingleAllocationByteLimit;
272 : int fCount;
273 :
274 : SkMessageBus<PurgeSharedIDMessage>::Inbox fPurgeSharedIDInbox;
275 :
276 : void checkMessages();
277 : void purgeAsNeeded(bool forcePurge = false);
278 :
279 : // linklist management
280 : void moveToHead(Rec*);
281 : void addToHead(Rec*);
282 : void release(Rec*);
283 : void remove(Rec*);
284 :
285 : void init(); // called by constructors
286 :
287 : #ifdef SK_DEBUG
288 : void validate() const;
289 : #else
290 : void validate() const {}
291 : #endif
292 : };
293 : #endif
|