ipc/glue/Shmem.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * vim: sw=2 ts=8 et :
   3  */
   4 /* This Source Code Form is subject to the terms of the Mozilla Public
   5  * License, v. 2.0. If a copy of the MPL was not distributed with this
   6  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   7
   8 #ifndef mozilla_ipc_Shmem_h
   9 #define mozilla_ipc_Shmem_h
  10
  11 #include "mozilla/Attributes.h"
  12
  13 #include "base/basictypes.h"
  14 #include "base/process.h"
  15
  16 #include "nscore.h"
  17 #include "nsDebug.h"
  18 #include "nsAutoPtr.h"
  19
  20 #include "ipc/IPCMessageUtils.h"
  21 #include "mozilla/ipc/SharedMemory.h"
  22
  23 /**
  24  * |Shmem| is one agent in the IPDL shared memory scheme.  The way it
  25     works is essentially
  26  *
  27  *  (1) C++ code calls, say, |parentActor->AllocShmem(size)|
  28
  29  *  (2) IPDL-generated code creates a |mozilla::ipc::SharedMemory|
  30  *  wrapping the bare OS shmem primitives.  The code then adds the new
  31  *  SharedMemory to the set of shmem segments being managed by IPDL.
  32  *
  33  *  (3) IPDL-generated code "shares" the new SharedMemory to the child
  34  *  process, and then sends a special asynchronous IPC message to the
  35  *  child notifying it of the creation of the segment.  (What this
  36  *  means is OS specific.)
  37  *
  38  *  (4a) The child receives the special IPC message, and using the
  39  *  |SharedMemory{SysV,Basic}::Handle| it was passed, creates a
  40  *  |mozilla::ipc::SharedMemory| in the child
  41  *  process.
  42  *
  43  *  (4b) After sending the "shmem-created" IPC message, IPDL-generated
  44  *  code in the parent returns a |mozilla::ipc::Shmem| back to the C++
  45  *  caller of |parentActor->AllocShmem()|.  The |Shmem| is a "weak
  46  *  reference" to the underlying |SharedMemory|, which is managed by
  47  *  IPDL-generated code.  C++ consumers of |Shmem| can't get at the
  48  *  underlying |SharedMemory|.
  49  *
  50  * If parent code wants to give access rights to the Shmem to the
  51  * child, it does so by sending its |Shmem| to the child, in an IPDL
  52  * message.  The parent's |Shmem| then "dies", i.e. becomes
  53  * inaccessible.  This process could be compared to passing a
  54  * "shmem-access baton" between parent and child.
  55  */
  56
  57 namespace mozilla {
  58 namespace layers {
  59 class ShadowLayerForwarder;
  60 }
  61
  62 namespace ipc {
  63
  64 class Shmem final
  65 {
  66   friend struct IPC::ParamTraits<mozilla::ipc::Shmem>;
  67 #ifdef DEBUG
  68   // For ShadowLayerForwarder::CheckSurfaceDescriptor
  69   friend class mozilla::layers::ShadowLayerForwarder;
  70 #endif
  71
  72 public:
  73   typedef int32_t id_t;
  74   // Low-level wrapper around platform shmem primitives.
  75   typedef mozilla::ipc::SharedMemory SharedMemory;
  76   typedef SharedMemory::SharedMemoryType SharedMemoryType;
  77   struct IHadBetterBeIPDLCodeCallingThis_OtherwiseIAmADoodyhead {};
  78
  79   Shmem() :
  80     mSegment(nullptr),
  81     mData(nullptr),
  82     mSize(0),
  83     mId(0)
  84   {
  85   }
  86
  87   Shmem(const Shmem& aOther) :
  88     mSegment(aOther.mSegment),
  89     mData(aOther.mData),
  90     mSize(aOther.mSize),
  91     mId(aOther.mId)
  92   {
  93   }
  94
  95 #if !defined(DEBUG)
  96   Shmem(IHadBetterBeIPDLCodeCallingThis_OtherwiseIAmADoodyhead,
  97         SharedMemory* aSegment, id_t aId) :
  98     mSegment(aSegment),
  99     mData(aSegment->memory()),
 100     mSize(0),
 101     mId(aId)
 102   {
 103     mSize = static_cast<size_t>(*PtrToSize(mSegment));
 104   }
 105 #else
 106   Shmem(IHadBetterBeIPDLCodeCallingThis_OtherwiseIAmADoodyhead,
 107         SharedMemory* aSegment, id_t aId);
 108 #endif
 109
 110   ~Shmem()
 111   {
 112     // Shmem only holds a "weak ref" to the actual segment, which is
 113     // owned by IPDL. So there's nothing interesting to be done here
 114     forget(IHadBetterBeIPDLCodeCallingThis_OtherwiseIAmADoodyhead());
 115   }
 116
 117   Shmem& operator=(const Shmem& aRhs)
 118   {
 119     mSegment = aRhs.mSegment;
 120     mData = aRhs.mData;
 121     mSize = aRhs.mSize;
 122     mId = aRhs.mId;
 123     return *this;
 124   }
 125
 126   bool operator==(const Shmem& aRhs) const
 127   {
 128     // need to compare IDs because of AdoptShmem(); two Shmems might
 129     // refer to the same segment but with different IDs for different
 130     // protocol trees.  (NB: it's possible for this method to
 131     // spuriously return true if AdoptShmem() gives the same ID for
 132     // two protocol trees, but I don't think that can cause any
 133     // problems since the Shmems really would be indistinguishable.)
 134     return mSegment == aRhs.mSegment && mId == aRhs.mId;
 135   }
 136
 137   // Returns whether this Shmem is writable by you, and thus whether you can
 138   // transfer writability to another actor.
 139   bool
 140   IsWritable() const
 141   {
 142     return mSegment != nullptr;
 143   }
 144
 145   // Returns whether this Shmem is readable by you, and thus whether you can
 146   // transfer readability to another actor.
 147   bool
 148   IsReadable() const
 149   {
 150     return mSegment != nullptr;
 151   }
 152
 153   // Return a pointer to the user-visible data segment.
 154   template<typename T>
 155   T*
 156   get() const
 157   {
 158     AssertInvariants();
 159     AssertAligned<T>();
 160
 161     return reinterpret_cast<T*>(mData);
 162   }
 163
 164   // Return the size of the segment as requested when this shmem
 165   // segment was allocated, in units of T.  The underlying mapping may
 166   // actually be larger because of page alignment and private data,
 167   // but this isn't exposed to clients.
 168   template<typename T>
 169   size_t
 170   Size() const
 171   {
 172     AssertInvariants();
 173     AssertAligned<T>();
 174
 175     return mSize / sizeof(T);
 176   }
 177
 178   int GetSysVID() const;
 179
 180   // These shouldn't be used directly, use the IPDL interface instead.
 181   id_t Id(IHadBetterBeIPDLCodeCallingThis_OtherwiseIAmADoodyhead) const {
 182     return mId;
 183   }
 184
 185   SharedMemory* Segment(IHadBetterBeIPDLCodeCallingThis_OtherwiseIAmADoodyhead) const {
 186     return mSegment;
 187   }
 188
 189 #ifndef DEBUG
 190   void RevokeRights(IHadBetterBeIPDLCodeCallingThis_OtherwiseIAmADoodyhead)
 191   {
 192   }
 193 #else
 194   void RevokeRights(IHadBetterBeIPDLCodeCallingThis_OtherwiseIAmADoodyhead);
 195 #endif
 196
 197   void forget(IHadBetterBeIPDLCodeCallingThis_OtherwiseIAmADoodyhead)
 198   {
 199     mSegment = nullptr;
 200     mData = nullptr;
 201     mSize = 0;
 202     mId = 0;
 203   }
 204
 205   static already_AddRefed<Shmem::SharedMemory>
 206   Alloc(IHadBetterBeIPDLCodeCallingThis_OtherwiseIAmADoodyhead,
 207         size_t aNBytes,
 208         SharedMemoryType aType,
 209         bool aUnsafe,
 210         bool aProtect=false);
 211
 212   // Prepare this to be shared with |aProcess|.  Return an IPC message
 213   // that contains enough information for the other process to map
 214   // this segment in OpenExisting() below.  Return a new message if
 215   // successful (owned by the caller), nullptr if not.
 216   IPC::Message*
 217   ShareTo(IHadBetterBeIPDLCodeCallingThis_OtherwiseIAmADoodyhead,
 218           base::ProcessHandle aProcess,
 219           int32_t routingId);
 220
 221   // Stop sharing this with |aProcess|.  Return an IPC message that
 222   // contains enough information for the other process to unmap this
 223   // segment.  Return a new message if successful (owned by the
 224   // caller), nullptr if not.
 225   IPC::Message*
 226   UnshareFrom(IHadBetterBeIPDLCodeCallingThis_OtherwiseIAmADoodyhead,
 227               base::ProcessHandle aProcess,
 228               int32_t routingId);
 229
 230   // Return a SharedMemory instance in this process using the
 231   // descriptor shared to us by the process that created the
 232   // underlying OS shmem resource.  The contents of the descriptor
 233   // depend on the type of SharedMemory that was passed to us.
 234   static already_AddRefed<SharedMemory>
 235   OpenExisting(IHadBetterBeIPDLCodeCallingThis_OtherwiseIAmADoodyhead,
 236                const IPC::Message& aDescriptor,
 237                id_t* aId,
 238                bool aProtect=false);
 239
 240   static void
 241   Dealloc(IHadBetterBeIPDLCodeCallingThis_OtherwiseIAmADoodyhead,
 242           SharedMemory* aSegment);
 243
 244 private:
 245   template<typename T>
 246   void AssertAligned() const
 247   {
 248     if (0 != (mSize % sizeof(T)))
 249       NS_RUNTIMEABORT("shmem is not T-aligned");
 250   }
 251
 252 #if !defined(DEBUG)
 253   void AssertInvariants() const
 254   { }
 255
 256   static uint32_t*
 257   PtrToSize(SharedMemory* aSegment)
 258   {
 259     char* endOfSegment =
 260       reinterpret_cast<char*>(aSegment->memory()) + aSegment->Size();
 261     return reinterpret_cast<uint32_t*>(endOfSegment - sizeof(uint32_t));
 262   }
 263
 264 #else
 265   void AssertInvariants() const;
 266 #endif
 267
 268   SharedMemory* MOZ_NON_OWNING_REF mSegment;
 269   void* mData;
 270   size_t mSize;
 271   id_t mId;
 272 };
 273
 274
 275 } // namespace ipc
 276 } // namespace mozilla
 277
 278
 279 namespace IPC {
 280
 281 template<>
 282 struct ParamTraits<mozilla::ipc::Shmem>
 283 {
 284   typedef mozilla::ipc::Shmem paramType;
 285
 286   // NB: Read()/Write() look creepy in that Shmems have a pointer
 287   // member, but IPDL internally uses mId to properly initialize a
 288   // "real" Shmem
 289
 290   static void Write(Message* aMsg, const paramType& aParam)
 291   {
 292     WriteParam(aMsg, aParam.mId);
 293   }
 294
 295   static bool Read(const Message* aMsg, void** aIter, paramType* aResult)
 296   {
 297     paramType::id_t id;
 298     if (!ReadParam(aMsg, aIter, &id))
 299       return false;
 300     aResult->mId = id;
 301     return true;
 302   }
 303
 304   static void Log(const paramType& aParam, std::wstring* aLog)
 305   {
 306     aLog->append(L"(shmem segment)");
 307   }
 308 };
 309
 310
 311 } // namespace IPC
 312
 313
 314 #endif // ifndef mozilla_ipc_Shmem_h