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 11 namespace base { 12 13 namespace trace_event { 14 class MemoryAllocatorDump; 15 class ProcessMemoryDump; 16 } 17 18 // Discardable memory is used to cache large objects without worrying about 19 // blowing out memory, both on mobile devices where there is no swap, and 20 // desktop devices where unused free memory should be used to help the user 21 // experience. This is preferable to releasing memory in response to an OOM 22 // signal because it is simpler and provides system-wide management of 23 // purgable memory, though it has less flexibility as to which objects get 24 // discarded. 25 // 26 // Discardable memory has two states: locked and unlocked. While the memory is 27 // locked, it will not be discarded. Unlocking the memory allows the 28 // discardable memory system and the OS to reclaim it if needed. Locks do not 29 // nest. 30 // 31 // Notes: 32 // - The paging behavior of memory while it is locked is not specified. While 33 // mobile platforms will not swap it out, it may qualify for swapping 34 // on desktop platforms. It is not expected that this will matter, as the 35 // preferred pattern of usage for DiscardableMemory is to lock down the 36 // memory, use it as quickly as possible, and then unlock it. 37 // - Because of memory alignment, the amount of memory allocated can be 38 // larger than the requested memory size. It is not very efficient for 39 // small allocations. 40 // - A discardable memory instance is not thread safe. It is the 41 // responsibility of users of discardable memory to ensure there are no 42 // races. 43 // 44 class BASE_EXPORT DiscardableMemory { 45 public: 46 DiscardableMemory(); 47 virtual ~DiscardableMemory(); 48 49 // Locks the memory so that it will not be purged by the system. Returns 50 // true on success. If the return value is false then this object should be 51 // discarded and a new one should be created. 52 virtual bool Lock() WARN_UNUSED_RESULT = 0; 53 54 // Unlocks the memory so that it can be purged by the system. Must be called 55 // after every successful lock call. 56 virtual void Unlock() = 0; 57 58 // Returns the memory address held by this object. The object must be locked 59 // before calling this. 60 virtual void* data() const = 0; 61 62 // Handy method to simplify calling data() with a reinterpret_cast. data_as()63 template<typename T> T* data_as() const { 64 return reinterpret_cast<T*>(data()); 65 } 66 67 // Used for dumping the statistics of discardable memory allocated in tracing. 68 // Returns a new MemoryAllocatorDump in the |pmd| with the size of the 69 // discardable memory. The MemoryAllocatorDump created is owned by |pmd|. See 70 // ProcessMemoryDump::CreateAllocatorDump. 71 virtual trace_event::MemoryAllocatorDump* CreateMemoryAllocatorDump( 72 const char* name, 73 trace_event::ProcessMemoryDump* pmd) const = 0; 74 }; 75 76 } // namespace base 77 78 #endif // BASE_MEMORY_DISCARDABLE_MEMORY_H_ 79