1 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 #ifndef BASE_MEMORY_DISCARDABLE_MEMORY_H_
6 #define BASE_MEMORY_DISCARDABLE_MEMORY_H_
8 #include "base/base_export.h"
9 #include "base/basictypes.h"
10 #include "base/compiler_specific.h"
11 #include "base/memory/scoped_ptr.h"
15 enum LockDiscardableMemoryStatus {
16 DISCARDABLE_MEMORY_FAILED = -1,
17 DISCARDABLE_MEMORY_PURGED = 0,
18 DISCARDABLE_MEMORY_SUCCESS = 1
21 // Platform abstraction for discardable memory. DiscardableMemory is used to
22 // cache large objects without worrying about blowing out memory, both on mobile
23 // devices where there is no swap, and desktop devices where unused free memory
24 // should be used to help the user experience. This is preferable to releasing
25 // memory in response to an OOM signal because it is simpler, though it has less
26 // flexibility as to which objects get discarded.
28 // Discardable memory has two states: locked and unlocked. While the memory is
29 // locked, it will not be discarded. Unlocking the memory allows the OS to
30 // reclaim it if needed. Locks do not nest.
33 // - The paging behavior of memory while it is locked is not specified. While
34 // mobile platforms will not swap it out, it may qualify for swapping
35 // on desktop platforms. It is not expected that this will matter, as the
36 // preferred pattern of usage for DiscardableMemory is to lock down the
37 // memory, use it as quickly as possible, and then unlock it.
38 // - Because of memory alignment, the amount of memory allocated can be
39 // larger than the requested memory size. It is not very efficient for
41 // - A discardable memory instance is not thread safe. It is the
42 // responsibility of users of discardable memory to ensure there are no
46 // - Linux: http://lwn.net/Articles/452035/
47 // - Mac: http://trac.webkit.org/browser/trunk/Source/WebCore/platform/mac/PurgeableBufferMac.cpp
48 // the comment starting with "vm_object_purgable_control" at
49 // http://www.opensource.apple.com/source/xnu/xnu-792.13.8/osfmk/vm/vm_object.c
50 class BASE_EXPORT DiscardableMemory {
52 virtual ~DiscardableMemory() {}
54 // Check whether the system supports discardable memory natively. Returns
55 // false if the support is emulated.
56 static bool SupportedNatively();
58 static scoped_ptr<DiscardableMemory> CreateLockedMemory(size_t size);
60 // Locks the memory so that it will not be purged by the system. Returns
61 // DISCARDABLE_MEMORY_SUCCESS on success. If the return value is
62 // DISCARDABLE_MEMORY_FAILED then this object should be discarded and
63 // a new one should be created. If the return value is
64 // DISCARDABLE_MEMORY_PURGED then the memory is present but any data that
66 virtual LockDiscardableMemoryStatus Lock() WARN_UNUSED_RESULT = 0;
68 // Unlocks the memory so that it can be purged by the system. Must be called
69 // after every successful lock call.
70 virtual void Unlock() = 0;
72 // Returns the memory address held by this object. The object must be locked
73 // before calling this. Otherwise, this will cause a DCHECK error.
74 virtual void* Memory() const = 0;
76 // Testing utility calls.
78 // Check whether a purge of all discardable memory in the system is supported.
79 // Use only for testing!
80 static bool PurgeForTestingSupported();
82 // Purge all discardable memory in the system. This call has global effects
83 // across all running processes, so it should only be used for testing!
84 static void PurgeForTesting();
89 #endif // BASE_MEMORY_DISCARDABLE_MEMORY_H_