1 : // Copyright (c) 2006-2008 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_SHARED_MEMORY_H_
6 : #define BASE_SHARED_MEMORY_H_
7 :
8 : #include "build/build_config.h"
9 :
10 : #if defined(OS_POSIX)
11 : #include <sys/types.h>
12 : #include <semaphore.h>
13 : #include "base/file_descriptor_posix.h"
14 : #endif
15 : #include <string>
16 :
17 : #include "base/basictypes.h"
18 : #include "base/process.h"
19 :
20 : namespace base {
21 :
22 : // SharedMemoryHandle is a platform specific type which represents
23 : // the underlying OS handle to a shared memory segment.
24 : #if defined(OS_WIN)
25 : typedef HANDLE SharedMemoryHandle;
26 : typedef HANDLE SharedMemoryLock;
27 : #elif defined(OS_POSIX)
28 : // A SharedMemoryId is sufficient to identify a given shared memory segment on a
29 : // system, but insufficient to map it.
30 : typedef FileDescriptor SharedMemoryHandle;
31 : typedef ino_t SharedMemoryId;
32 : // On POSIX, the lock is implemented as a lockf() on the mapped file,
33 : // so no additional member (or definition of SharedMemoryLock) is
34 : // needed.
35 : #endif
36 :
37 : // Platform abstraction for shared memory. Provides a C++ wrapper
38 : // around the OS primitive for a memory mapped file.
39 : class SharedMemory {
40 : public:
41 : // Create a new SharedMemory object.
42 : SharedMemory();
43 :
44 : // Create a new SharedMemory object from an existing, open
45 : // shared memory file.
46 : SharedMemory(SharedMemoryHandle handle, bool read_only);
47 :
48 : // Create a new SharedMemory object from an existing, open
49 : // shared memory file that was created by a remote process and not shared
50 : // to the current process.
51 : SharedMemory(SharedMemoryHandle handle, bool read_only,
52 : base::ProcessHandle process);
53 :
54 : // Destructor. Will close any open files.
55 : ~SharedMemory();
56 :
57 : // Return true iff the given handle is valid (i.e. not the distingished
58 : // invalid value; NULL for a HANDLE and -1 for a file descriptor)
59 : static bool IsHandleValid(const SharedMemoryHandle& handle);
60 :
61 : // Return invalid handle (see comment above for exact definition).
62 : static SharedMemoryHandle NULLHandle();
63 :
64 : // Creates or opens a shared memory segment based on a name.
65 : // If read_only is true, opens the memory as read-only.
66 : // If open_existing is true, and the shared memory already exists,
67 : // opens the existing shared memory and ignores the size parameter.
68 : // If name is the empty string, use a unique name.
69 : // Returns true on success, false on failure.
70 : bool Create(const std::string& name, bool read_only, bool open_existing,
71 : size_t size);
72 :
73 : // Deletes resources associated with a shared memory segment based on name.
74 : // Not all platforms require this call.
75 : bool Delete(const std::wstring& name);
76 :
77 : // Opens a shared memory segment based on a name.
78 : // If read_only is true, opens for read-only access.
79 : // If name is the empty string, use a unique name.
80 : // Returns true on success, false on failure.
81 : bool Open(const std::wstring& name, bool read_only);
82 :
83 : // Maps the shared memory into the caller's address space.
84 : // Returns true on success, false otherwise. The memory address
85 : // is accessed via the memory() accessor.
86 : bool Map(size_t bytes);
87 :
88 : // Unmaps the shared memory from the caller's address space.
89 : // Returns true if successful; returns false on error or if the
90 : // memory is not mapped.
91 : bool Unmap();
92 :
93 : // Get the size of the opened shared memory backing file.
94 : // Note: This size is only available to the creator of the
95 : // shared memory, and not to those that opened shared memory
96 : // created externally.
97 : // Returns 0 if not opened or unknown.
98 : size_t max_size() const { return max_size_; }
99 :
100 : // Gets a pointer to the opened memory space if it has been
101 : // Mapped via Map(). Returns NULL if it is not mapped.
102 0 : void *memory() const { return memory_; }
103 :
104 : // Get access to the underlying OS handle for this segment.
105 : // Use of this handle for anything other than an opaque
106 : // identifier is not portable.
107 : SharedMemoryHandle handle() const;
108 :
109 : #if defined(OS_POSIX)
110 : // Return a unique identifier for this shared memory segment. Inode numbers
111 : // are technically only unique to a single filesystem. However, we always
112 : // allocate shared memory backing files from the same directory, so will end
113 : // up on the same filesystem.
114 : SharedMemoryId id() const { return inode_; }
115 : #endif
116 :
117 : // Closes the open shared memory segment.
118 : // It is safe to call Close repeatedly.
119 : void Close();
120 :
121 : // Share the shared memory to another process. Attempts
122 : // to create a platform-specific new_handle which can be
123 : // used in a remote process to access the shared memory
124 : // file. new_handle is an ouput parameter to receive
125 : // the handle for use in the remote process.
126 : // Returns true on success, false otherwise.
127 0 : bool ShareToProcess(base::ProcessHandle process,
128 : SharedMemoryHandle* new_handle) {
129 0 : return ShareToProcessCommon(process, new_handle, false);
130 : }
131 :
132 : // Logically equivalent to:
133 : // bool ok = ShareToProcess(process, new_handle);
134 : // Close();
135 : // return ok;
136 : // Note that the memory is unmapped by calling this method, regardless of the
137 : // return value.
138 : bool GiveToProcess(ProcessHandle process,
139 : SharedMemoryHandle* new_handle) {
140 : return ShareToProcessCommon(process, new_handle, true);
141 : }
142 :
143 : // Lock the shared memory.
144 : // This is a cross-process lock which may be recursively
145 : // locked by the same thread.
146 : // TODO(port):
147 : // WARNING: on POSIX the lock only works across processes, not
148 : // across threads. 2 threads in the same process can both grab the
149 : // lock at the same time. There are several solutions for this
150 : // (futex, lockf+anon_semaphore) but none are both clean and common
151 : // across Mac and Linux.
152 : void Lock();
153 :
154 : // Release the shared memory lock.
155 : void Unlock();
156 :
157 : private:
158 : #if defined(OS_POSIX)
159 : bool CreateOrOpen(const std::wstring &name, int posix_flags, size_t size);
160 : bool FilenameForMemoryName(const std::wstring &memname,
161 : std::wstring *filename);
162 : void LockOrUnlockCommon(int function);
163 :
164 : #endif
165 : bool ShareToProcessCommon(ProcessHandle process,
166 : SharedMemoryHandle* new_handle,
167 : bool close_self);
168 :
169 : #if defined(OS_WIN)
170 : std::wstring name_;
171 : HANDLE mapped_file_;
172 : #elif defined(OS_POSIX)
173 : int mapped_file_;
174 : ino_t inode_;
175 : #endif
176 : void* memory_;
177 : bool read_only_;
178 : size_t max_size_;
179 : #if !defined(OS_POSIX)
180 : SharedMemoryLock lock_;
181 : #endif
182 :
183 : DISALLOW_EVIL_CONSTRUCTORS(SharedMemory);
184 : };
185 :
186 : // A helper class that acquires the shared memory lock while
187 : // the SharedMemoryAutoLock is in scope.
188 : class SharedMemoryAutoLock {
189 : public:
190 0 : explicit SharedMemoryAutoLock(SharedMemory* shared_memory)
191 0 : : shared_memory_(shared_memory) {
192 0 : shared_memory_->Lock();
193 0 : }
194 :
195 0 : ~SharedMemoryAutoLock() {
196 0 : shared_memory_->Unlock();
197 0 : }
198 :
199 : private:
200 : SharedMemory* shared_memory_;
201 : DISALLOW_EVIL_CONSTRUCTORS(SharedMemoryAutoLock);
202 : };
203 :
204 : } // namespace base
205 :
206 : #endif // BASE_SHARED_MEMORY_H_
|