Bug 1595048 - move JSWindowActor notes into Fission.rst document, r=mconley
authorGijs Kruitbosch <gijskruitbosch@gmail.com>
Fri, 08 Nov 2019 19:42:02 +0000
changeset 501354 aa04697d9a3f061726fd6acec930bfaa4062d290
parent 501353 aba92aad986e96b08f23ffd7a20a0d672efd2945
child 501355 0f89eae608917986895f8ec227dc56a4634b4d77
push id114168
push userdluca@mozilla.com
push dateSun, 10 Nov 2019 03:08:55 +0000
treeherdermozilla-inbound@33f64c1ef3e4 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersmconley
bugs1595048
milestone72.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1595048 - move JSWindowActor notes into Fission.rst document, r=mconley Differential Revision: https://phabricator.services.mozilla.com/D52352
browser/components/BrowserGlue.jsm
dom/docs/Fission.rst
toolkit/modules/ActorManagerParent.jsm
--- a/browser/components/BrowserGlue.jsm
+++ b/browser/components/BrowserGlue.jsm
@@ -30,16 +30,21 @@ XPCOMUtils.defineLazyServiceGetter(
   this,
   "PushService",
   "@mozilla.org/push/Service;1",
   "nsIPushService"
 );
 
 const PREF_PDFJS_ENABLED_CACHE_STATE = "pdfjs.enabledCache.state";
 
+/**
+ * Fission-compatible JSWindowActor implementations.
+ * Detailed documentation of these is in dom/docs/Fission.rst,
+ * available at https://firefox-source-docs.mozilla.org/dom/Fission.html#jswindowactor
+ */
 let ACTORS = {
   BrowserTab: {
     parent: {
       moduleURI: "resource:///actors/BrowserTabParent.jsm",
     },
     child: {
       moduleURI: "resource:///actors/BrowserTabChild.jsm",
 
--- a/dom/docs/Fission.rst
+++ b/dom/docs/Fission.rst
@@ -324,17 +324,27 @@ Let's look at the second chunk:
     },
 
 We're similarly declaring where the ``PluginChild`` subclassing ``JSWindowActorChild`` can be found.
 
 Next, we declare the content events, if fired in a BrowsingContext, will cause the JSWindowActor pair to instantiate if it doesn't already exist, and then have ``handleEvent`` called on the ``PluginChild`` instance. For each event name, an Object of event listener options can be passed. You can use the same event listener options as accepted by ``addEventListener``.
 
 Next, we declare that ``PluginChild`` should observe the ``decoder-doctor-notification`` ``nsIObserver`` notification. When that observer notification fires, the ``PluginChild`` will be instantiated for all ``BrowsingContext``'s, and the ``observe`` method on the ``PluginChild`` implementation will be called.
 
-Finally, we say that the ``PluginChild`` actor should apply to ``allFrames``. This means that the ``PluginChild`` is allowed to be loaded in any subframe. If ``allFrames`` is set to false, the actor will only ever load in the top-level frame.
+Finally, we say that the ``PluginChild`` actor should apply to ``allFrames``. This means that the ``PluginChild`` is allowed to be loaded in any subframe. If ``allFrames`` is set to false (the default), the actor will only ever load in the top-level frame.
+
+Design considerations when adding a new JSWindowActor
+`````````````````````````````````````````````````````
+
+A few things worth bearing in mind when adding your own actor registration:
+
+- Any ``child`` or ``parent`` side you register **must** have a ``moduleURI`` property.
+- You do not need to have both ``child`` and ``parent`` modules, and should avoid having actor sides that do nothing but send messages. The process without a defined module will still get an actor, and you can send messages from that side, but cannot receive them via ``receiveMessage``. Note that you **can** also use ``sendQuery`` from this side, enabling you to handle a response from the other process despite not having a ``receiveMessage`` method.
+- Consider whether you really need ``allFrames`` - it'll save memory and CPU time if we don't need to instantiate the actor for subframes.
+- When copying/moving "Legacy" :ref:`fission.message-manager-actors`, remove their ``messages`` properties. They are no longer necessary.
 
 Using ContentDOMReference instead of CPOWs
 ``````````````````````````````````````````
 
 Despite being outlawed as a way of synchronously accessing the properties of objects in other processes, CPOWs ended up being useful as a way of passing handles for DOM elements between processes.
 
 CPOW messages, however, cannot be sent over the JSWindowActor communications pipe, so this handy mechanism will no longer work.
 
--- a/toolkit/modules/ActorManagerParent.jsm
+++ b/toolkit/modules/ActorManagerParent.jsm
@@ -22,43 +22,18 @@ const { ExtensionUtils } = ChromeUtils.i
 );
 const { Services } = ChromeUtils.import("resource://gre/modules/Services.jsm");
 
 const { DefaultMap } = ExtensionUtils;
 
 /**
  * Fission-compatible JSWindowActor implementations.
  * Each actor options object takes the form of a WindowActorOptions dictionary.
- * Detailed documentation of these options is in JSWindowActor.webidl.
- *
- * Some brief "gotcha"s compared to the legacy type actors:
- * - both parent and child sides can be specified; at least one must be
- *   specified. Consider that you may not need both: code in the process
- *   without a module can still request the JSWindowActor instance by name
- *   (the key in the dictionary below) and send messages to the other process
- *   using it - but it cannot listen for responses. Sometimes, this is
- *   sufficient.
- *
- * - JSWindowActor supports `sendQuery`, which allows one process to ask the
- *   other process for something. The other process replies via the return
- *   value of `receiveMessage` in the actor, which also supports promises.
- *   This reduces the need to have "manual" request/response message handling,
- *   counters, etc.
- *
- * - any parent and child option object specified must contain a "moduleURI"
- *   property. The module must export a class that inherits from
- *   JSWindowActorChild (for the child side) or JSWindowActorParent (for the
- *   parent side). The actor should live at resource://gre/actors/
- *   (for toolkit/ ) or resource///actors/ (for browser/ ) uris.
- *
- * - messages are only sent between the parent and child pair of actors.
- *   Therefore, unlike the legacy actors, it is not necessary to specify a list
- *   of messages either actor is interested in. Messages sent using
- *   the actor will always be passed to the `receiveMessage` implementation in
- *   the other process.
+ * Detailed documentation of these options is in dom/docs/Fission.rst,
+ * available at https://firefox-source-docs.mozilla.org/dom/Fission.html#jswindowactor
  */
 let ACTORS = {
   AudioPlayback: {
     parent: {
       moduleURI: "resource://gre/actors/AudioPlaybackParent.jsm",
     },
 
     child: {