Create a platform-dependent object for accessing purgeable memory.

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();

[djsollen, 2013/03/14 13:56:31]

writing SkPurgeableMemoryBlock::PlatformSupportsPurgeableMemory() seems to be a
little redundant. Could it be shortened to
SkPurgeableMemoryBlock::IsSupported();

[scroggo, 2013/03/14 15:36:13]

Done.

+
+    /**
+     *  Create a new purgeable memory block of 'size' bytes. Returns NULL if not supported on this
+     *  platform or on failure.
+     *  @param size Number of bytes requested.
+     *  @return A new block, or NULL on failure.
+     */
+    static SkPurgeableMemoryBlock* CreatePurgeableMemoryBlock(size_t size);

[djsollen, 2013/03/14 13:56:31]

following the naming of other factories like SkBlurMaskFilter can this be
shortened to just Create(size_t size)?

[scroggo, 2013/03/14 15:36:13]

Done.

+
+#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; }

[djsollen, 2013/03/14 13:56:31]

Is this really needed? Who calls this?

[scroggo, 2013/03/14 15:36:13]

This is a debug only function just for debugging. It is called by
SkPurgeableImageCache::getMemoryStatus (part of my larger CL that is not
included here. The caller is on line 120 of
https://codereview.chromium.org/12433020/diff/47002/src/lazy/SkPurgeableImage...).

I wanted to have a way to test how it behaves when the system purges the memory,
but I could not find a way to do that on android (I found
ASHMEM_PURGE_ALL_CACHES, but it does not seem to be public) so I cheated and set
the file descriptor to -1, which I later use as a sign that it has been purged.
Do you know how to purge ashmem? I am not happy with this API either.

[scroggo, 2013/03/14 18:05:32]

Removed! Thanks for adding the purge function!

+#endif
+
+#endif
+
+    ~SkPurgeableMemoryBlock();
+
+    /**
+     *  Output parameter for pin(), stating whether the data has been retained.
+     */
+    enum PinResult {
+        /**
+         *  The data has been purged, or this is the first call to pin.
+         */
+        kUninitialized_PinResult,
+
+        /**
+         *  The data has been retained. The memory contains the same data it held when unpin() was
+         *  called.
+         */
+        kRetained_PinResult,
+    };
+
+    /**
+     *  Pin the memory for use. Must not be called while already pinned.
+     *  @param PinResult Whether the data was retained. Ignored on failure.
+     *  @return Pointer to the pinned data on success. NULL on failure.
+     */
+    void* pin(PinResult*);
+
+    /**
+     *  Unpin the data so it can be purged if necessary.
+     */
+    void unpin();
+
+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