From 0ebf5bdf043a27fd3dfb7f92e0cb63d88954c44d Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 03:47:29 +0200 Subject: Adding upstream version 115.8.0esr. Signed-off-by: Daniel Baumann --- dom/docs/ipc/Fission-IPC-Diagram.svg | 5 + dom/docs/ipc/Fission-actors-diagram.png | Bin 0 -> 69010 bytes dom/docs/ipc/Fission-framescripts.png | Bin 0 -> 84425 bytes dom/docs/ipc/index.rst | 9 + dom/docs/ipc/jsactors.rst | 547 ++++++++++++++++++++++++++++++++ dom/docs/ipc/mainthread.rst | 13 + dom/docs/ipc/process_model.rst | 334 +++++++++++++++++++ 7 files changed, 908 insertions(+) create mode 100644 dom/docs/ipc/Fission-IPC-Diagram.svg create mode 100644 dom/docs/ipc/Fission-actors-diagram.png create mode 100644 dom/docs/ipc/Fission-framescripts.png create mode 100644 dom/docs/ipc/index.rst create mode 100644 dom/docs/ipc/jsactors.rst create mode 100644 dom/docs/ipc/mainthread.rst create mode 100644 dom/docs/ipc/process_model.rst (limited to 'dom/docs/ipc') diff --git a/dom/docs/ipc/Fission-IPC-Diagram.svg b/dom/docs/ipc/Fission-IPC-Diagram.svg new file mode 100644 index 0000000000..f53d4b65b4 --- /dev/null +++ b/dom/docs/ipc/Fission-IPC-Diagram.svg @@ -0,0 +1,5 @@ + + +
Browser Process
Browser Process
Content Process
<div>Content Process</div>
Content Process
<div>Content Process</div>
<xul:browser src="a.com"/>
nsFrameLoader
[Not supported by viewer]
PBrowser
[Not supported by viewer]
BrowserParent
BrowserParent
BrowserChild
BrowserChild
nsWebBrowser
nsWebBrowser
<iframe src="b.com"/>
nsFrameLoader
[Not supported by viewer]
PBrowserBridge
PBrowserBridge
BrowserBridgeChild
BrowserBridgeChild
PBrowser
[Not supported by viewer]
BrowserParent
BrowserParent
BrowserChild
BrowserChild
PBrowser
[Not supported by viewer]
BrowserParent
BrowserParent
BrowserChild
BrowserChild
BrowserBridgeParent
BrowserBridgeParent
BrowserBridgeParent
BrowserBridgeParent
nsWebBrowser
nsWebBrowser
nsWebBrowser
nsWebBrowser
<iframe src="a.com"/>
nsFrameLoader
[Not supported by viewer]
PBrowserBridge
PBrowserBridge
BrowserBridgeChild
BrowserBridgeChild

Gecko IPC for Fission

Example:
<xul:browser src="a.com"/>
  <iframe src="b.com"/>
    <iframe src="a.com"/>

[Not supported by viewer] \ No newline at end of file diff --git a/dom/docs/ipc/Fission-actors-diagram.png b/dom/docs/ipc/Fission-actors-diagram.png new file mode 100644 index 0000000000..d3acce2c5c Binary files /dev/null and b/dom/docs/ipc/Fission-actors-diagram.png differ diff --git a/dom/docs/ipc/Fission-framescripts.png b/dom/docs/ipc/Fission-framescripts.png new file mode 100644 index 0000000000..98748bc965 Binary files /dev/null and b/dom/docs/ipc/Fission-framescripts.png differ diff --git a/dom/docs/ipc/index.rst b/dom/docs/ipc/index.rst new file mode 100644 index 0000000000..4a044ab906 --- /dev/null +++ b/dom/docs/ipc/index.rst @@ -0,0 +1,9 @@ +DOM IPC +======= + +.. toctree:: + :maxdepth: 1 + + jsactors + mainthread + process_model diff --git a/dom/docs/ipc/jsactors.rst b/dom/docs/ipc/jsactors.rst new file mode 100644 index 0000000000..3cd2d63c79 --- /dev/null +++ b/dom/docs/ipc/jsactors.rst @@ -0,0 +1,547 @@ +JSActors +======== + +In the Fission world, the preferred method of communication between between things-that-may-live-in-a-different-process are JSActors. + +At the time of this writing, Fission offers the following JSActors: + +- `JSProcessActor`, to communicate between a child process and its parent; +- `JSWindowActor`, to communicate between a frame and its parent. + +JSProcessActor +--------------- + +What are JSProcessActors? +~~~~~~~~~~~~~~~~~~~~~~~~~ + +A JSProcess pair (see below) is the preferred method of communication between a child process and its parent process. + +In the Fission world, JSProcessActors are the replacement for e10s-era *process scripts*. + +The life of a JSProcessActor pair +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +JSProcessActors always exist by pair: + +- one instance of `JSProcessActorChild`, which lives in the child process – for instance, `MyActorChild`; +- one instance of `JSProcessActorParent`, which lives in the parent process – for instance, `MyActorParent`. + +The pair is instantiated lazily, upon the first call to `getActor("MyActor")` (see below). Note that if a +parent process has several children, the parent process will typically host several instances of `MyActorParent` +whereas the children will each host a single instance of `MyActorChild`. + +JSProcessActor primitives allow sending and receiving messages *within the pair*. As of this writing, +JSProcessActor does not offer primitives for broadcasting, enumerating, etc. + +The pair dies when the child process dies. + +About actor names +`````````````````` + +Note that the names +`MyActorChild` and `MyActorParent` are meaningful – suffixes `Child` and `Parent` are how `getActor(...)` finds +the correct classes to load within the JS code. + + +JSWindowActor +--------------- + +What are JSWindowActors? +~~~~~~~~~~~~~~~~~~~~~~~~~ + +A JSWindowActor pair (see below) is the preferred method of communication between a frame and its parent, regardless of whether the frame +and parent live in the same process or in distinct processes. + +In the Fission world, JSWindowActors are the replacement for *framescripts*. Framescripts were how we structured code to be aware of the parent (UI) and child (content) separation, including establishing the communication channel between the two (via the Frame Message Manager). + +However, the framescripts had no way to establish further process separation downwards (that is, for out-of-process iframes). JSWindowActors will be the replacement. + +How are they structured? +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A review of the pre-Fission Message Manager mechanism +````````````````````````````````````````````````````` + +.. note:: + There are actually several types of Message Managers: Frame Message Managers, Window Message Managers, Group Message Managers and Process Message Managers. For the purposes of this documentation, it's simplest to refer to all of these mechanisms altogether as the "Message Manager mechanism". Most of the examples in this document will be operating on the assumption that the Message Manager is a Frame Message Manager, which is the most commonly used one. + +Currently, in the post `Electrolysis Project`_ Firefox codebase, we have code living in the parent process (UI) that is in plain JS (.js files) or in JS modules (.jsm files). In the child process (hosting the content), we use framescripts (.js) and also JS modules. The framescripts are instantiated once per top-level frame (or, in simpler terms, once per tab). This code has access to all of the DOM from the web content, including all iframes within it. + +The two processes communicate via the Frame Message Manager (mm) using the ``sendAsyncMessage`` / ``receiveMessage`` API, and any code in the parent can communicate with any code in the child (and vice versa), by just listening to the messages of interest. + +The Frame Message Manager communication mechanism follows a publish / subscribe pattern similar to how Events work in Firefox: + +1. Something exposes a mechanism for subscribing to notifications (``addMessageListener`` for the Frame Message Manager, ``addEventListener`` for Events). +2. The subscriber is responsible for unsubscribing when there's no longer interest in the notifications (``removeMessageListener`` for the Frame Message Manager, ``removeEventListener`` for Events). +3. Any number of subscribers can be attached at any one time. + +.. figure:: Fission-framescripts.png + :width: 320px + :height: 200px + +How JSWindowActors differ from the Frame Message Manager +`````````````````````````````````````````````````````````` + +For Fission, the JSWindowActors replacing framescripts will be structured in pairs. A pair of JSWindowActors will be instantiated lazily: one in the parent and one in the child process, and a direct channel of communication between the two will be established. The JSWindowActor in the parent must extend the global ``JSWindowActorParent`` class, and the JSWindowActor in the child must extend the global ``JSWindowActorChild`` class. + +The JSWindowActor mechanism is similar to how `IPC Actors`_ work in the native layer of Firefox: + +#. Every Actor has one counterpart in another process that they can communicate directly with. +#. Every Actor inherits a common communications API from a parent class. +#. Every Actor has a name that ends in either ``Parent`` or ``Child``. +#. There is no built-in mechanism for subscribing to messages. When one JSWindowActor sends a message, the counterpart JSWindowActor on the other side will receive it without needing to explicitly listen for it. + +Other notable differences between JSWindowActor's and Message Manager / framescripts: + +#. Each JSWindowActor pair is associated with a particular frame. For example, given the following DOM hierarchy:: + + +