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.
5 #ifndef BASE_MEMORY_DISCARDABLE_SHARED_MEMORY_H_
6 #define BASE_MEMORY_DISCARDABLE_SHARED_MEMORY_H_
8 #include "base/base_export.h"
9 #include "base/logging.h"
10 #include "base/memory/shared_memory.h"
11 #include "base/threading/thread_collision_warner.h"
12 #include "base/time/time.h"
20 // Platform abstraction for discardable shared memory.
22 // This class is not thread-safe. Clients are responsible for synchronizing
23 // access to an instance of this class.
24 class BASE_EXPORT DiscardableSharedMemory
{
26 DiscardableSharedMemory();
28 // Create a new DiscardableSharedMemory object from an existing, open shared
29 // memory file. Memory must be locked.
30 explicit DiscardableSharedMemory(SharedMemoryHandle handle
);
32 // Closes any open files.
33 virtual ~DiscardableSharedMemory();
35 // Creates and maps a locked DiscardableSharedMemory object with |size|.
36 // Returns true on success and false on failure.
37 bool CreateAndMap(size_t size
);
39 // Maps the locked discardable memory into the caller's address space.
40 // Returns true on success, false otherwise.
41 bool Map(size_t size
);
43 // The actual size of the mapped memory (may be larger than requested).
44 size_t mapped_size() const { return mapped_size_
; }
46 // Returns a shared memory handle for this DiscardableSharedMemory object.
47 SharedMemoryHandle
handle() const { return shared_memory_
.handle(); }
49 // Locks a range of memory so that it will not be purged by the system.
50 // Returns true if successful and the memory is still resident. Locking can
51 // fail for three reasons; object might have been purged, our last known usage
52 // timestamp might be out of date or memory might already be locked. Last
53 // know usage time is updated to the actual last usage timestamp if memory
54 // is still resident or 0 if not. The range of memory must be unlocked. The
55 // result of trying to lock an already locked range is undefined.
56 // |offset| and |length| must both be a multiple of the page size as returned
58 // Passing 0 for |length| means "everything onward".
59 bool Lock(size_t offset
, size_t length
);
61 // Unlock a previously successfully locked range of memory. The range of
62 // memory must be locked. The result of trying to unlock a not
63 // previously locked range is undefined.
64 // |offset| and |length| must both be a multiple of the page size as returned
66 // Passing 0 for |length| means "everything onward".
67 void Unlock(size_t offset
, size_t length
);
69 // Gets a pointer to the opened discardable memory space. Discardable memory
70 // must have been mapped via Map().
73 // Returns the last know usage time for DiscardableSharedMemory object. This
74 // may be earlier than the "true" usage time when memory has been used by a
75 // different process. Returns NULL time if purged.
76 Time
last_known_usage() const { return last_known_usage_
; }
78 // This returns true and sets |last_known_usage_| to 0 if
79 // DiscardableSharedMemory object was successfully purged. Purging can fail
80 // for two reasons; object might be locked or our last known usage timestamp
81 // might be out of date. Last known usage time is updated to |current_time|
82 // if locked or the actual last usage timestamp if unlocked. It is often
83 // neccesary to call this function twice for the object to successfully be
84 // purged. First call, updates |last_known_usage_|. Second call, successfully
85 // purges the object using the updated |last_known_usage_|.
86 // Note: there is no guarantee that multiple calls to this function will
87 // successfully purge object. DiscardableSharedMemory object might be locked
88 // or another thread/process might be able to lock and unlock it in between
90 bool Purge(Time current_time
);
92 // Purge and release as much memory as possible to the OS.
93 // Note: The amount of memory that can be released to the OS is platform
94 // specific. Best case, all but one page is released. Worst case, nothing
96 bool PurgeAndTruncate(Time current_time
);
98 // Returns true if memory is still resident.
99 bool IsMemoryResident() const;
101 // Closes the open discardable memory segment.
102 // It is safe to call Close repeatedly.
105 // Shares the discardable memory segment to another process. Attempts to
106 // create a platform-specific |new_handle| which can be used in a remote
107 // process to access the discardable memory segment. |new_handle| is an
108 // output parameter to receive the handle for use in the remote process.
109 // Returns true on success, false otherwise.
110 bool ShareToProcess(ProcessHandle process_handle
,
111 SharedMemoryHandle
* new_handle
) {
112 return shared_memory_
.ShareToProcess(process_handle
, new_handle
);
116 // Virtual for tests.
117 virtual Time
Now() const;
119 SharedMemory shared_memory_
;
121 size_t locked_page_count_
;
123 std::set
<size_t> locked_pages_
;
125 // Implementation is not thread-safe but still usable if clients are
126 // synchronized somehow. Use a collision warner to detect incorrect usage.
127 DFAKE_MUTEX(thread_collision_warner_
);
128 Time last_known_usage_
;
130 DISALLOW_COPY_AND_ASSIGN(DiscardableSharedMemory
);
135 #endif // BASE_MEMORY_DISCARDABLE_SHARED_MEMORY_H_