michael@0: // Copyright (c) 2006-2008 The Chromium Authors. All rights reserved.
michael@0: // Use of this source code is governed by a BSD-style license that can be
michael@0: // found in the LICENSE file.
michael@0: 
michael@0: #ifndef BASE_SHARED_MEMORY_H_
michael@0: #define BASE_SHARED_MEMORY_H_
michael@0: 
michael@0: #include "build/build_config.h"
michael@0: 
michael@0: #if defined(OS_POSIX)
michael@0: #include <sys/types.h>
michael@0: #include <semaphore.h>
michael@0: #include "base/file_descriptor_posix.h"
michael@0: #endif
michael@0: #include <string>
michael@0: 
michael@0: #include "base/basictypes.h"
michael@0: #include "base/process.h"
michael@0: 
michael@0: namespace base {
michael@0: 
michael@0: // SharedMemoryHandle is a platform specific type which represents
michael@0: // the underlying OS handle to a shared memory segment.
michael@0: #if defined(OS_WIN)
michael@0: typedef HANDLE SharedMemoryHandle;
michael@0: typedef HANDLE SharedMemoryLock;
michael@0: #elif defined(OS_POSIX)
michael@0: // A SharedMemoryId is sufficient to identify a given shared memory segment on a
michael@0: // system, but insufficient to map it.
michael@0: typedef FileDescriptor SharedMemoryHandle;
michael@0: typedef ino_t SharedMemoryId;
michael@0: // On POSIX, the lock is implemented as a lockf() on the mapped file,
michael@0: // so no additional member (or definition of SharedMemoryLock) is
michael@0: // needed.
michael@0: #endif
michael@0: 
michael@0: // Platform abstraction for shared memory.  Provides a C++ wrapper
michael@0: // around the OS primitive for a memory mapped file.
michael@0: class SharedMemory {
michael@0:  public:
michael@0:   // Create a new SharedMemory object.
michael@0:   SharedMemory();
michael@0: 
michael@0:   // Create a new SharedMemory object from an existing, open
michael@0:   // shared memory file.
michael@0:   SharedMemory(SharedMemoryHandle handle, bool read_only);
michael@0: 
michael@0:   // Create a new SharedMemory object from an existing, open
michael@0:   // shared memory file that was created by a remote process and not shared
michael@0:   // to the current process.
michael@0:   SharedMemory(SharedMemoryHandle handle, bool read_only,
michael@0:       base::ProcessHandle process);
michael@0: 
michael@0:   // Destructor.  Will close any open files.
michael@0:   ~SharedMemory();
michael@0: 
michael@0:   // Return true iff the given handle is valid (i.e. not the distingished
michael@0:   // invalid value; NULL for a HANDLE and -1 for a file descriptor)
michael@0:   static bool IsHandleValid(const SharedMemoryHandle& handle);
michael@0: 
michael@0:   // Return invalid handle (see comment above for exact definition).
michael@0:   static SharedMemoryHandle NULLHandle();
michael@0: 
michael@0:   // Creates or opens a shared memory segment based on a name.
michael@0:   // If read_only is true, opens the memory as read-only.
michael@0:   // If open_existing is true, and the shared memory already exists,
michael@0:   // opens the existing shared memory and ignores the size parameter.
michael@0:   // If name is the empty string, use a unique name.
michael@0:   // Returns true on success, false on failure.
michael@0:   bool Create(const std::string& name, bool read_only, bool open_existing,
michael@0:               size_t size);
michael@0: 
michael@0:   // Deletes resources associated with a shared memory segment based on name.
michael@0:   // Not all platforms require this call.
michael@0:   bool Delete(const std::wstring& name);
michael@0: 
michael@0:   // Opens a shared memory segment based on a name.
michael@0:   // If read_only is true, opens for read-only access.
michael@0:   // If name is the empty string, use a unique name.
michael@0:   // Returns true on success, false on failure.
michael@0:   bool Open(const std::wstring& name, bool read_only);
michael@0: 
michael@0:   // Maps the shared memory into the caller's address space.
michael@0:   // Returns true on success, false otherwise.  The memory address
michael@0:   // is accessed via the memory() accessor.
michael@0:   bool Map(size_t bytes);
michael@0: 
michael@0:   // Unmaps the shared memory from the caller's address space.
michael@0:   // Returns true if successful; returns false on error or if the
michael@0:   // memory is not mapped.
michael@0:   bool Unmap();
michael@0: 
michael@0:   // Get the size of the opened shared memory backing file.
michael@0:   // Note:  This size is only available to the creator of the
michael@0:   // shared memory, and not to those that opened shared memory
michael@0:   // created externally.
michael@0:   // Returns 0 if not opened or unknown.
michael@0:   size_t max_size() const { return max_size_; }
michael@0: 
michael@0:   // Gets a pointer to the opened memory space if it has been
michael@0:   // Mapped via Map().  Returns NULL if it is not mapped.
michael@0:   void *memory() const { return memory_; }
michael@0: 
michael@0:   // Get access to the underlying OS handle for this segment.
michael@0:   // Use of this handle for anything other than an opaque
michael@0:   // identifier is not portable.
michael@0:   SharedMemoryHandle handle() const;
michael@0: 
michael@0: #if defined(OS_POSIX)
michael@0:   // Return a unique identifier for this shared memory segment. Inode numbers
michael@0:   // are technically only unique to a single filesystem. However, we always
michael@0:   // allocate shared memory backing files from the same directory, so will end
michael@0:   // up on the same filesystem.
michael@0:   SharedMemoryId id() const { return inode_; }
michael@0: #endif
michael@0: 
michael@0:   // Closes the open shared memory segment.
michael@0:   // It is safe to call Close repeatedly.
michael@0:   void Close();
michael@0: 
michael@0:   // Share the shared memory to another process.  Attempts
michael@0:   // to create a platform-specific new_handle which can be
michael@0:   // used in a remote process to access the shared memory
michael@0:   // file.  new_handle is an ouput parameter to receive
michael@0:   // the handle for use in the remote process.
michael@0:   // Returns true on success, false otherwise.
michael@0:   bool ShareToProcess(base::ProcessHandle process,
michael@0:                       SharedMemoryHandle* new_handle) {
michael@0:     return ShareToProcessCommon(process, new_handle, false);
michael@0:   }
michael@0: 
michael@0:   // Logically equivalent to:
michael@0:   //   bool ok = ShareToProcess(process, new_handle);
michael@0:   //   Close();
michael@0:   //   return ok;
michael@0:   // Note that the memory is unmapped by calling this method, regardless of the
michael@0:   // return value.
michael@0:   bool GiveToProcess(ProcessHandle process,
michael@0:                      SharedMemoryHandle* new_handle) {
michael@0:     return ShareToProcessCommon(process, new_handle, true);
michael@0:   }
michael@0: 
michael@0:   // Lock the shared memory.
michael@0:   // This is a cross-process lock which may be recursively
michael@0:   // locked by the same thread.
michael@0:   // TODO(port):
michael@0:   // WARNING: on POSIX the lock only works across processes, not
michael@0:   // across threads.  2 threads in the same process can both grab the
michael@0:   // lock at the same time.  There are several solutions for this
michael@0:   // (futex, lockf+anon_semaphore) but none are both clean and common
michael@0:   // across Mac and Linux.
michael@0:   void Lock();
michael@0: 
michael@0:   // Release the shared memory lock.
michael@0:   void Unlock();
michael@0: 
michael@0:  private:
michael@0: #if defined(OS_POSIX)
michael@0:   bool CreateOrOpen(const std::wstring &name, int posix_flags, size_t size);
michael@0:   bool FilenameForMemoryName(const std::wstring &memname,
michael@0:                              std::wstring *filename);
michael@0:   void LockOrUnlockCommon(int function);
michael@0: 
michael@0: #endif
michael@0:   bool ShareToProcessCommon(ProcessHandle process,
michael@0:                             SharedMemoryHandle* new_handle,
michael@0:                             bool close_self);
michael@0: 
michael@0: #if defined(OS_WIN)
michael@0:   std::wstring       name_;
michael@0:   HANDLE             mapped_file_;
michael@0: #elif defined(OS_POSIX)
michael@0:   int                mapped_file_;
michael@0:   ino_t              inode_;
michael@0: #endif
michael@0:   void*              memory_;
michael@0:   bool               read_only_;
michael@0:   size_t             max_size_;
michael@0: #if !defined(OS_POSIX)
michael@0:   SharedMemoryLock   lock_;
michael@0: #endif
michael@0: 
michael@0:   DISALLOW_EVIL_CONSTRUCTORS(SharedMemory);
michael@0: };
michael@0: 
michael@0: // A helper class that acquires the shared memory lock while
michael@0: // the SharedMemoryAutoLock is in scope.
michael@0: class SharedMemoryAutoLock {
michael@0:  public:
michael@0:   explicit SharedMemoryAutoLock(SharedMemory* shared_memory)
michael@0:       : shared_memory_(shared_memory) {
michael@0:     shared_memory_->Lock();
michael@0:   }
michael@0: 
michael@0:   ~SharedMemoryAutoLock() {
michael@0:     shared_memory_->Unlock();
michael@0:   }
michael@0: 
michael@0:  private:
michael@0:   SharedMemory* shared_memory_;
michael@0:   DISALLOW_EVIL_CONSTRUCTORS(SharedMemoryAutoLock);
michael@0: };
michael@0: 
michael@0: }  // namespace base
michael@0: 
michael@0: #endif  // BASE_SHARED_MEMORY_H_