ipc/glue/Shmem.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef mozilla_ipc_Shmem_h
   8 #define mozilla_ipc_Shmem_h
   9
  10 #include "mozilla/Attributes.h"
  11
  12 #include "base/basictypes.h"
  13 #include "base/process.h"
  14
  15 #include "nscore.h"
  16 #include "nsDebug.h"
  17
  18 #include "mozilla/ipc/SharedMemory.h"
  19 #include "mozilla/Range.h"
  20 #include "mozilla/UniquePtr.h"
  21
  22 /**
  23  * |Shmem| is one agent in the IPDL shared memory scheme.  The way it
  24     works is essentially
  25  *
  26  *  (1) C++ code calls, say, |parentActor->AllocShmem(size)|
  27
  28  *  (2) IPDL-generated code creates a |mozilla::ipc::SharedMemory|
  29  *  wrapping the bare OS shmem primitives.  The code then adds the new
  30  *  SharedMemory to the set of shmem segments being managed by IPDL.
  31  *
  32  *  (3) IPDL-generated code "shares" the new SharedMemory to the child
  33  *  process, and then sends a special asynchronous IPC message to the
  34  *  child notifying it of the creation of the segment.  (What this
  35  *  means is OS specific.)
  36  *
  37  *  (4a) The child receives the special IPC message, and using the
  38  *  |SharedMemory{Basic}::Handle| it was passed, creates a
  39  *  |mozilla::ipc::SharedMemory| in the child
  40  *  process.
  41  *
  42  *  (4b) After sending the "shmem-created" IPC message, IPDL-generated
  43  *  code in the parent returns a |mozilla::ipc::Shmem| back to the C++
  44  *  caller of |parentActor->AllocShmem()|.  The |Shmem| is a "weak
  45  *  reference" to the underlying |SharedMemory|, which is managed by
  46  *  IPDL-generated code.  C++ consumers of |Shmem| can't get at the
  47  *  underlying |SharedMemory|.
  48  *
  49  * If parent code wants to give access rights to the Shmem to the
  50  * child, it does so by sending its |Shmem| to the child, in an IPDL
  51  * message.  The parent's |Shmem| then "dies", i.e. becomes
  52  * inaccessible.  This process could be compared to passing a
  53  * "shmem-access baton" between parent and child.
  54  */
  55
  56 namespace mozilla {
  57 namespace layers {
  58 class ShadowLayerForwarder;
  59 }  // namespace layers
  60
  61 namespace ipc {
  62
  63 class IProtocol;
  64 class IToplevelProtocol;
  65
  66 template <typename P>
  67 struct IPDLParamTraits;
  68
  69 class Shmem final {
  70   friend struct IPDLParamTraits<mozilla::ipc::Shmem>;
  71   friend class mozilla::ipc::IProtocol;
  72   friend class mozilla::ipc::IToplevelProtocol;
  73 #ifdef DEBUG
  74   // For ShadowLayerForwarder::CheckSurfaceDescriptor
  75   friend class mozilla::layers::ShadowLayerForwarder;
  76 #endif
  77
  78  public:
  79   typedef int32_t id_t;
  80   // Low-level wrapper around platform shmem primitives.
  81   typedef mozilla::ipc::SharedMemory SharedMemory;
  82
  83   Shmem() : mSegment(nullptr), mData(nullptr), mSize(0), mId(0) {}
  84
  85   Shmem(const Shmem& aOther) = default;
  86
  87   ~Shmem() {
  88     // Shmem only holds a "weak ref" to the actual segment, which is
  89     // owned by IPDL. So there's nothing interesting to be done here
  90     forget();
  91   }
  92
  93   Shmem& operator=(const Shmem& aRhs) = default;
  94
  95   bool operator==(const Shmem& aRhs) const { return mSegment == aRhs.mSegment; }
  96
  97   // Returns whether this Shmem is writable by you, and thus whether you can
  98   // transfer writability to another actor.
  99   bool IsWritable() const { return mSegment != nullptr; }
 100
 101   // Returns whether this Shmem is readable by you, and thus whether you can
 102   // transfer readability to another actor.
 103   bool IsReadable() const { return mSegment != nullptr; }
 104
 105   // Return a pointer to the user-visible data segment.
 106   template <typename T>
 107   T* get() const {
 108     AssertInvariants();
 109     AssertAligned<T>();
 110
 111     return reinterpret_cast<T*>(mData);
 112   }
 113
 114   // Return the size of the segment as requested when this shmem
 115   // segment was allocated, in units of T.  The underlying mapping may
 116   // actually be larger because of page alignment and private data,
 117   // but this isn't exposed to clients.
 118   template <typename T>
 119   size_t Size() const {
 120     AssertInvariants();
 121     AssertAligned<T>();
 122
 123     return mSize / sizeof(T);
 124   }
 125
 126   template <typename T>
 127   Range<T> Range() const {
 128     return {get<T>(), Size<T>()};
 129   }
 130
 131  private:
 132   // These shouldn't be used directly, use the IPDL interface instead.
 133
 134   Shmem(SharedMemory* aSegment, id_t aId);
 135
 136   id_t Id() const { return mId; }
 137
 138   SharedMemory* Segment() const { return mSegment; }
 139
 140 #ifndef DEBUG
 141   void RevokeRights() {}
 142 #else
 143   void RevokeRights();
 144 #endif
 145
 146   void forget() {
 147     mSegment = nullptr;
 148     mData = nullptr;
 149     mSize = 0;
 150     mId = 0;
 151   }
 152
 153   static already_AddRefed<Shmem::SharedMemory> Alloc(size_t aNBytes,
 154                                                      bool aUnsafe,
 155                                                      bool aProtect = false);
 156
 157   // Prepare this to be shared with another process. Return an IPC message that
 158   // contains enough information for the other process to map this segment in
 159   // OpenExisting() below.  Return a new message if successful (owned by the
 160   // caller), nullptr if not.
 161   UniquePtr<IPC::Message> MkCreatedMessage(int32_t routingId);
 162
 163   // Stop sharing this with another process. Return an IPC message that
 164   // contains enough information for the other process to unmap this
 165   // segment.  Return a new message if successful (owned by the
 166   // caller), nullptr if not.
 167   UniquePtr<IPC::Message> MkDestroyedMessage(int32_t routingId);
 168
 169   // Return a SharedMemory instance in this process using the descriptor shared
 170   // to us by the process that created the underlying OS shmem resource.  The
 171   // contents of the descriptor depend on the type of SharedMemory that was
 172   // passed to us.
 173   static already_AddRefed<SharedMemory> OpenExisting(
 174       const IPC::Message& aDescriptor, id_t* aId, bool aProtect = false);
 175
 176   static void Dealloc(SharedMemory* aSegment);
 177
 178   template <typename T>
 179   void AssertAligned() const {
 180     if (0 != (mSize % sizeof(T))) MOZ_CRASH("shmem is not T-aligned");
 181   }
 182
 183 #if !defined(DEBUG)
 184   void AssertInvariants() const {}
 185
 186   static uint32_t* PtrToSize(SharedMemory* aSegment) {
 187     char* endOfSegment =
 188         reinterpret_cast<char*>(aSegment->memory()) + aSegment->Size();
 189     return reinterpret_cast<uint32_t*>(endOfSegment - sizeof(uint32_t));
 190   }
 191
 192 #else
 193   void AssertInvariants() const;
 194 #endif
 195
 196   RefPtr<SharedMemory> mSegment;
 197   void* mData;
 198   size_t mSize;
 199   id_t mId;
 200 };
 201
 202 }  // namespace ipc
 203 }  // namespace mozilla
 204
 205 #endif  // ifndef mozilla_ipc_Shmem_h