Improvements/additions to SkImageCache/SkLazyPixelRef.

SkPurgeableImageCache:
New image cache that uses virtual memory to store the pixels. Combines
features of SkAshmemImageCache (which has been removed) with SkPurgeableMemoryBlock, which has android and Mac versions.

SkImageCache:
Modified the API. pinCache now returns a status out parameter which
states whether the pinned memory retained the old data. This allows
allocAndPinCache to only be used for allocations.
Add a new debug only interface to purge unpinned data.
Updates to documentation, clarifying behavior.
Changed CachedStatus to MemoryStatus

SkLruImageCache:
Implement the new function purgeAllUnpinnedCaches and change implementation
of pinCache for the new behavior.

SkLazyPixelRef:
Rewrite onLockPixels to account for the new behavior of pinCache.

BitmapFactoryTest:
Test the new SkPurgeableImageCache.
Write tests which directly test the SkImageCaches.
Create a larger bitmap, since some of the SkImageCaches are designed
to handle large bitmaps.

bench_ and render_pictures:
Consolidate lazy_decode_bitmap into one function.
Allow using a flag to specify using the purgeable image cache.
Clean up some #includes.

Review URL: https://codereview.chromium.org/12433020

git-svn-id: http://skia.googlecode.com/svn/trunk@8207 2bbb7eff-a529-9590-31e7-b0007b416f81

5 files changed, 127 insertions, 95 deletions

diff --git a/include/lazy/SkBitmapFactory.h b/include/lazy/SkBitmapFactory.h
index bebd3a7cee..eb427ee390 100644
--- a/include/lazy/SkBitmapFactory.h
+++ b/include/lazy/SkBitmapFactory.h
@@ -67,20 +67,29 @@ public:
     bool installPixelRef(SkData*, SkBitmap*);
 
     /**
-     *  A function for selecting an SkImageCache to use based on an SkImage::Info.
+     *  An object for selecting an SkImageCache to use based on an SkImage::Info.
      */
-    typedef SkImageCache* (*CacheSelector)(const SkImage::Info&);
+    class CacheSelector : public SkRefCnt {
+
+    public:
+        /**
+         *  Return an SkImageCache to use based on the provided SkImage::Info. If the caller decides
+         *  to hang on to the result, it will call ref, so the implementation should not add a ref
+         *  as a result of this call.
+         */
+        virtual SkImageCache* selectCache(const SkImage::Info&) = 0;
+    };
 
     /**
      *  Set the function to be used to select which SkImageCache to use. Mutually exclusive with
      *  fImageCache.
      */
-    void setCacheSelector(CacheSelector);
+    void setCacheSelector(CacheSelector*);
 
 private:
-    DecodeProc    fDecodeProc;
-    SkImageCache* fImageCache;
-    CacheSelector fCacheSelector;
+    DecodeProc     fDecodeProc;
+    SkImageCache*  fImageCache;
+    CacheSelector* fCacheSelector;
 };
 
 #endif // SkBitmapFactory_DEFINED
diff --git a/include/lazy/SkImageCache.h b/include/lazy/SkImageCache.h
index 6cd064ba5b..bfd5269ee9 100644
--- a/include/lazy/SkImageCache.h
+++ b/include/lazy/SkImageCache.h
@@ -22,22 +22,45 @@ public:
      *  call to releaseCache and a call to throwAwayCache.
      *  @param bytes Number of bytes needed.
      *  @param ID Output parameter which must not be NULL. On success, ID will be set to a value
-     *         associated with that memory which can be used as a parameter to the other functions
-     *         in SkImageCache. On failure, ID is unchanged.
+     *      associated with that memory which can be used as a parameter to the other functions
+     *      in SkImageCache. On failure, ID is unchanged.
      *  @return Pointer to the newly allocated memory, or NULL. This memory is safe to use until
-     *          releaseCache is called with ID.
+     *      releaseCache is called with ID.
      */
     virtual void* allocAndPinCache(size_t bytes, intptr_t* ID) = 0;
 
     /**
-     *  Re-request the memory associated with ID.
+     *  Output parameter for pinCache, stating whether the memory still contains the data it held
+     *  when releaseCache was last called for the same ID.
+     */
+    enum DataStatus {
+        /**
+         *  The data has been purged, and therefore needs to be rewritten to the returned memory.
+         */
+        kUninitialized_DataStatus,
+
+        /**
+         *  The memory still contains the data it held when releaseCache was last called with the
+         *  same ID.
+         */
+        kRetained_DataStatus,
+    };
+
+    /**
+     *  Re-request the memory associated with ID and pin it so that it will not be reclaimed until
+     *  the next call to releaseCache with the same ID.
      *  @param ID Unique ID for the memory block.
+     *  @param status Output parameter which must not be NULL. On success (i.e. the return value is
+     *      not NULL), status will be set to one of two states representing the cached memory. If
+     *      status is set to kRetained_DataStatus, the memory contains the same data it did
+     *      before releaseCache was called with this ID. If status is set to
+     *      kUninitialized_DataStatus, the memory is still pinned, but the previous data is no
+     *      longer available. If the return value is NULL, status is unchanged.
      *  @return Pointer: If non-NULL, points to the previously allocated memory, in which case
-     *          this call must be balanced with a call to releaseCache. If NULL, the memory
-     *          has been reclaimed, so allocAndPinCache must be called again with a pointer to
-     *          the same ID.
+     *      this call must be balanced with a call to releaseCache. If NULL, the memory
+     *      has been reclaimed, and throwAwayCache MUST NOT be called.
      */
-    virtual void* pinCache(intptr_t ID) = 0;
+    virtual void* pinCache(intptr_t ID, DataStatus* status) = 0;
 
     /**
      *  Inform the cache that it is safe to free the block of memory corresponding to ID. After
@@ -61,16 +84,42 @@ public:
     static const intptr_t UNINITIALIZED_ID = 0;
 
 #ifdef SK_DEBUG
-    enum CacheStatus {
-        kPinned_CacheStatus,
-        kUnpinned_CacheStatus,
-        kThrownAway_CacheStatus,
+    /**
+     *  Debug only status of a memory block.
+     */
+    enum MemoryStatus {
+        /**
+         *  It is safe to use the pointer returned by the most recent of allocAndPinCache(ID) or
+         *  pinCache(ID) with the same ID.
+         */
+        kPinned_MemoryStatus,
+
+        /**
+         *  The pointer returned by the most recent call to allocAndPinCache(ID) or pinCache(ID) has
+         *  since been released by releaseCache(ID). In order to reuse it, pinCache(ID) must be
+         *  called again. Note that after calling releaseCache(ID), the status of that particular
+         *  ID may not be kUnpinned_MemoryStatus, depending on the implementation, but it will not
+         *  be kPinned_MemoryStatus.
+         */
+        kUnpinned_MemoryStatus,
+
+        /**
+         *  The memory associated with ID has been thrown away. No calls should be made using the
+         *  same ID.
+         */
+        kFreed_MemoryStatus,
     };
 
     /**
-     *  Debug only function to get the status of a particular block of memory.
+     *  Debug only function to get the status of a particular block of memory. Safe to call after
+     *  throwAwayCache has been called with this ID.
+     */
+    virtual MemoryStatus getMemoryStatus(intptr_t ID) const = 0;
+
+    /**
+     *  Debug only function to clear all unpinned caches.
      */
-    virtual CacheStatus getCacheStatus(intptr_t ID) const = 0;
+    virtual void purgeAllUnpinnedCaches() = 0;
 #endif
 };
 #endif // SkImageCache_DEFINED
diff --git a/include/lazy/SkLruImageCache.h b/include/lazy/SkLruImageCache.h
index 05d28150b0..f655230a93 100644
--- a/include/lazy/SkLruImageCache.h
+++ b/include/lazy/SkLruImageCache.h
@@ -25,7 +25,8 @@ public:
     virtual ~SkLruImageCache();
 
 #ifdef SK_DEBUG
-    CacheStatus getCacheStatus(intptr_t ID) const SK_OVERRIDE;
+    virtual MemoryStatus getMemoryStatus(intptr_t ID) const SK_OVERRIDE;
+    virtual void purgeAllUnpinnedCaches() SK_OVERRIDE;
 #endif
 
     /**
@@ -45,7 +46,7 @@ public:
     size_t getImageCacheUsed() const { return fRamUsed; }
 
     virtual void* allocAndPinCache(size_t bytes, intptr_t* ID) SK_OVERRIDE;
-    virtual void* pinCache(intptr_t ID) SK_OVERRIDE;
+    virtual void* pinCache(intptr_t ID, SkImageCache::DataStatus*) SK_OVERRIDE;
     virtual void releaseCache(intptr_t ID) SK_OVERRIDE;
     virtual void throwAwayCache(intptr_t ID) SK_OVERRIDE;
 
@@ -55,7 +56,7 @@ private:
     typedef SkTInternalLList<CachedPixels>::Iter Iter;
 
 #ifdef SK_DEBUG
-    // fMutex is mutable so that getCacheStatus can be const
+    // fMutex is mutable so that getMemoryStatus can be const
     mutable
 #endif
     SkMutex fMutex;
diff --git a/include/lazy/SkPurgeableImageCache.h b/include/lazy/SkPurgeableImageCache.h
new file mode 100644
index 0000000000..0516ff18ef
--- /dev/null
+++ b/include/lazy/SkPurgeableImageCache.h
@@ -0,0 +1,45 @@
+/*
+ * Copyright 2013 Google Inc.
+ *
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#ifndef SkPurgeableImageCache_DEFINED
+#define SkPurgeableImageCache_DEFINED
+
+#include "SkImageCache.h"
+
+#ifdef SK_DEBUG
+    #include "SkTDArray.h"
+#endif
+
+/**
+ *  Implementation for SkImageCache that uses system defined purgeable memory.
+ */
+class SkPurgeableImageCache : public SkImageCache {
+
+public:
+    static SkImageCache* Create();
+
+    virtual void* allocAndPinCache(size_t bytes, intptr_t* ID) SK_OVERRIDE;
+    virtual void* pinCache(intptr_t ID, SkImageCache::DataStatus*) SK_OVERRIDE;
+    virtual void releaseCache(intptr_t ID) SK_OVERRIDE;
+    virtual void throwAwayCache(intptr_t ID) SK_OVERRIDE;
+
+#ifdef SK_DEBUG
+    virtual MemoryStatus getMemoryStatus(intptr_t ID) const SK_OVERRIDE;
+    virtual void purgeAllUnpinnedCaches() SK_OVERRIDE;
+    virtual ~SkPurgeableImageCache();
+#endif
+
+private:
+    SkPurgeableImageCache();
+
+#ifdef SK_DEBUG
+    SkTDArray<intptr_t> fRecs;
+    int findRec(intptr_t) const;
+#endif
+    void removeRec(intptr_t);
+};
+#endif // SkPurgeableImageCache_DEFINED
diff --git a/include/ports/SkAshmemImageCache.h b/include/ports/SkAshmemImageCache.h
deleted file mode 100644
index 817e702490..0000000000
--- a/include/ports/SkAshmemImageCache.h
+++ /dev/null
@@ -1,72 +0,0 @@
-/*
- * Copyright 2013 Google Inc.
- *
- * Use of this source code is governed by a BSD-style license that can be
- * found in the LICENSE file.
- */
-
-#ifndef SkAshmemImageCache_DEFINED
-#define SkAshmemImageCache_DEFINED
-
-#include "SkImageCache.h"
-#include "SkTDArray.h"
-#include "SkTypes.h"
-
-class SkAshmemImageCache : public SkImageCache {
-
-public:
-    /**
-     *  Get a pointer to the single global instance of SkAshmemImageCache.
-     */
-    static SkAshmemImageCache* GetAshmemImageCache();
-
-    virtual void* allocAndPinCache(size_t bytes, intptr_t* ID) SK_OVERRIDE;
-    virtual void* pinCache(intptr_t ID) SK_OVERRIDE;
-    virtual void releaseCache(intptr_t ID) SK_OVERRIDE;
-    virtual void throwAwayCache(intptr_t ID) SK_OVERRIDE;
-
-#ifdef SK_DEBUG
-    SkImageCache::CacheStatus getCacheStatus(intptr_t ID) const SK_OVERRIDE;
-
-    virtual ~SkAshmemImageCache();
-#endif
-
-private:
-    struct AshmemRec {
-        int    fFD;
-        void*  fAddr;
-        size_t fSize;
-#ifdef SK_DEBUG
-        bool   fPinned;
-
-        static int Compare(const AshmemRec*, const AshmemRec*);
-#endif
-    };
-
-    /**
-     *  Constructor is private. The correct way to get this cache is through
-     *  GetAshmemImageCache, so that all callers can get the single global.
-     */
-    SkAshmemImageCache();
-
-#ifdef SK_DEBUG
-    // Stores a list of AshmemRecs to track deletion.
-    SkTDArray<AshmemRec*> fRecs;
-
-    /**
-     *  Debug only function to add an AshmemRec to the list.
-     */
-    void appendRec(AshmemRec*);
-
-    /**
-     *  Return the index of AshmemRec.
-     */
-    int findRec(const AshmemRec*) const;
-#endif
-
-    /**
-     *  Deletes AshmemRec. In debug, also removes from the list.
-     */
-    void removeRec(AshmemRec*);
-};
-#endif // SkAshmemImageCache_DEFINED