base/memory/discardable_memory.h

   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/basictypes.h"
  10 #include "base/compiler_specific.h"
  11
  12 namespace base {
  13
  14 namespace trace_event {
  15 class MemoryAllocatorDump;
  16 class ProcessMemoryDump;
  17 }
  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   // discarded 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   // Handy method to simplify calling data() with a reinterpret_cast.
  64   template<typename T> T* data_as() const {
  65     return reinterpret_cast<T*>(data());
  66   }
  67
  68   // Used for dumping the statistics of discardable memory allocated in tracing.
  69   // Returns a new MemoryAllocatorDump in the |pmd| with the size of the
  70   // discardable memory. The MemoryAllocatorDump created is owned by |pmd|. See
  71   // ProcessMemoryDump::CreateAllocatorDump.
  72   virtual trace_event::MemoryAllocatorDump* CreateMemoryAllocatorDump(
  73       const char* name,
  74       trace_event::ProcessMemoryDump* pmd) const = 0;
  75 };
  76
  77 }  // namespace base
  78
  79 #endif  // BASE_MEMORY_DISCARDABLE_MEMORY_H_