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::ipc {
  57
  58 class IProtocol;
  59 class IToplevelProtocol;
  60
  61 template <typename P>
  62 struct IPDLParamTraits;
  63
  64 class Shmem final {
  65   friend struct IPDLParamTraits<mozilla::ipc::Shmem>;
  66   friend class mozilla::ipc::IProtocol;
  67   friend class mozilla::ipc::IToplevelProtocol;
  68
  69  public:
  70   typedef int32_t id_t;
  71   // Low-level wrapper around platform shmem primitives.
  72   typedef mozilla::ipc::SharedMemory SharedMemory;
  73
  74   Shmem() : mSegment(nullptr), mData(nullptr), mSize(0), mId(0) {}
  75
  76   Shmem(const Shmem& aOther) = default;
  77
  78   ~Shmem() {
  79     // Shmem only holds a "weak ref" to the actual segment, which is
  80     // owned by IPDL. So there's nothing interesting to be done here
  81     forget();
  82   }
  83
  84   Shmem& operator=(const Shmem& aRhs) = default;
  85
  86   bool operator==(const Shmem& aRhs) const { return mSegment == aRhs.mSegment; }
  87
  88   // Returns whether this Shmem is writable by you, and thus whether you can
  89   // transfer writability to another actor.
  90   bool IsWritable() const { return mSegment != nullptr; }
  91
  92   // Returns whether this Shmem is readable by you, and thus whether you can
  93   // transfer readability to another actor.
  94   bool IsReadable() const { return mSegment != nullptr; }
  95
  96   // Return a pointer to the user-visible data segment.
  97   template <typename T>
  98   T* get() const {
  99     AssertInvariants();
 100     AssertAligned<T>();
 101
 102     return reinterpret_cast<T*>(mData);
 103   }
 104
 105   // Return the size of the segment as requested when this shmem
 106   // segment was allocated, in units of T.  The underlying mapping may
 107   // actually be larger because of page alignment and private data,
 108   // but this isn't exposed to clients.
 109   template <typename T>
 110   size_t Size() const {
 111     AssertInvariants();
 112     AssertAligned<T>();
 113
 114     return mSize / sizeof(T);
 115   }
 116
 117   template <typename T>
 118   Range<T> Range() const {
 119     return {get<T>(), Size<T>()};
 120   }
 121
 122  private:
 123   // These shouldn't be used directly, use the IPDL interface instead.
 124
 125   Shmem(SharedMemory* aSegment, id_t aId, size_t aSize, bool aUnsafe);
 126
 127   id_t Id() const { return mId; }
 128
 129   SharedMemory* Segment() const { return mSegment; }
 130
 131 #ifndef DEBUG
 132   void RevokeRights() {}
 133 #else
 134   void RevokeRights();
 135 #endif
 136
 137   void forget() {
 138     mSegment = nullptr;
 139     mData = nullptr;
 140     mSize = 0;
 141     mId = 0;
 142 #ifdef DEBUG
 143     mUnsafe = false;
 144 #endif
 145   }
 146
 147   static already_AddRefed<Shmem::SharedMemory> Alloc(size_t aNBytes);
 148
 149   // Prepare this to be shared with another process. Return an IPC message that
 150   // contains enough information for the other process to map this segment in
 151   // OpenExisting() below.  Return a new message if successful (owned by the
 152   // caller), nullptr if not.
 153   UniquePtr<IPC::Message> MkCreatedMessage(int32_t routingId);
 154
 155   // Stop sharing this with another process. Return an IPC message that
 156   // contains enough information for the other process to unmap this
 157   // segment.  Return a new message if successful (owned by the
 158   // caller), nullptr if not.
 159   UniquePtr<IPC::Message> MkDestroyedMessage(int32_t routingId);
 160
 161   // Return a SharedMemory instance in this process using the descriptor shared
 162   // to us by the process that created the underlying OS shmem resource.  The
 163   // contents of the descriptor depend on the type of SharedMemory that was
 164   // passed to us.
 165   static already_AddRefed<SharedMemory> OpenExisting(
 166       const IPC::Message& aDescriptor, id_t* aId, bool aProtect = false);
 167
 168   template <typename T>
 169   void AssertAligned() const {
 170     if (0 != (mSize % sizeof(T))) MOZ_CRASH("shmem is not T-aligned");
 171   }
 172
 173 #if !defined(DEBUG)
 174   void AssertInvariants() const {}
 175 #else
 176   void AssertInvariants() const;
 177 #endif
 178
 179   RefPtr<SharedMemory> mSegment;
 180   void* mData;
 181   size_t mSize;
 182   id_t mId;
 183 #ifdef DEBUG
 184   bool mUnsafe = false;
 185 #endif
 186 };
 187
 188 }  // namespace mozilla::ipc
 189
 190 #endif  // ifndef mozilla_ipc_Shmem_h