base/shared_memory.h

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