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. 4 5 #ifndef BASE_MEMORY_DISCARDABLE_MEMORY_H_ 6 #define BASE_MEMORY_DISCARDABLE_MEMORY_H_ 7 8 #include <string> 9 #include <vector> 10 11 #include "base/base_export.h" 12 #include "base/basictypes.h" 13 #include "base/compiler_specific.h" 14 #include "base/memory/scoped_ptr.h" 15 16 namespace base { 17 18 enum DiscardableMemoryType { 19 DISCARDABLE_MEMORY_TYPE_NONE, 20 DISCARDABLE_MEMORY_TYPE_ASHMEM, 21 DISCARDABLE_MEMORY_TYPE_MAC, 22 DISCARDABLE_MEMORY_TYPE_EMULATED, 23 DISCARDABLE_MEMORY_TYPE_MALLOC 24 }; 25 26 enum DiscardableMemoryLockStatus { 27 DISCARDABLE_MEMORY_LOCK_STATUS_FAILED, 28 DISCARDABLE_MEMORY_LOCK_STATUS_PURGED, 29 DISCARDABLE_MEMORY_LOCK_STATUS_SUCCESS 30 }; 31 32 // Platform abstraction for discardable memory. DiscardableMemory is used to 33 // cache large objects without worrying about blowing out memory, both on mobile 34 // devices where there is no swap, and desktop devices where unused free memory 35 // should be used to help the user experience. This is preferable to releasing 36 // memory in response to an OOM signal because it is simpler, though it has less 37 // flexibility as to which objects get discarded. 38 // 39 // Discardable memory has two states: locked and unlocked. While the memory is 40 // locked, it will not be discarded. Unlocking the memory allows the OS to 41 // reclaim it if needed. Locks do not nest. 42 // 43 // Notes: 44 // - The paging behavior of memory while it is locked is not specified. While 45 // mobile platforms will not swap it out, it may qualify for swapping 46 // on desktop platforms. It is not expected that this will matter, as the 47 // preferred pattern of usage for DiscardableMemory is to lock down the 48 // memory, use it as quickly as possible, and then unlock it. 49 // - Because of memory alignment, the amount of memory allocated can be 50 // larger than the requested memory size. It is not very efficient for 51 // small allocations. 52 // - A discardable memory instance is not thread safe. It is the 53 // responsibility of users of discardable memory to ensure there are no 54 // races. 55 // 56 // References: 57 // - Linux: http://lwn.net/Articles/452035/ 58 // - Mac: http://trac.webkit.org/browser/trunk/Source/WebCore/platform/mac/PurgeableBufferMac.cpp 59 // the comment starting with "vm_object_purgable_control" at 60 // http://www.opensource.apple.com/source/xnu/xnu-792.13.8/osfmk/vm/vm_object.c 61 // 62 // Thread-safety: DiscardableMemory instances are not thread-safe. 63 class BASE_EXPORT DiscardableMemory { 64 public: 65 virtual ~DiscardableMemory() {} 66 67 // Call this on a thread with a MessageLoop current to allow discardable 68 // memory implementations to respond to memory pressure signals. 69 static void RegisterMemoryPressureListeners(); 70 71 // Call this to prevent discardable memory implementations from responding 72 // to memory pressure signals. 73 static void UnregisterMemoryPressureListeners(); 74 75 // Gets the discardable memory type with a given name. 76 static DiscardableMemoryType GetNamedType(const std::string& name); 77 78 // Gets the name of a discardable memory type. 79 static const char* GetTypeName(DiscardableMemoryType type); 80 81 // Gets system supported discardable memory types. Default preferred type 82 // at the front of vector. 83 static void GetSupportedTypes(std::vector<DiscardableMemoryType>* types); 84 85 // Sets the preferred discardable memory type. This overrides the default 86 // preferred type. Can only be called once prior to GetPreferredType() 87 // or CreateLockedMemory(). Caller is responsible for correct ordering. 88 static void SetPreferredType(DiscardableMemoryType type); 89 90 // Gets the preferred discardable memory type. 91 static DiscardableMemoryType GetPreferredType(); 92 93 // Create a DiscardableMemory instance with specified |type| and |size|. 94 static scoped_ptr<DiscardableMemory> CreateLockedMemoryWithType( 95 DiscardableMemoryType type, size_t size); 96 97 // Create a DiscardableMemory instance with preferred type and |size|. 98 static scoped_ptr<DiscardableMemory> CreateLockedMemory(size_t size); 99 100 // Discardable memory implementations might allow an elevated usage level 101 // while in frequent use. Call this to have the usage reduced to the base 102 // level. Returns true if there's no need to call this again until 103 // memory instances have been used. This indicates that all discardable 104 // memory implementations have reduced usage to the base level or below. 105 // Note: calling this too often or while discardable memory is in frequent 106 // use can hurt performance, whereas calling it too infrequently can result 107 // in memory bloat. 108 static bool ReduceMemoryUsage(); 109 110 // Locks the memory so that it will not be purged by the system. Returns 111 // DISCARDABLE_MEMORY_LOCK_STATUS_SUCCESS on success. If the return value is 112 // DISCARDABLE_MEMORY_LOCK_STATUS_FAILED then this object should be 113 // discarded and a new one should be created. If the return value is 114 // DISCARDABLE_MEMORY_LOCK_STATUS_PURGED then the memory is present but any 115 // data that was in it is gone. 116 virtual DiscardableMemoryLockStatus Lock() WARN_UNUSED_RESULT = 0; 117 118 // Unlocks the memory so that it can be purged by the system. Must be called 119 // after every successful lock call. 120 virtual void Unlock() = 0; 121 122 // Returns the memory address held by this object. The object must be locked 123 // before calling this. Otherwise, this will cause a DCHECK error. 124 virtual void* Memory() const = 0; 125 126 // Testing utility calls. 127 128 // Purge all discardable memory in the system. This call has global effects 129 // across all running processes, so it should only be used for testing! 130 static void PurgeForTesting(); 131 }; 132 133 } // namespace base 134 135 #endif // BASE_MEMORY_DISCARDABLE_MEMORY_H_ 136
