Improvements/additions to SkImageCache/SkLazyPixelRef.

src/lazy/SkPurgeableMemoryBlock.h

+/*
+ * 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 SkPurgeableMemoryBlock_DEFINED
+#define SkPurgeableMemoryBlock_DEFINED
+
+#include "SkTypes.h"
+
+class SkPurgeableMemoryBlock : public SkNoncopyable {
+
+public:
+    /**
+     *  Whether or not this platform has an implementation for purgeable memory.
+     */
+    static bool PlatformSupportsPurgeableMemory();
+
+    /**
+     *  Create a new purgeable memory block with size >= size. Returns NULL if not supported on this

[reed1, 2013/03/13 20:41:34]

size >= size is a funny statement. How about

Create a new purgeable memory block of 'size' bytes.

Do we need to say that it might be larger under the hood?

[scroggo, 2013/03/13 22:06:42]

Done.

+     *  platform or on failure.
+     *  @param size Number of bytes requested. The resulting data will be at least this large.
+     *  @return A new block, or NULL on failure. On success, the memory will already be pinned.

[reed1, 2013/03/13 20:41:34]

Why should it already be pinned?

[scroggo, 2013/03/13 22:06:42]

Currently, the only client (allocAndPinCache) wants the memory to be pinned when
it asks for it. I uploaded a patch that changes this behavior so we can decide
if we like that better.

+     */
+    static SkPurgeableMemoryBlock* CreatePurgeableMemoryBlock(size_t size);
+
+#ifdef SK_DEBUG
+    /**
+     *  Whether the platform supports one shot purge of all unpinned blocks. If so,
+     *  PurgeAllUnpinnedBlocks will be used to test a purge. Otherwise, purge will be called on
+     *  individual blocks.
+     */
+    static bool PlatformSupportsPurgingAllUnpinnedBlocks();
+
+    /**
+     *  Purge all unpinned blocks at once, if the platform supports it.
+     */
+    static bool PurgeAllUnpinnedBlocks();
+
+    // If PlatformSupportsPurgingAllUnpinnedBlocks returns true, this will not be called, so it can
+    // simply return false.
+    bool purge();
+
+    bool isPinned() const { return fPinned; }
+
+#ifdef SK_BUILD_FOR_ANDROID
+    int getFD() const { return fFD; }
+#endif
+
+#endif
+
+    ~SkPurgeableMemoryBlock();
+
+    /**
+     *  Result of a call to pin().
+     */
+    enum PinResult {
+        /**
+         *  The pin succeeded, and the data has been purged. It will need to be rewritten to the
+         *  memory.
+         */
+        kUninitialized_PinResult,
+
+        /**
+         *  The pin succeeded, and the data has been retained. The memory contains the same data it
+         *  held when unpin() was called.
+         */
+        kRetained_PinResult,
+
+        /**
+         *  The pin failed. This object should be discarded.
+         */
+        kFailed_PinResult,
+    };
+
+    /**
+     *  Pin the memory for use. Must not be called while already pinned.

[reed1, 2013/03/13 20:41:34]

Why is this api different from the decoder, in that here there are two separate
calls: pin() and data(), instead of one: void* pin(PinResult*)

Not critical, but that sort of api makes it a little clearer that the void* (1)
may change between pin calls, and (2) it is only valid during a pin.

[scroggo, 2013/03/13 22:06:42]

In the implementation from this patch, it starts off pinned, and there needs to
be a way to access the data without calling pin. The latest patch changes it so
it does not start off pinned, so I can use that API.

+     */
+    PinResult pin();
+
+    /**
+     *  Unpin the data so it can be purged if necessary.
+     */
+    void unpin();
+
+    /**
+     *  Pointer to the data. Should only be used after a call to pin which succeeds.
+     */
+    void* data() { return fAddr; }
+
+private:
+    void*       fAddr;
+    size_t      fSize;
+    bool        fPinned;
+#ifdef SK_BUILD_FOR_ANDROID
+    int         fFD;
+#endif
+
+    // Unimplemented default constructor is private, to prevent manual creation.
+    SkPurgeableMemoryBlock();
+
+    // The correct way to create a new one is from the static CreatePurgeableMemoryBlock.
+    SkPurgeableMemoryBlock(size_t);
+};
+
+#endif // SkPurgeableMemoryBlock_DEFINED