Android提供的LruCache類簡介

yangxi_001發表於2013-11-26
原文網址 : https://blog.csdn.net/yangxi_pekin/article/details/16962837
Android
  1. package android.util;  
  2.   
  3. import java.util.LinkedHashMap;  
  4. import java.util.Map;  
  5.   
  6. /** 
  7.  * A cache that holds strong references to a limited number of values. Each time 
  8.  * a value is accessed, it is moved to the head of a queue. When a value is 
  9.  * added to a full cache, the value at the end of that queue is evicted and may 
  10.  * become eligible for garbage collection. 
  11.  * Cache儲存一個強引用來限制內容數量，每當Item被訪問的時候，此Item就會移動到佇列的頭部。
  12.  * 當cache已滿的時候加入新的item時，在佇列尾部的item會被回收。
  13.  * <p>If your cached values hold resources that need to be explicitly released, 
  14.  * override {@link #entryRemoved}. 
  15.  * 如果你cache的某個值需要明確釋放，重寫entryRemoved()
  16.  * <p>If a cache miss should be computed on demand for the corresponding keys, 
  17.  * override {@link #create}. This simplifies the calling code, allowing it to 
  18.  * assume a value will always be returned, even when there's a cache miss. 
  19.  * 如果key相對應的item丟掉啦，重寫create().這簡化了呼叫程式碼，即使丟失了也總會返回。
  20.  * <p>By default, the cache size is measured in the number of entries. Override 
  21.  * {@link #sizeOf} to size the cache in different units. For example, this cache 
  22.  * is limited to 4MiB of bitmaps: 預設cache大小是測量的item的數量，重寫sizeof計算不同item的
  23.  *  大小。
  24.  * <pre>   {@code 
  25.  *   int cacheSize = 4 * 1024 * 1024; // 4MiB 
  26.  *   LruCache<String, Bitmap> bitmapCache = new LruCache<String, Bitmap>(cacheSize) { 
  27.  *       protected int sizeOf(String key, Bitmap value) { 
  28.  *           return value.getByteCount(); 
  29.  *       } 
  30.  *   }}</pre> 
  31.  * 
  32.  * <p>This class is thread-safe. Perform multiple cache operations atomically by 
  33.  * synchronizing on the cache: <pre>   {@code 
  34.  *   synchronized (cache) { 
  35.  *     if (cache.get(key) == null) { 
  36.  *         cache.put(key, value); 
  37.  *     } 
  38.  *   }}</pre> 
  39.  * 
  40.  * <p>This class does not allow null to be used as a key or value. A return 
  41.  * value of null from {@link #get}, {@link #put} or {@link #remove} is 
  42.  * unambiguous: the key was not in the cache.
  43.  * 不允許key或者value為null
  44.  *  當get（），put（），remove（）返回值為null時，key相應的項不在cache中
  45.  */  
  46. public class LruCache<K, V> {  
  47.     private final LinkedHashMap<K, V> map;  
  48.   
  49.     /** Size of this cache in units. Not necessarily the number of elements. */  
  50.     private int size; //已經儲存的大小
  51.     private int maxSize; //規定的最大儲存空間
  52.   
  53.     private int putCount;  //put的次數
  54.     private int createCount;  //create的次數
  55.     private int evictionCount;  //回收的次數
  56.     private int hitCount;  //命中的次數
  57.     private int missCount;  //丟失的次數
  58.   
  59.     /** 
  60.      * @param maxSize for caches that do not override {@link #sizeOf}, this is 
  61.      *     the maximum number of entries in the cache. For all other caches, 
  62.      *     this is the maximum sum of the sizes of the entries in this cache. 
  63.      */  
  64.     public LruCache(int maxSize) {  
  65.         if (maxSize <= 0) {  
  66.             throw new IllegalArgumentException("maxSize <= 0");  
  67.         }  
  68.         this.maxSize = maxSize;  
  69.         this.map = new LinkedHashMap<K, V>(0, 0.75f, true);  
  70.     }  
  71.   
  72.     /** 
  73.      * Returns the value for {@code key} if it exists in the cache or can be 
  74.      * created by {@code #create}. If a value was returned, it is moved to the 
  75.      * head of the queue. This returns null if a value is not cached and cannot 
  76.      * be created. 通過key返回相應的item，或者建立返回相應的item。相應的item會移動到佇列的頭部，
  77.      * 如果item的value沒有被cache或者不能被建立，則返回null。
  78.      */  
  79.     public final V get(K key) {  
  80.         if (key == null) {  
  81.             throw new NullPointerException("key == null");  
  82.         }  
  83.   
  84.         V mapValue;  
  85.         synchronized (this) {  
  86.             mapValue = map.get(key);  
  87.             if (mapValue != null) {  
  88.                 hitCount++;  //命中
  89.                 return mapValue;  
  90.             }  
  91.             missCount++;  //丟失
  92.         }  
  93.   
  94.         /* 
  95.          * Attempt to create a value. This may take a long time, and the map 
  96.          * may be different when create() returns. If a conflicting value was 
  97.          * added to the map while create() was working, we leave that value in 
  98.          * the map and release the created value. 
  99.          * 如果丟失了就試圖建立一個item
  100.          */  
  101.   
  102.         V createdValue = create(key);  
  103.         if (createdValue == null) {  
  104.             return null;  
  105.         }  
  106.   
  107.         synchronized (this) {  
  108.             createCount++;//建立++  
  109.             mapValue = map.put(key, createdValue);  
  110.   
  111.             if (mapValue != null) {  
  112.                 // There was a conflict so undo that last put  
  113.                 //如果前面存在oldValue，那麼撤銷put（） 
  114.                 map.put(key, mapValue);  
  115.             } else {  
  116.                 size += safeSizeOf(key, createdValue);  
  117.             }  
  118.         }  
  119.   
  120.         if (mapValue != null) {  
  121.             entryRemoved(false, key, createdValue, mapValue);  
  122.             return mapValue;  
  123.         } else {  
  124.             trimToSize(maxSize);  
  125.             return createdValue;  
  126.         }  
  127.     }  
  128.   
  129.     /** 
  130.      * Caches {@code value} for {@code key}. The value is moved to the head of 
  131.      * the queue. 
  132.      * 
  133.      * @return the previous value mapped by {@code key}. 
  134.      */  
  135.     public final V put(K key, V value) {  
  136.         if (key == null || value == null) {  
  137.             throw new NullPointerException("key == null || value == null");  
  138.         }  
  139.   
  140.         V previous;  
  141.         synchronized (this) {  
  142.             putCount++;  
  143.             size += safeSizeOf(key, value);  
  144.             previous = map.put(key, value);  
  145.             if (previous != null) {  //返回的先前的value值
  146.                 size -= safeSizeOf(key, previous);  
  147.             }  
  148.         }  
  149.   
  150.         if (previous != null) {  
  151.             entryRemoved(false, key, previous, value);  
  152.         }  
  153.   
  154.         trimToSize(maxSize);  
  155.         return previous;  
  156.     }  
  157.   
  158.     /** 
  159.      * @param maxSize the maximum size of the cache before returning. May be -1 
  160.      *     to evict even 0-sized elements. 
  161.      *  清空cache空間
  162.      */  
  163.     private void trimToSize(int maxSize) {  
  164.         while (true) {  
  165.             K key;  
  166.             V value;  
  167.             synchronized (this) {  
  168.                 if (size < 0 || (map.isEmpty() && size != 0)) {  
  169.                     throw new IllegalStateException(getClass().getName()  
  170.                             + ".sizeOf() is reporting inconsistent results!");  
  171.                 }  
  172.   
  173.                 if (size <= maxSize) {  
  174.                     break;  
  175.                 }  
  176.   
  177.                 Map.Entry<K, V> toEvict = map.eldest();  
  178.                 if (toEvict == null) {  
  179.                     break;  
  180.                 }  
  181.   
  182.                 key = toEvict.getKey();  
  183.                 value = toEvict.getValue();  
  184.                 map.remove(key);  
  185.                 size -= safeSizeOf(key, value);  
  186.                 evictionCount++;  
  187.             }  
  188.   
  189.             entryRemoved(true, key, value, null);  
  190.         }  
  191.     }  
  192.   
  193.     /** 
  194.      * Removes the entry for {@code key} if it exists. 
  195.      * 刪除key相應的cache項，返回相應的value
  196.      * @return the previous value mapped by {@code key}. 
  197.      */  
  198.     public final V remove(K key) {  
  199.         if (key == null) {  
  200.             throw new NullPointerException("key == null");  
  201.         }  
  202.   
  203.         V previous;  
  204.         synchronized (this) {  
  205.             previous = map.remove(key);  
  206.             if (previous != null) {  
  207.                 size -= safeSizeOf(key, previous);  
  208.             }  
  209.         }  
  210.   
  211.         if (previous != null) {  
  212.             entryRemoved(false, key, previous, null);  
  213.         }  
  214.   
  215.         return previous;  
  216.     }  
  217.   
  218.     /** 
  219.      * Called for entries that have been evicted or removed. This method is 
  220.      * invoked when a value is evicted to make space, removed by a call to 
  221.      * {@link #remove}, or replaced by a call to {@link #put}. The default 
  222.      * implementation does nothing. 
  223.      * 當item被回收或者刪掉時呼叫。改方法當value被回收釋放儲存空間時被remove呼叫，
  224.      * 或者替換item值時put呼叫，預設實現什麼都沒做。
  225.      * <p>The method is called without synchronization: other threads may 
  226.      * access the cache while this method is executing. 
  227.      * 
  228.      * @param evicted true if the entry is being removed to make space, false 
  229.      *     if the removal was caused by a {@link #put} or {@link #remove}. 
  230.      * true---為釋放空間被刪除；false---put或remove導致
  231.      * @param newValue the new value for {@code key}, if it exists. If non-null, 
  232.      *     this removal was caused by a {@link #put}. Otherwise it was caused by 
  233.      *     an eviction or a {@link #remove}. 
  234.      */  
  235.     protected void entryRemoved(boolean evicted, K key, V oldValue, V newValue) {}  
  236.   
  237.     /** 
  238.      * Called after a cache miss to compute a value for the corresponding key. 
  239.      * Returns the computed value or null if no value can be computed. The 
  240.      * default implementation returns null. 
  241.      * 當某Item丟失時會呼叫到，返回計算的相應的value或者null
  242.      * <p>The method is called without synchronization: other threads may 
  243.      * access the cache while this method is executing. 
  244.      * 
  245.      * <p>If a value for {@code key} exists in the cache when this method 
  246.      * returns, the created value will be released with {@link #entryRemoved} 
  247.      * and discarded. This can occur when multiple threads request the same key 
  248.      * at the same time (causing multiple values to be created), or when one 
  249.      * thread calls {@link #put} while another is creating a value for the same 
  250.      * key. 
  251.      */  
  252.     protected V create(K key) {  
  253.         return null;  
  254.     }  
  255.   
  256.     private int safeSizeOf(K key, V value) {  
  257.         int result = sizeOf(key, value);  
  258.         if (result < 0) {  
  259.             throw new IllegalStateException("Negative size: " + key + "=" + value);  
  260.         }  
  261.         return result;  
  262.     }  
  263.   
  264.     /** 
  265.      * Returns the size of the entry for {@code key} and {@code value} in 
  266.      * user-defined units.  The default implementation returns 1 so that size 
  267.      * is the number of entries and max size is the maximum number of entries. 
  268.      * 返回使用者定義的item的大小，預設返回1代表item的數量，最大size就是最大item值
  269.      * <p>An entry's size must not change while it is in the cache. 
  270.      */  
  271.     protected int sizeOf(K key, V value) {  
  272.         return 1;  
  273.     }  
  274.   
  275.     /** 
  276.      * Clear the cache, calling {@link #entryRemoved} on each removed entry. 
  277.      * 清空cacke
  278.      */  
  279.     public final void evictAll() {  
  280.         trimToSize(-1); // -1 will evict 0-sized elements  
  281.     }  
  282.   
  283.     /** 
  284.      * For caches that do not override {@link #sizeOf}, this returns the number 
  285.      * of entries in the cache. For all other caches, this returns the sum of 
  286.      * the sizes of the entries in this cache. 
  287.      */  
  288.     public synchronized final int size() {  
  289.         return size;  
  290.     }  
  291.   
  292.     /** 
  293.      * For caches that do not override {@link #sizeOf}, this returns the maximum 
  294.      * number of entries in the cache. For all other caches, this returns the 
  295.      * maximum sum of the sizes of the entries in this cache. 
  296.      */  
  297.     public synchronized final int maxSize() {  
  298.         return maxSize;  
  299.     }  
  300.   
  301.     /** 
  302.      * Returns the number of times {@link #get} returned a value that was 
  303.      * already present in the cache. 
  304.      */  
  305.     public synchronized final int hitCount() {  
  306.         return hitCount;  
  307.     }  
  308.   
  309.     /** 
  310.      * Returns the number of times {@link #get} returned null or required a new 
  311.      * value to be created. 
  312.      */  
  313.     public synchronized final int missCount() {  
  314.         return missCount;  
  315.     }  
  316.   
  317.     /** 
  318.      * Returns the number of times {@link #create(Object)} returned a value. 
  319.      */  
  320.     public synchronized final int createCount() {  
  321.         return createCount;  
  322.     }  
  323.   
  324.     /** 
  325.      * Returns the number of times {@link #put} was called. 
  326.      */  
  327.     public synchronized final int putCount() {  
  328.         return putCount;  
  329.     }  
  330.   
  331.     /** 
  332.      * Returns the number of values that have been evicted. 
  333.      * 返回被回收的數量
  334.      */  
  335.     public synchronized final int evictionCount() {  
  336.         return evictionCount;  
  337.     }  
  338.   
  339.     /** 
  340.      * Returns a copy of the current contents of the cache, ordered from least 
  341.      * recently accessed to most recently accessed. 返回當前cache的副本，從最近最少訪問到最多訪問
  342.      */  
  343.     public synchronized final Map<K, V> snapshot() {  
  344.         return new LinkedHashMap<K, V>(map);  
  345.     }  
  346.   
  347.     @Override public synchronized final String toString() {  
  348.         int accesses = hitCount + missCount;  
  349.         int hitPercent = accesses != 0 ? (100 * hitCount / accesses) : 0;  
  350.         return String.format("LruCache[maxSize=%d,hits=%d,misses=%d,hitRate=%d%%]",  
  351.                 maxSize, hitCount, missCount, hitPercent);  
  352.     }  
  353. }  

相關文章