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 "base/base_export.h" 9 #include "base/compiler_specific.h" 10 #include "build/build_config.h" 11 12 namespace base { 13 14 namespace trace_event { 15 class MemoryAllocatorDump; 16 class ProcessMemoryDump; 17 } // namespace trace_event 18 19 // Discardable memory is used to cache large objects without worrying about 20 // blowing out memory, both on mobile devices where there is no swap, and 21 // desktop devices where unused free memory should be used to help the user 22 // experience. This is preferable to releasing memory in response to an OOM 23 // signal because it is simpler and provides system-wide management of 24 // purgable memory, though it has less flexibility as to which objects get 25 // discarded. 26 // 27 // Discardable memory has two states: locked and unlocked. While the memory is 28 // locked, it will not be discarded. Unlocking the memory allows the 29 // discardable memory system and the OS to reclaim it if needed. Locks do not 30 // nest. 31 // 32 // Notes: 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 40 // small allocations. 41 // - A discardable memory instance is not thread safe. It is the 42 // responsibility of users of discardable memory to ensure there are no 43 // races. 44 // 45 class BASE_EXPORT DiscardableMemory { 46 public: 47 DiscardableMemory(); 48 virtual ~DiscardableMemory(); 49 50 // Locks the memory so that it will not be purged by the system. Returns 51 // true on success. If the return value is false then this object should be 52 // destroyed and a new one should be created. 53 virtual bool Lock() WARN_UNUSED_RESULT = 0; 54 55 // Unlocks the memory so that it can be purged by the system. Must be called 56 // after every successful lock call. 57 virtual void Unlock() = 0; 58 59 // Returns the memory address held by this object. The object must be locked 60 // before calling this. 61 virtual void* data() const = 0; 62 63 // Forces the memory to be purged, such that any following Lock() will fail. 64 // The object must be unlocked before calling this. 65 virtual void DiscardForTesting() = 0; 66 67 // Handy method to simplify calling data() with a reinterpret_cast. data_as()68 template<typename T> T* data_as() const { 69 return reinterpret_cast<T*>(data()); 70 } 71 72 // Used for dumping the statistics of discardable memory allocated in tracing. 73 // Returns a new MemoryAllocatorDump in the |pmd| with the size of the 74 // discardable memory. The MemoryAllocatorDump created is owned by |pmd|. See 75 // ProcessMemoryDump::CreateAllocatorDump. 76 virtual trace_event::MemoryAllocatorDump* CreateMemoryAllocatorDump( 77 const char* name, 78 trace_event::ProcessMemoryDump* pmd) const = 0; 79 }; 80 81 enum class DiscardableMemoryBacking { kSharedMemory, kMadvFree }; 82 BASE_EXPORT DiscardableMemoryBacking GetDiscardableMemoryBacking(); 83 84 } // namespace base 85 86 #endif // BASE_MEMORY_DISCARDABLE_MEMORY_H_ 87