Add comments to bitmap pools

Change-Id: Ie841316629ef0737dcdd5002b3278cf0bca3a768

1 files changed, 36 insertions, 1 deletions

diff --git a/src/com/android/photos/data/GalleryBitmapPool.java b/src/com/android/photos/data/GalleryBitmapPool.java
index a5a17ede2..7eb9794c5 100644
--- a/src/com/android/photos/data/GalleryBitmapPool.java
+++ b/src/com/android/photos/data/GalleryBitmapPool.java
@@ -23,9 +23,25 @@ import android.util.Pools.SimplePool;
 
 import com.android.photos.data.SparseArrayBitmapPool.Node;
 
+/**
+ * Pool allowing the efficient reuse of bitmaps in order to avoid long
+ * garbage collection pauses.
+ */
 public class GalleryBitmapPool {
 
     private static final int CAPACITY_BYTES = 20971520;
+
+    // We found that Gallery uses bitmaps that are either square (for example,
+    // tiles of large images or square thumbnails), match one of the common
+    // photo aspect ratios (4x3, 3x2, or 16x9), or, less commonly, are of some
+    // other aspect ratio. Taking advantage of this information, we use 3
+    // SparseArrayBitmapPool instances to back the GalleryBitmapPool, which affords
+    // O(1) lookups for square bitmaps, and average-case - but *not* asymptotically -
+    // O(1) lookups for common photo aspect ratios and other miscellaneous aspect
+    // ratios. Beware of the pathological case where there are many bitmaps added
+    // to the pool with different non-square aspect ratios but the same width, as
+    // performance will degrade and the average case lookup will approach
+    // O(# of different aspect ratios).
     private static final int POOL_INDEX_NONE = -1;
     private static final int POOL_INDEX_SQUARE = 0;
     private static final int POOL_INDEX_PHOTO = 1;
@@ -84,11 +100,20 @@ public class GalleryBitmapPool {
         return POOL_INDEX_MISC;
     }
 
+    /**
+     * @return Capacity of the pool in bytes.
+     */
     public synchronized int getCapacity() {
         return mCapacityBytes;
     }
 
-    public synchronized int getSize() {
+    /**
+     * @return Approximate total size in bytes of the bitmaps stored in the pool.
+     */
+    public int getSize() {
+        // Note that this only returns an approximate size, since multiple threads
+        // might be getting and putting Bitmaps from the pool and we lock at the
+        // sub-pool level to avoid unnecessary blocking.
         int total = 0;
         for (SparseArrayBitmapPool p : mPools) {
             total += p.getSize();
@@ -96,6 +121,9 @@ public class GalleryBitmapPool {
         return total;
     }
 
+    /**
+     * @return Bitmap from the pool with the desired height/width or null if none available.
+     */
     public Bitmap get(int width, int height) {
         SparseArrayBitmapPool pool = getPoolForDimensions(width, height);
         if (pool == null) {
@@ -105,6 +133,10 @@ public class GalleryBitmapPool {
         }
     }
 
+    /**
+     * Adds the given bitmap to the pool.
+     * @return Whether the bitmap was added to the pool.
+     */
     public boolean put(Bitmap b) {
         if (b == null || b.getConfig() != Bitmap.Config.ARGB_8888) {
             return false;
@@ -118,6 +150,9 @@ public class GalleryBitmapPool {
         }
     }
 
+    /**
+     * Empty the pool, recycling all the bitmaps currently in it.
+     */
     public void clear() {
         for (SparseArrayBitmapPool p : mPools) {
             p.clear();