base/shared_memory.h

   1 // Copyright (c) 2012 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 #include <string>
  11
  12 #if defined(OS_POSIX)
  13 #include <stdio.h>
  14 #include <sys/types.h>
  15 #include <semaphore.h>
  16 #endif
  17
  18 #include "base/base_export.h"
  19 #include "base/basictypes.h"
  20 #include "base/process.h"
  21
  22 #if defined(OS_POSIX)
  23 #include "base/file_descriptor_posix.h"
  24 #endif
  25
  26 namespace base {
  27
  28 class FilePath;
  29
  30 // SharedMemoryHandle is a platform specific type which represents
  31 // the underlying OS handle to a shared memory segment.
  32 #if defined(OS_WIN)
  33 typedef HANDLE SharedMemoryHandle;
  34 typedef HANDLE SharedMemoryLock;
  35 #elif defined(OS_POSIX)
  36 // A SharedMemoryId is sufficient to identify a given shared memory segment on a
  37 // system, but insufficient to map it.
  38 typedef FileDescriptor SharedMemoryHandle;
  39 typedef ino_t SharedMemoryId;
  40 // On POSIX, the lock is implemented as a lockf() on the mapped file,
  41 // so no additional member (or definition of SharedMemoryLock) is
  42 // needed.
  43 #endif
  44
  45 // Options for creating a shared memory object.
  46 struct SharedMemoryCreateOptions {
  47   SharedMemoryCreateOptions() : name(NULL), size(0), open_existing(false),
  48                                 executable(false) {}
  49
  50   // If NULL, the object is anonymous.  This pointer is owned by the caller
  51   // and must live through the call to Create().
  52   const std::string* name;
  53
  54   // Size of the shared memory object to be created.
  55   // When opening an existing object, this has no effect.
  56   size_t size;
  57
  58   // If true, and the shared memory already exists, Create() will open the
  59   // existing shared memory and ignore the size parameter.  If false,
  60   // shared memory must not exist.  This flag is meaningless unless name is
  61   // non-NULL.
  62   bool open_existing;
  63
  64   // If true, mappings might need to be made executable later.
  65   bool executable;
  66 };
  67
  68 // Platform abstraction for shared memory.  Provides a C++ wrapper
  69 // around the OS primitive for a memory mapped file.
  70 class BASE_EXPORT SharedMemory {
  71  public:
  72   SharedMemory();
  73
  74 #if defined(OS_WIN)
  75   // Similar to the default constructor, except that this allows for
  76   // calling Lock() to acquire the named mutex before either Create or Open
  77   // are called on Windows.
  78   explicit SharedMemory(const std::wstring& name);
  79 #endif
  80
  81   // Create a new SharedMemory object from an existing, open
  82   // shared memory file.
  83   SharedMemory(SharedMemoryHandle handle, bool read_only);
  84
  85   // Create a new SharedMemory object from an existing, open
  86   // shared memory file that was created by a remote process and not shared
  87   // to the current process.
  88   SharedMemory(SharedMemoryHandle handle, bool read_only,
  89                ProcessHandle process);
  90
  91   // Closes any open files.
  92   ~SharedMemory();
  93
  94   // Return true iff the given handle is valid (i.e. not the distingished
  95   // invalid value; NULL for a HANDLE and -1 for a file descriptor)
  96   static bool IsHandleValid(const SharedMemoryHandle& handle);
  97
  98   // Returns invalid handle (see comment above for exact definition).
  99   static SharedMemoryHandle NULLHandle();
 100
 101   // Closes a shared memory handle.
 102   static void CloseHandle(const SharedMemoryHandle& handle);
 103
 104   // Creates a shared memory object as described by the options struct.
 105   // Returns true on success and false on failure.
 106   bool Create(const SharedMemoryCreateOptions& options);
 107
 108   // Creates and maps an anonymous shared memory segment of size size.
 109   // Returns true on success and false on failure.
 110   bool CreateAndMapAnonymous(size_t size);
 111
 112   // Creates an anonymous shared memory segment of size size.
 113   // Returns true on success and false on failure.
 114   bool CreateAnonymous(size_t size) {
 115     SharedMemoryCreateOptions options;
 116     options.size = size;
 117     return Create(options);
 118   }
 119
 120   // Creates or opens a shared memory segment based on a name.
 121   // If open_existing is true, and the shared memory already exists,
 122   // opens the existing shared memory and ignores the size parameter.
 123   // If open_existing is false, shared memory must not exist.
 124   // size is the size of the block to be created.
 125   // Returns true on success, false on failure.
 126   bool CreateNamed(const std::string& name, bool open_existing, size_t size) {
 127     SharedMemoryCreateOptions options;
 128     options.name = &name;
 129     options.open_existing = open_existing;
 130     options.size = size;
 131     return Create(options);
 132   }
 133
 134   // Deletes resources associated with a shared memory segment based on name.
 135   // Not all platforms require this call.
 136   bool Delete(const std::string& name);
 137
 138   // Opens a shared memory segment based on a name.
 139   // If read_only is true, opens for read-only access.
 140   // Returns true on success, false on failure.
 141   bool Open(const std::string& name, bool read_only);
 142
 143   // Maps the shared memory into the caller's address space.
 144   // Returns true on success, false otherwise.  The memory address
 145   // is accessed via the memory() accessor.  The mapped address is guaranteed to
 146   // have an alignment of at least MAP_MINIMUM_ALIGNMENT.
 147   bool Map(size_t bytes) {
 148     return MapAt(0, bytes);
 149   }
 150
 151   // Same as above, but with |offset| to specify from begining of the shared
 152   // memory block to map.
 153   // |offset| must be alignent to value of |SysInfo::VMAllocationGranularity()|.
 154   bool MapAt(off_t offset, size_t bytes);
 155   enum { MAP_MINIMUM_ALIGNMENT = 32 };
 156
 157   // Unmaps the shared memory from the caller's address space.
 158   // Returns true if successful; returns false on error or if the
 159   // memory is not mapped.
 160   bool Unmap();
 161
 162   // Get the size of the shared memory backing file.
 163   // Note:  This size is only available to the creator of the
 164   // shared memory, and not to those that opened shared memory
 165   // created externally.
 166   // Returns 0 if not created or unknown.
 167   // Deprecated method, please keep track of the size yourself if you created
 168   // it.
 169   // http://crbug.com/60821
 170   size_t created_size() const { return created_size_; }
 171
 172   // Gets a pointer to the opened memory space if it has been
 173   // Mapped via Map().  Returns NULL if it is not mapped.
 174   void *memory() const { return memory_; }
 175
 176   // Returns the underlying OS handle for this segment.
 177   // Use of this handle for anything other than an opaque
 178   // identifier is not portable.
 179   SharedMemoryHandle handle() const;
 180
 181 #if defined(OS_POSIX) && !defined(OS_NACL)
 182   // Returns a unique identifier for this shared memory segment. Inode numbers
 183   // are technically only unique to a single filesystem. However, we always
 184   // allocate shared memory backing files from the same directory, so will end
 185   // up on the same filesystem.
 186   SharedMemoryId id() const { return inode_; }
 187 #endif
 188
 189   // Closes the open shared memory segment.
 190   // It is safe to call Close repeatedly.
 191   void Close();
 192
 193   // Shares the shared memory to another process.  Attempts
 194   // to create a platform-specific new_handle which can be
 195   // used in a remote process to access the shared memory
 196   // file.  new_handle is an ouput parameter to receive
 197   // the handle for use in the remote process.
 198   // Returns true on success, false otherwise.
 199   bool ShareToProcess(ProcessHandle process,
 200                       SharedMemoryHandle* new_handle) {
 201     return ShareToProcessCommon(process, new_handle, false);
 202   }
 203
 204   // Logically equivalent to:
 205   //   bool ok = ShareToProcess(process, new_handle);
 206   //   Close();
 207   //   return ok;
 208   // Note that the memory is unmapped by calling this method, regardless of the
 209   // return value.
 210   bool GiveToProcess(ProcessHandle process,
 211                      SharedMemoryHandle* new_handle) {
 212     return ShareToProcessCommon(process, new_handle, true);
 213   }
 214
 215   // Locks the shared memory.
 216   //
 217   // WARNING: on POSIX the memory locking primitive only works across
 218   // processes, not across threads.  The Lock method is not currently
 219   // used in inner loops, so we protect against multiple threads in a
 220   // critical section using a class global lock.
 221   void Lock();
 222
 223 #if defined(OS_WIN)
 224   // A Lock() implementation with a timeout that also allows setting
 225   // security attributes on the mutex. sec_attr may be NULL.
 226   // Returns true if the Lock() has been acquired, false if the timeout was
 227   // reached.
 228   bool Lock(uint32 timeout_ms, SECURITY_ATTRIBUTES* sec_attr);
 229 #endif
 230
 231   // Releases the shared memory lock.
 232   void Unlock();
 233
 234  private:
 235 #if defined(OS_POSIX) && !defined(OS_NACL)
 236   bool PrepareMapFile(FILE *fp);
 237   bool FilePathForMemoryName(const std::string& mem_name, FilePath* path);
 238   void LockOrUnlockCommon(int function);
 239 #endif
 240   bool ShareToProcessCommon(ProcessHandle process,
 241                             SharedMemoryHandle* new_handle,
 242                             bool close_self);
 243
 244 #if defined(OS_WIN)
 245   std::wstring       name_;
 246   HANDLE             mapped_file_;
 247 #elif defined(OS_POSIX)
 248   int                mapped_file_;
 249   size_t             mapped_size_;
 250   ino_t              inode_;
 251 #endif
 252   void*              memory_;
 253   bool               read_only_;
 254   size_t             created_size_;
 255 #if !defined(OS_POSIX)
 256   SharedMemoryLock   lock_;
 257 #endif
 258
 259   DISALLOW_COPY_AND_ASSIGN(SharedMemory);
 260 };
 261
 262 // A helper class that acquires the shared memory lock while
 263 // the SharedMemoryAutoLock is in scope.
 264 class SharedMemoryAutoLock {
 265  public:
 266   explicit SharedMemoryAutoLock(SharedMemory* shared_memory)
 267       : shared_memory_(shared_memory) {
 268     shared_memory_->Lock();
 269   }
 270
 271   ~SharedMemoryAutoLock() {
 272     shared_memory_->Unlock();
 273   }
 274
 275  private:
 276   SharedMemory* shared_memory_;
 277   DISALLOW_COPY_AND_ASSIGN(SharedMemoryAutoLock);
 278 };
 279
 280 }  // namespace base
 281
 282 #endif  // BASE_SHARED_MEMORY_H_