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 // Gets the discardable memory type with a given name. 68 static DiscardableMemoryType GetNamedType(const std::string& name); 69 70 // Gets the name of a discardable memory type. 71 static const char* GetTypeName(DiscardableMemoryType type); 72 73 // Gets system supported discardable memory types. Default preferred type 74 // at the front of vector. 75 static void GetSupportedTypes(std::vector<DiscardableMemoryType>* types); 76 77 // Sets the preferred discardable memory type. This overrides the default 78 // preferred type. Can only be called once prior to GetPreferredType() 79 // or CreateLockedMemory(). Caller is responsible for correct ordering. 80 static void SetPreferredType(DiscardableMemoryType type); 81 82 // Gets the preferred discardable memory type. 83 static DiscardableMemoryType GetPreferredType(); 84 85 // Create a DiscardableMemory instance with specified |type| and |size|. 86 static scoped_ptr<DiscardableMemory> CreateLockedMemoryWithType( 87 DiscardableMemoryType type, size_t size); 88 89 // Create a DiscardableMemory instance with preferred type and |size|. 90 static scoped_ptr<DiscardableMemory> CreateLockedMemory(size_t size); 91 92 // Discardable memory implementations might allow an elevated usage level 93 // while in frequent use. Call this to have the usage reduced to the base 94 // level. Returns true if there's no need to call this again until 95 // memory instances have been used. This indicates that all discardable 96 // memory implementations have reduced usage to the base level or below. 97 // Note: calling this too often or while discardable memory is in frequent 98 // use can hurt performance, whereas calling it too infrequently can result 99 // in memory bloat. 100 static bool ReduceMemoryUsage(); 101 102 // Locks the memory so that it will not be purged by the system. Returns 103 // DISCARDABLE_MEMORY_LOCK_STATUS_SUCCESS on success. If the return value is 104 // DISCARDABLE_MEMORY_LOCK_STATUS_FAILED then this object should be 105 // discarded and a new one should be created. If the return value is 106 // DISCARDABLE_MEMORY_LOCK_STATUS_PURGED then the memory is present but any 107 // data that was in it is gone. 108 virtual DiscardableMemoryLockStatus Lock() WARN_UNUSED_RESULT = 0; 109 110 // Unlocks the memory so that it can be purged by the system. Must be called 111 // after every successful lock call. 112 virtual void Unlock() = 0; 113 114 // Returns the memory address held by this object. The object must be locked 115 // before calling this. Otherwise, this will cause a DCHECK error. 116 virtual void* Memory() const = 0; 117 118 // Testing utility calls. 119 120 // Purge all discardable memory in the system. This call has global effects 121 // across all running processes, so it should only be used for testing! 122 static void PurgeForTesting(); 123 }; 124 125 } // namespace base 126 127 #endif // BASE_MEMORY_DISCARDABLE_MEMORY_H_ 128
