dom/messagechannel/MessagePort.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_dom_MessagePort_h
   8 #define mozilla_dom_MessagePort_h
   9
  10 #include "mozilla/Attributes.h"
  11 #include "mozilla/DOMEventTargetHelper.h"
  12 #include "mozilla/dom/DOMTypes.h"
  13 #include "mozilla/UniquePtr.h"
  14 #include "nsTArray.h"
  15
  16 #ifdef XP_WIN
  17 #  undef PostMessage
  18 #endif
  19
  20 class nsIGlobalObject;
  21
  22 namespace mozilla::dom {
  23
  24 class MessageData;
  25 class MessagePortChild;
  26 class PostMessageRunnable;
  27 class RefMessageBodyService;
  28 class SharedMessageBody;
  29 class StrongWorkerRef;
  30 struct StructuredSerializeOptions;
  31
  32 // A class to hold a MessagePortIdentifier from
  33 // MessagePort::CloneAndDistentangle() and close if neither passed to
  34 // MessagePort::Create() nor release()ed to send via IPC.
  35 // When the `neutered` field of the MessagePortIdentifier is false, a close is
  36 // required.
  37 // This does not derive from MessagePortIdentifier because
  38 // MessagePortIdentifier is final and because use of UniqueMessagePortId as a
  39 // MessagePortIdentifier is intentionally prevented without release of
  40 // ownership.
  41 class UniqueMessagePortId final {
  42  public:
  43   UniqueMessagePortId() { mIdentifier.neutered() = true; }
  44   explicit UniqueMessagePortId(const MessagePortIdentifier& aIdentifier)
  45       : mIdentifier(aIdentifier) {}
  46   UniqueMessagePortId(UniqueMessagePortId&& aOther) noexcept
  47       : mIdentifier(aOther.mIdentifier) {
  48     aOther.mIdentifier.neutered() = true;
  49   }
  50   ~UniqueMessagePortId() { ForceClose(); };
  51   void ForceClose();
  52
  53   [[nodiscard]] MessagePortIdentifier release() {
  54     MessagePortIdentifier id = mIdentifier;
  55     mIdentifier.neutered() = true;
  56     return id;
  57   }
  58   // const member accessors are not required because a const
  59   // UniqueMessagePortId is not useful.
  60   nsID& uuid() { return mIdentifier.uuid(); }
  61   nsID& destinationUuid() { return mIdentifier.destinationUuid(); }
  62   uint32_t& sequenceId() { return mIdentifier.sequenceId(); }
  63   bool& neutered() { return mIdentifier.neutered(); }
  64
  65   UniqueMessagePortId(const UniqueMessagePortId& aOther) = delete;
  66   void operator=(const UniqueMessagePortId& aOther) = delete;
  67
  68  private:
  69   MessagePortIdentifier mIdentifier;
  70 };
  71
  72 class MessagePort final : public DOMEventTargetHelper {
  73   friend class PostMessageRunnable;
  74
  75  public:
  76   NS_DECL_ISUPPORTS_INHERITED
  77   NS_DECL_CYCLE_COLLECTION_CLASS_INHERITED(MessagePort, DOMEventTargetHelper)
  78
  79   static already_AddRefed<MessagePort> Create(nsIGlobalObject* aGlobal,
  80                                               const nsID& aUUID,
  81                                               const nsID& aDestinationUUID,
  82                                               ErrorResult& aRv);
  83
  84   static already_AddRefed<MessagePort> Create(nsIGlobalObject* aGlobal,
  85                                               UniqueMessagePortId& aIdentifier,
  86                                               ErrorResult& aRv);
  87
  88   // For IPC.
  89   static void ForceClose(const MessagePortIdentifier& aIdentifier);
  90
  91   virtual JSObject* WrapObject(JSContext* aCx,
  92                                JS::Handle<JSObject*> aGivenProto) override;
  93
  94   void PostMessage(JSContext* aCx, JS::Handle<JS::Value> aMessage,
  95                    const Sequence<JSObject*>& aTransferable, ErrorResult& aRv);
  96
  97   void PostMessage(JSContext* aCx, JS::Handle<JS::Value> aMessage,
  98                    const StructuredSerializeOptions& aOptions,
  99                    ErrorResult& aRv);
 100
 101   void Start();
 102
 103   void Close();
 104
 105   EventHandlerNonNull* GetOnmessage();
 106
 107   void SetOnmessage(EventHandlerNonNull* aCallback);
 108
 109   IMPL_EVENT_HANDLER(messageerror)
 110
 111   // Non WebIDL methods
 112
 113   void UnshippedEntangle(RefPtr<MessagePort>& aEntangledPort);
 114
 115   bool CanBeCloned() const { return !mHasBeenTransferredOrClosed; }
 116
 117   void CloneAndDisentangle(UniqueMessagePortId& aIdentifier);
 118
 119   void CloseForced();
 120
 121   // These methods are useful for MessagePortChild
 122
 123   void Entangled(nsTArray<MessageData>& aMessages);
 124   void MessagesReceived(nsTArray<MessageData>& aMessages);
 125   void StopSendingDataConfirmed();
 126   void Closed();
 127
 128  private:
 129   enum State {
 130     // The plan is to be eStateUnshippedEntangled once we are told about our
 131     // unshipped entangled counterpart.
 132     eStateInitializingUnshippedEntangled,
 133
 134     // When a port is created by a MessageChannel it is entangled with the
 135     // other. They both run on the same thread, same event loop and the
 136     // messages are added to the queues without using PBackground actors.
 137     // When one of the port is shipped, the state is changed to
 138     // StateEntangling.
 139     eStateUnshippedEntangled,
 140
 141     // If the port is closed or cloned when we are in this state, we go in one
 142     // of the following 2 steps. EntanglingForClose or ForDisentangle.
 143     eStateEntangling,
 144
 145     // We are not fully entangled yet but are already disentangled.
 146     eStateEntanglingForDisentangle,
 147
 148     // We are not fully entangled yet but are already closed.
 149     eStateEntanglingForClose,
 150
 151     // When entangled() is received we send all the messages in the
 152     // mMessagesForTheOtherPort to the actor and we change the state to
 153     // StateEntangled. At this point the port is entangled with the other. We
 154     // send and receive messages.
 155     // If the port queue is not enabled, the received messages are stored in
 156     // the mMessages.
 157     eStateEntangled,
 158
 159     // When the port is cloned or disentangled we want to stop receiving
 160     // messages. We call 'SendStopSendingData' to the actor and we wait for an
 161     // answer. All the messages received between now and the
 162     // 'StopSendingDataComfirmed are queued in the mMessages but not
 163     // dispatched.
 164     eStateDisentangling,
 165
 166     // When 'StopSendingDataConfirmed' is received, we can disentangle the port
 167     // calling SendDisentangle in the actor because we are 100% sure that we
 168     // don't receive any other message, so nothing will be lost.
 169     // Disentangling the port we send all the messages from the mMessages
 170     // though the actor.
 171     eStateDisentangled,
 172
 173     // We are here if Close() has been called. We are disentangled but we can
 174     // still send pending messages.
 175     eStateDisentangledForClose
 176   };
 177
 178   explicit MessagePort(nsIGlobalObject* aGlobal, State aState);
 179   ~MessagePort();
 180
 181   void DisconnectFromOwner() override;
 182
 183   void Initialize(const nsID& aUUID, const nsID& aDestinationUUID,
 184                   uint32_t aSequenceID, bool aNeutered, ErrorResult& aRv);
 185
 186   bool ConnectToPBackground();
 187
 188   // Dispatch events from the Message Queue using a nsRunnable.
 189   void Dispatch();
 190
 191   void DispatchError();
 192
 193   void StartDisentangling();
 194   void Disentangle();
 195
 196   void RemoveDocFromBFCache();
 197
 198   void CloseInternal(bool aSoftly);
 199
 200   // This method is meant to keep alive the MessagePort when this object is
 201   // creating the actor and until the actor is entangled.
 202   // We release the object when the port is closed or disentangled.
 203   void UpdateMustKeepAlive();
 204
 205   bool IsCertainlyAliveForCC() const override { return mIsKeptAlive; }
 206
 207   RefPtr<StrongWorkerRef> mWorkerRef;
 208
 209   RefPtr<PostMessageRunnable> mPostMessageRunnable;
 210
 211   RefPtr<MessagePortChild> mActor;
 212
 213   RefPtr<MessagePort> mUnshippedEntangledPort;
 214
 215   RefPtr<RefMessageBodyService> mRefMessageBodyService;
 216
 217   nsTArray<RefPtr<SharedMessageBody>> mMessages;
 218   nsTArray<RefPtr<SharedMessageBody>> mMessagesForTheOtherPort;
 219
 220   UniquePtr<MessagePortIdentifier> mIdentifier;
 221
 222   State mState;
 223
 224   bool mMessageQueueEnabled;
 225
 226   bool mIsKeptAlive;
 227
 228   // mHasBeenTransferredOrClosed is used to know if this port has been manually
 229   // closed or transferred via postMessage. Note that if the entangled port is
 230   // closed, this port is closed as well (see mState) but, just because close()
 231   // has not been called directly, by spec, this port can still be transferred.
 232   bool mHasBeenTransferredOrClosed;
 233 };
 234
 235 }  // namespace mozilla::dom
 236
 237 #endif  // mozilla_dom_MessagePort_h