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