1 // Copyright 2013 The Chromium Authors
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 "build/build_config.h"
13 namespace trace_event {
14 class MemoryAllocatorDump;
15 class ProcessMemoryDump;
16 } // namespace trace_event
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
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
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
40 // - A discardable memory instance is not thread safe. It is the
41 // responsibility of users of discardable memory to ensure there are no
44 class BASE_EXPORT DiscardableMemory {
47 virtual ~DiscardableMemory();
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 // destroyed and a new one should be created.
52 [[nodiscard]] virtual bool Lock() = 0;
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;
58 // Returns the memory address held by this object. The object must be locked
59 // before calling this.
60 virtual void* data() const = 0;
62 // Forces the memory to be purged, such that any following Lock() will fail.
63 // The object must be unlocked before calling this.
64 virtual void DiscardForTesting() = 0;
66 // Handy method to simplify calling data() with a reinterpret_cast.
67 template<typename T> T* data_as() const {
68 return reinterpret_cast<T*>(data());
71 // Used for dumping the statistics of discardable memory allocated in tracing.
72 // Returns a new MemoryAllocatorDump in the |pmd| with the size of the
73 // discardable memory. The MemoryAllocatorDump created is owned by |pmd|. See
74 // ProcessMemoryDump::CreateAllocatorDump.
75 virtual trace_event::MemoryAllocatorDump* CreateMemoryAllocatorDump(
77 trace_event::ProcessMemoryDump* pmd) const = 0;
80 enum class DiscardableMemoryBacking { kSharedMemory, kMadvFree };
81 BASE_EXPORT DiscardableMemoryBacking GetDiscardableMemoryBacking();
85 #endif // BASE_MEMORY_DISCARDABLE_MEMORY_H_