discardable_memory.h 3.4 KB

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