Added llvm into exceptions as we can't add README.chromium into 3rd party repository
[chromium-blink-merge.git] / base / memory / discardable_shared_memory.h
blob59c5d5b54024eef56cd4efbb1a49d3b567548928
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"
14 #if DCHECK_IS_ON()
15 #include <set>
16 #endif
18 namespace base {
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 {
25 public:
26 enum LockResult { SUCCESS, PURGED, FAILED };
28 DiscardableSharedMemory();
30 // Create a new DiscardableSharedMemory object from an existing, open shared
31 // memory file. Memory must be locked.
32 explicit DiscardableSharedMemory(SharedMemoryHandle handle);
34 // Closes any open files.
35 virtual ~DiscardableSharedMemory();
37 // Creates and maps a locked DiscardableSharedMemory object with |size|.
38 // Returns true on success and false on failure.
39 bool CreateAndMap(size_t size);
41 // Maps the locked discardable memory into the caller's address space.
42 // Returns true on success, false otherwise.
43 bool Map(size_t size);
45 // The actual size of the mapped memory (may be larger than requested).
46 size_t mapped_size() const { return mapped_size_; }
48 // Returns a shared memory handle for this DiscardableSharedMemory object.
49 SharedMemoryHandle handle() const { return shared_memory_.handle(); }
51 // Locks a range of memory so that it will not be purged by the system.
52 // The range of memory must be unlocked. The result of trying to lock an
53 // already locked range is undefined. |offset| and |length| must both be
54 // a multiple of the page size as returned by GetPageSize().
55 // Passing 0 for |length| means "everything onward".
56 // Returns SUCCESS if range was successfully locked and the memory is still
57 // resident, PURGED if range was successfully locked but has been purged
58 // since last time it was locked and FAILED if range could not be locked.
59 // Locking can fail for two reasons; object might have been purged, our
60 // last known usage timestamp might be out of date. Last known usage time
61 // is updated to the actual last usage timestamp if memory is still resident
62 // or 0 if not.
63 LockResult Lock(size_t offset, size_t length);
65 // Unlock a previously successfully locked range of memory. The range of
66 // memory must be locked. The result of trying to unlock a not
67 // previously locked range is undefined.
68 // |offset| and |length| must both be a multiple of the page size as returned
69 // by GetPageSize().
70 // Passing 0 for |length| means "everything onward".
71 void Unlock(size_t offset, size_t length);
73 // Gets a pointer to the opened discardable memory space. Discardable memory
74 // must have been mapped via Map().
75 void* memory() const;
77 // Returns the last know usage time for DiscardableSharedMemory object. This
78 // may be earlier than the "true" usage time when memory has been used by a
79 // different process. Returns NULL time if purged.
80 Time last_known_usage() const { return last_known_usage_; }
82 // This returns true and sets |last_known_usage_| to 0 if
83 // DiscardableSharedMemory object was successfully purged. Purging can fail
84 // for two reasons; object might be locked or our last known usage timestamp
85 // might be out of date. Last known usage time is updated to |current_time|
86 // if locked or the actual last usage timestamp if unlocked. It is often
87 // neccesary to call this function twice for the object to successfully be
88 // purged. First call, updates |last_known_usage_|. Second call, successfully
89 // purges the object using the updated |last_known_usage_|.
90 // Note: there is no guarantee that multiple calls to this function will
91 // successfully purge object. DiscardableSharedMemory object might be locked
92 // or another thread/process might be able to lock and unlock it in between
93 // each call.
94 bool Purge(Time current_time);
96 // Purge and release as much memory as possible to the OS.
97 // Note: The amount of memory that can be released to the OS is platform
98 // specific. Best case, all but one page is released. Worst case, nothing
99 // is released.
100 bool PurgeAndTruncate(Time current_time);
102 // Returns true if memory is still resident.
103 bool IsMemoryResident() const;
105 // Closes the open discardable memory segment.
106 // It is safe to call Close repeatedly.
107 void Close();
109 // Shares the discardable memory segment to another process. Attempts to
110 // create a platform-specific |new_handle| which can be used in a remote
111 // process to access the discardable memory segment. |new_handle| is an
112 // output parameter to receive the handle for use in the remote process.
113 // Returns true on success, false otherwise.
114 bool ShareToProcess(ProcessHandle process_handle,
115 SharedMemoryHandle* new_handle) {
116 return shared_memory_.ShareToProcess(process_handle, new_handle);
119 private:
120 // Virtual for tests.
121 virtual Time Now() const;
123 SharedMemory shared_memory_;
124 size_t mapped_size_;
125 size_t locked_page_count_;
126 #if DCHECK_IS_ON()
127 std::set<size_t> locked_pages_;
128 #endif
129 // Implementation is not thread-safe but still usable if clients are
130 // synchronized somehow. Use a collision warner to detect incorrect usage.
131 DFAKE_MUTEX(thread_collision_warner_);
132 Time last_known_usage_;
134 DISALLOW_COPY_AND_ASSIGN(DiscardableSharedMemory);
137 } // namespace base
139 #endif // BASE_MEMORY_DISCARDABLE_SHARED_MEMORY_H_