Android LRUCache

 17 package android.util;
 18 
 19 import java.util.LinkedHashMap;
 20 import java.util.Map;
 21 
 22 /**
 23  * A cache that holds strong references to a limited number of values. Each time
 24  * a value is accessed, it is moved to the head of a queue. When a value is
 25  * added to a full cache, the value at the end of that queue is evicted and may
 26  * become eligible for garbage collection. 
一个cache缓冲区，维护有限个值的强引用。当一个值被命中时，它被移到队列的头部？？？确定有移动么
当一个值被加入一个已满的cache中时，队列最后一个值被舍弃。可能会被垃圾回收
 28  * <p>If your cached values hold resources that need to be explicitly released,
 29  * override {@link #entryRemoved}.
如果你缓存的值中有必须被释放的资源，需要override  entryRemoved方法
 31  * <p>If a cache miss should be computed on demand for the corresponding keys,
 32  * override {@link #create}. This simplifies the calling code, allowing it to
 33  * assume a value will always be returned, even when there‘s a cache miss.
如果一次cache未命中时，同样需要返回。 需要override create()方法。
这使调用简化：不管是不是命中，都返回一个值。

因为当前的create方法返回的是个null。当你没get到的时候，会调用create方法。在当前情况下，返回null会直接return null。
不会往后执行之后的创建键值对，并返回的操作。

但是如果你重写了create()，使其返回的不是null，则后边的操作会执行。调用get(key)，value值被返回。
 35  * <p>By default, the cache size is measured in the number of entries. Override
 36  * {@link #sizeOf} to size the cache in different units. For example, this cache
 37  * is limited to 4MiB of bitmaps:
默认情况下，一个cache的大小,是以实体的个数来衡量的。因为当前的sizeOf() 方法返回的是1，也就是每个entry大小是1
你可以override  sizeof方法，改变cache 的最小单元大小。
例如，下边这个cache 限制为最大4MiB的bitmap cache
每个单元的大小就不是1了，而是bitmap的大小。

 38  * <pre>   {@code
 39  *   int cacheSize = 4 * 1024 * 1024; // 4MiB
 40  *   LruCache<String, Bitmap> bitmapCache = new LruCache<String, Bitmap>(cacheSize) {
 41  *       protected int sizeOf(String key, Bitmap value) {
 42  *           return value.getByteCount();
 43  *       }
 44  *   }}</pre>

LRUCache类是线程安全的。多个cache操作时候。要synchronize这个cache

 46  * <p>This class is thread-safe. Perform multiple cache operations atomically by
 47  * synchronizing on the cache: <pre>   {@code
 48  *   synchronized (cache) {
 49  *     if (cache.get(key) == null) {
 50  *         cache.put(key, value);
 51  *     }
 52  *   }}</pre>

这个类不允许传入的key和value是空。
get put remove返回null，代表这个key不再cache中

 54  * <p>This class does not allow null to be used as a key or value. A return
 55  * value of null from {@link #get}, {@link #put} or {@link #remove} is
 56  * unambiguous: the key was not in the cache.
 57  *
 58  * <p>This class appeared in Android 3.1 (Honeycomb MR1); it‘s available as part
 59  * of <a href="http://developer.android.com/sdk/compatibility-library.html">Android‘s
 60  * Support Package</a> for earlier releases.
 61  */
 62 public class LruCache<K, V> {
 63     private final LinkedHashMap<K, V> map;
 64 
 65     /** Size of this cache in units. Not necessarily the number of elements. */
 66     private int size;
 67     private int maxSize;
 68 
 69     private int putCount;
 70     private int createCount;
 71     private int evictionCount;
 72     private int hitCount;
 73     private int missCount;
 74 
 75     /**
 76      * @param maxSize for caches that do not override {@link #sizeOf}, this is
 77      *     the maximum number of entries in the cache. For all other caches,
 78      *     this is the maximum sum of the sizes of the entries in this cache.
 79      */
 80     public LruCache(int maxSize) {
 81         if (maxSize <= 0) {
 82             throw new IllegalArgumentException("maxSize <= 0");
 83         }
 84         this.maxSize = maxSize;
 85         this.map = new LinkedHashMap<K, V>(0, 0.75f, true);
 86     }
 87 
 88     /**
 89      * Sets the size of the cache.
 90      * @param maxSize The new maximum size.
 91      *
 92      * @hide
 93      */
 94     public void resize(int maxSize) {
 95         if (maxSize <= 0) {
 96             throw new IllegalArgumentException("maxSize <= 0");
 97         }
 98 
 99         synchronized (this) {
100             this.maxSize = maxSize;
101         }
102         trimToSize(maxSize);
103     }
104 
105     /**
106      * Returns the value for {@code key} if it exists in the cache or can be
107      * created by {@code #create}. If a value was returned, it is moved to the
108      * head of the queue. This returns null if a value is not cached and cannot
109      * be created.
110      */
111     public final V get(K key) {
112         if (key == null) {
113             throw new NullPointerException("key == null");
114         }
115 
116         V mapValue;
117         synchronized (this) {
118             mapValue = map.get(key);
119             if (mapValue != null) {
120                 hitCount++;
121                 return mapValue;
122             }
123             missCount++;
124         }
125 
126         /*
127          * Attempt to create a value. This may take a long time, and the map
128          * may be different when create() returns. If a conflicting value was
129          * added to the map while create() was working, we leave that value in
130          * the map and release the created value.
131          */
132 
133         V createdValue = create(key);
134         if (createdValue == null) {
135             return null;
136         }
137 
138         synchronized (this) {
139             createCount++;
140             mapValue = map.put(key, createdValue);
141 
142             if (mapValue != null) {
143                 // There was a conflict so undo that last put
144                 map.put(key, mapValue);
145             } else {
146                 size += safeSizeOf(key, createdValue);
147             }
148         }
149 
150         if (mapValue != null) {
151             entryRemoved(false, key, createdValue, mapValue);
152             return mapValue;
153         } else {
154             trimToSize(maxSize);
155             return createdValue;
156         }
157     }
158 
159     /**
160      * Caches {@code value} for {@code key}. The value is moved to the head of
161      * the queue.
162      *
163      * @return the previous value mapped by {@code key}.
164      */
165     public final V put(K key, V value) {
166         if (key == null || value == null) {
167             throw new NullPointerException("key == null || value == null");
168         }
169 
170         V previous;
171         synchronized (this) {
172             putCount++;
173             size += safeSizeOf(key, value);
174             previous = map.put(key, value);
175             if (previous != null) {
176                 size -= safeSizeOf(key, previous);
177             }
178         }
179 
180         if (previous != null) {
181             entryRemoved(false, key, previous, value);
182         }
183 
184         trimToSize(maxSize);
185         return previous;
186     }
187 
188     /**
189      * Remove the eldest entries until the total of remaining entries is at or
190      * below the requested size.
191      *
192      * @param maxSize the maximum size of the cache before returning. May be -1
193      *            to evict even 0-sized elements.
194      */
195     public void trimToSize(int maxSize) {
196         while (true) {
197             K key;
198             V value;
199             synchronized (this) {
200                 if (size < 0 || (map.isEmpty() && size != 0)) {
201                     throw new IllegalStateException(getClass().getName()
202                             + ".sizeOf() is reporting inconsistent results!");
203                 }
204 
205                 if (size <= maxSize) {
206                     break;
207                 }
208 
209                 Map.Entry<K, V> toEvict = map.eldest();
210                 if (toEvict == null) {
211                     break;
212                 }
213 
214                 key = toEvict.getKey();
215                 value = toEvict.getValue();
216                 map.remove(key);
217                 size -= safeSizeOf(key, value);
218                 evictionCount++;
219             }
220 
221             entryRemoved(true, key, value, null);
222         }
223     }
224 
225     /**
226      * Removes the entry for {@code key} if it exists.
227      *
228      * @return the previous value mapped by {@code key}.
229      */
230     public final V remove(K key) {
231         if (key == null) {
232             throw new NullPointerException("key == null");
233         }
234 
235         V previous;
236         synchronized (this) {
237             previous = map.remove(key);
238             if (previous != null) {
239                 size -= safeSizeOf(key, previous);
240             }
241         }
242 
243         if (previous != null) {
244             entryRemoved(false, key, previous, null);
245         }
246 
247         return previous;
248     }
249 
250     /**
251      * Called for entries that have been evicted or removed. This method is
252      * invoked when a value is evicted to make space, removed by a call to
253      * {@link #remove}, or replaced by a call to {@link #put}. The default
254      * implementation does nothing.
255      *
256      * <p>The method is called without synchronization: other threads may
257      * access the cache while this method is executing.
258      *
259      * @param evicted true if the entry is being removed to make space, false
260      *     if the removal was caused by a {@link #put} or {@link #remove}.
261      * @param newValue the new value for {@code key}, if it exists. If non-null,
262      *     this removal was caused by a {@link #put}. Otherwise it was caused by
263      *     an eviction or a {@link #remove}.
264      */
265     protected void entryRemoved(boolean evicted, K key, V oldValue, V newValue) {}
266 
267     /**
268      * Called after a cache miss to compute a value for the corresponding key.
269      * Returns the computed value or null if no value can be computed. The
270      * default implementation returns null.
271      *
272      * <p>The method is called without synchronization: other threads may
273      * access the cache while this method is executing.
274      *
275      * <p>If a value for {@code key} exists in the cache when this method
276      * returns, the created value will be released with {@link #entryRemoved}
277      * and discarded. This can occur when multiple threads request the same key
278      * at the same time (causing multiple values to be created), or when one
279      * thread calls {@link #put} while another is creating a value for the same
280      * key.
281      */
282     protected V create(K key) {
283         return null;
284     }
285 
286     private int safeSizeOf(K key, V value) {
287         int result = sizeOf(key, value);
288         if (result < 0) {
289             throw new IllegalStateException("Negative size: " + key + "=" + value);
290         }
291         return result;
292     }
293 
294     /**
295      * Returns the size of the entry for {@code key} and {@code value} in
296      * user-defined units.  The default implementation returns 1 so that size
297      * is the number of entries and max size is the maximum number of entries.
298      *
299      * <p>An entry‘s size must not change while it is in the cache.
300      */
301     protected int sizeOf(K key, V value) {
302         return 1;
303     }
304 
305     /**
306      * Clear the cache, calling {@link #entryRemoved} on each removed entry.
307      */
308     public final void evictAll() {
309         trimToSize(-1); // -1 will evict 0-sized elements
310     }
311 
312     /**
313      * For caches that do not override {@link #sizeOf}, this returns the number
314      * of entries in the cache. For all other caches, this returns the sum of
315      * the sizes of the entries in this cache.
316      */
317     public synchronized final int size() {
318         return size;
319     }
320 
321     /**
322      * For caches that do not override {@link #sizeOf}, this returns the maximum
323      * number of entries in the cache. For all other caches, this returns the
324      * maximum sum of the sizes of the entries in this cache.
325      */
326     public synchronized final int maxSize() {
327         return maxSize;
328     }
329 
330     /**
331      * Returns the number of times {@link #get} returned a value that was
332      * already present in the cache.
333      */
334     public synchronized final int hitCount() {
335         return hitCount;
336     }
337 
338     /**
339      * Returns the number of times {@link #get} returned null or required a new
340      * value to be created.
341      */
342     public synchronized final int missCount() {
343         return missCount;
344     }
345 
346     /**
347      * Returns the number of times {@link #create(Object)} returned a value.
348      */
349     public synchronized final int createCount() {
350         return createCount;
351     }
352 
353     /**
354      * Returns the number of times {@link #put} was called.
355      */
356     public synchronized final int putCount() {
357         return putCount;
358     }
359 
360     /**
361      * Returns the number of values that have been evicted.
362      */
363     public synchronized final int evictionCount() {
364         return evictionCount;
365     }
366 
367     /**
368      * Returns a copy of the current contents of the cache, ordered from least
369      * recently accessed to most recently accessed.
370      */
371     public synchronized final Map<K, V> snapshot() {
372         return new LinkedHashMap<K, V>(map);
373     }
374 
375     @Override public synchronized final String toString() {
376         int accesses = hitCount + missCount;
377         int hitPercent = accesses != 0 ? (100 * hitCount / accesses) : 0;
378         return String.format("LruCache[maxSize=%d,hits=%d,misses=%d,hitRate=%d%%]",
379                 maxSize, hitCount, missCount, hitPercent);
380     }
381 }