summaryrefslogtreecommitdiffstats
path: root/dom/docs/navigation/embedding.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
commit26a029d407be480d791972afb5975cf62c9360a6 (patch)
treef435a8308119effd964b339f76abb83a57c29483 /dom/docs/navigation/embedding.rst
parentInitial commit. (diff)
downloadfirefox-26a029d407be480d791972afb5975cf62c9360a6.tar.xz
firefox-26a029d407be480d791972afb5975cf62c9360a6.zip
Adding upstream version 124.0.1.upstream/124.0.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'dom/docs/navigation/embedding.rst')
-rw-r--r--dom/docs/navigation/embedding.rst92
1 files changed, 92 insertions, 0 deletions
diff --git a/dom/docs/navigation/embedding.rst b/dom/docs/navigation/embedding.rst
new file mode 100644
index 0000000000..a42aabc6f5
--- /dev/null
+++ b/dom/docs/navigation/embedding.rst
@@ -0,0 +1,92 @@
+Browsing Context Embedding
+==========================
+
+Embedder Element to nsDocShell
+------------------------------
+
+In order to render the contents of a ``BrowsingContext``, the embedding
+element needs to be able to communicate with the ``nsDocShell`` which is
+currently being used to host it's content. This is done in 3 different ways
+depending on which combination of processes is in-use.
+
+- *in-process*: The ``nsFrameLoader`` directly embeds the ``nsDocShell``.
+- *remote tab*: The parent process is the embedder, and uses a ``PBrowser``,
+ via a ``BrowserHost``. The ``BrowserChild`` actor holds the actual
+ ``nsDocShell`` alive.
+- *remote subframe*: A content process is the embedder, and uses a
+ ``PBrowserBridge``, via a ``BrowserBridgeHost`` to communicate with the
+ parent process. The parent process then uses a ``BrowserParent``, as in the
+ *remote tab* case, to communicate with the ``nsDocShell``.
+
+Diagram
+^^^^^^^
+
+.. digraph:: embedding
+
+ node [shape=rectangle]
+
+ subgraph cluster_choice {
+ color=transparent;
+ node [shape=none];
+
+ "In-Process";
+ "Remote Tab";
+ "Remote Subframe";
+ }
+
+ "nsFrameLoaderOwner" [label="nsFrameLoaderOwner\ne.g. <iframe>, <xul:browser>, <embed>"]
+
+ "nsFrameLoaderOwner" -> "nsFrameLoader";
+
+ "nsFrameLoader" -> "In-Process" [dir=none];
+ "nsFrameLoader" -> "Remote Tab" [dir=none];
+ "nsFrameLoader" -> "Remote Subframe" [dir=none];
+
+ "In-Process" -> "nsDocShell";
+ "Remote Tab" -> "BrowserHost";
+ "Remote Subframe" -> "BrowserBridgeHost";
+
+ "BrowserHost" -> "BrowserParent";
+ "BrowserParent" -> "BrowserChild" [label="PBrowser" style=dotted];
+ "BrowserChild" -> "nsDocShell";
+
+ "BrowserBridgeHost" -> "BrowserBridgeChild";
+ "BrowserBridgeChild" -> "BrowserBridgeParent" [label="PBrowserBridge", style=dotted];
+ "BrowserBridgeParent" -> "BrowserParent";
+
+nsDocShell to Document
+----------------------
+
+Embedding an individual document within a ``nsDocShell`` is done within the
+content process, which has that docshell.
+
+
+Diagram
+^^^^^^^
+
+This diagram shows the objects involved in a content process which is being
+used to host a given ``BrowsingContext``, along with rough relationships
+between them. Dotted lines represent a "current" relationship, whereas solid
+lines are a stronger lifetime relationship.
+
+.. graph:: document
+
+ node [shape=rectangle]
+
+ "BrowsingContext" -- "nsDocShell" [style=dotted];
+ "nsDocShell" -- "nsGlobalWindowOuter";
+ "nsGlobalWindowOuter" -- "nsGlobalWindowInner" [style=dotted];
+ "nsGlobalWindowInner" -- "Document" [style=dotted];
+
+ "nsDocShell" -- "nsDocumentViewer" [style=dotted];
+ "nsDocumentViewer" -- "Document";
+ "nsDocumentViewer" -- "PresShell";
+
+ "nsGlobalWindowInner" -- "WindowGlobalChild";
+ "BrowsingContext" -- "WindowContext" [style=dotted];
+ "WindowContext" -- "nsGlobalWindowInner";
+
+ subgraph cluster_synced {
+ label = "Synced Contexts";
+ "BrowsingContext" "WindowContext";
+ }