base/memory/discardable_shared_memory.h

   1 // Copyright 2014 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_SHARED_MEMORY_H_
   6 #define BASE_MEMORY_DISCARDABLE_SHARED_MEMORY_H_
   7
   8 #include "base/base_export.h"
   9 #include "base/memory/shared_memory.h"
  10 #include "base/time/time.h"
  11
  12 namespace base {
  13
  14 // Platform abstraction for discardable shared memory.
  15 class BASE_EXPORT DiscardableSharedMemory {
  16  public:
  17   DiscardableSharedMemory();
  18
  19   // Create a new DiscardableSharedMemory object from an existing, open shared
  20   // memory file.
  21   explicit DiscardableSharedMemory(SharedMemoryHandle handle);
  22
  23   // Closes any open files.
  24   virtual ~DiscardableSharedMemory();
  25
  26   // Creates and maps a locked DiscardableSharedMemory object with |size|.
  27   // Returns true on success and false on failure.
  28   bool CreateAndMap(size_t size);
  29
  30   // Maps the discardable memory into the caller's address space.
  31   // Returns true on success, false otherwise.
  32   bool Map(size_t size);
  33
  34   // The actual size of the mapped memory (may be larger than requested).
  35   size_t mapped_size() const { return shared_memory_.mapped_size(); }
  36
  37   // Returns a shared memory handle for this DiscardableSharedMemory object.
  38   SharedMemoryHandle handle() const { return shared_memory_.handle(); }
  39
  40   // Locks the memory so that it will not be purged by the system. Returns
  41   // true if successful and the memory is still resident. Locking can fail
  42   // for three reasons; object might have been purged, our last known usage
  43   // timestamp might be out of date or memory might already be locked. Last
  44   // know usage time is updated to the actual last usage timestamp if memory
  45   // is still resident or 0 if not.
  46   bool Lock();
  47
  48   // Unlock previously successfully locked memory.
  49   void Unlock();
  50
  51   // Gets a pointer to the opened discardable memory space. Discardable memory
  52   // must have been mapped via Map().
  53   void* memory() const;
  54
  55   // Returns the last know usage time for DiscardableSharedMemory object. This
  56   // may be earlier than the "true" usage time when memory has been used by a
  57   // different process. Returns NULL time if purged.
  58   Time last_known_usage() const { return last_known_usage_; }
  59
  60   // This returns true and sets |last_known_usage_| to 0 if
  61   // DiscardableSharedMemory object was successfully purged. Purging can fail
  62   // for two reasons; object might be locked or our last known usage timestamp
  63   // might be out of date. Last known usage time is updated to |current_time|
  64   // if locked or the actual last usage timestamp if unlocked. It is often
  65   // neccesary to call this function twice for the object to successfully be
  66   // purged. First call, updates |last_known_usage_|. Second call, successfully
  67   // purges the object using the updated |last_known_usage_|.
  68   // Note: there is no guarantee that multiple calls to this function will
  69   // successfully purge object. DiscardableSharedMemory object might be locked
  70   // or another thread/process might be able to lock and unlock it in between
  71   // each call.
  72   bool Purge(Time current_time);
  73
  74   // Purge and release as much memory as possible to the OS.
  75   // Note: The amount of memory that can be released to the OS is platform
  76   // specific. Best case, all but one page is released. Worst case, nothing
  77   // is released.
  78   bool PurgeAndTruncate(Time current_time);
  79
  80   // Returns true if memory is still resident.
  81   bool IsMemoryResident() const;
  82
  83   // Closes the open discardable memory segment.
  84   // It is safe to call Close repeatedly.
  85   void Close();
  86
  87   // Shares the discardable memory segment to another process. Attempts to
  88   // create a platform-specific |new_handle| which can be used in a remote
  89   // process to access the discardable memory segment. |new_handle| is an
  90   // output parameter to receive the handle for use in the remote process.
  91   // Returns true on success, false otherwise.
  92   bool ShareToProcess(ProcessHandle process_handle,
  93                       SharedMemoryHandle* new_handle) {
  94     return shared_memory_.ShareToProcess(process_handle, new_handle);
  95   }
  96
  97  private:
  98   // Virtual for tests.
  99   virtual Time Now() const;
 100
 101   SharedMemory shared_memory_;
 102   Time last_known_usage_;
 103
 104   DISALLOW_COPY_AND_ASSIGN(DiscardableSharedMemory);
 105 };
 106
 107 }  // namespace base
 108
 109 #endif  // BASE_MEMORY_DISCARDABLE_SHARED_MEMORY_H_