tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

embedding.rst (2928B)

      1 Browsing Context Embedding
      2 ==========================
      3 
      4 Embedder Element to nsDocShell
      5 ------------------------------
      6 
      7 In order to render the contents of a ``BrowsingContext``, the embedding
      8 element needs to be able to communicate with the ``nsDocShell`` which is
      9 currently being used to host it's content. This is done in 3 different ways
     10 depending on which combination of processes is in-use.
     11 
     12 - *in-process*: The ``nsFrameLoader`` directly embeds the ``nsDocShell``.
     13 - *remote tab*: The parent process is the embedder, and uses a ``PBrowser``,
     14  via a ``BrowserHost``. The ``BrowserChild`` actor holds the actual
     15  ``nsDocShell`` alive.
     16 - *remote subframe*: A content process is the embedder, and uses a
     17  ``PBrowserBridge``, via a ``BrowserBridgeHost`` to communicate with the
     18  parent process. The parent process then uses a ``BrowserParent``, as in the
     19  *remote tab* case, to communicate with the ``nsDocShell``.
     20 
     21 Diagram
     22 ^^^^^^^
     23 
     24 .. digraph:: embedding
     25 
     26  node [shape=rectangle]
     27 
     28  subgraph cluster_choice {
     29    color=transparent;
     30    node [shape=none];
     31 
     32    "In-Process";
     33    "Remote Tab";
     34    "Remote Subframe";
     35  }
     36 
     37  "nsFrameLoaderOwner" [label="nsFrameLoaderOwner\ne.g. <iframe>, <xul:browser>, <embed>"]
     38 
     39  "nsFrameLoaderOwner" -> "nsFrameLoader";
     40 
     41  "nsFrameLoader" -> "In-Process" [dir=none];
     42  "nsFrameLoader" -> "Remote Tab" [dir=none];
     43  "nsFrameLoader" -> "Remote Subframe" [dir=none];
     44 
     45  "In-Process" -> "nsDocShell";
     46  "Remote Tab" -> "BrowserHost";
     47  "Remote Subframe" -> "BrowserBridgeHost";
     48 
     49  "BrowserHost" -> "BrowserParent";
     50  "BrowserParent" -> "BrowserChild" [label="PBrowser" style=dotted];
     51  "BrowserChild" -> "nsDocShell";
     52 
     53  "BrowserBridgeHost" -> "BrowserBridgeChild";
     54  "BrowserBridgeChild" -> "BrowserBridgeParent" [label="PBrowserBridge", style=dotted];
     55  "BrowserBridgeParent" -> "BrowserParent";
     56 
     57 nsDocShell to Document
     58 ----------------------
     59 
     60 Embedding an individual document within a ``nsDocShell`` is done within the
     61 content process, which has that docshell.
     62 
     63 
     64 Diagram
     65 ^^^^^^^
     66 
     67 This diagram shows the objects involved in a content process which is being
     68 used to host a given ``BrowsingContext``, along with rough relationships
     69 between them. Dotted lines represent a "current" relationship, whereas solid
     70 lines are a stronger lifetime relationship.
     71 
     72 .. graph:: document
     73 
     74  node [shape=rectangle]
     75 
     76  "BrowsingContext" -- "nsDocShell" [style=dotted];
     77  "nsDocShell" -- "nsGlobalWindowOuter";
     78  "nsGlobalWindowOuter" -- "nsGlobalWindowInner" [style=dotted];
     79  "nsGlobalWindowInner" -- "Document" [style=dotted];
     80 
     81  "nsDocShell" -- "nsDocumentViewer" [style=dotted];
     82  "nsDocumentViewer" -- "Document";
     83  "nsDocumentViewer" -- "PresShell";
     84 
     85  "nsGlobalWindowInner" -- "WindowGlobalChild";
     86  "BrowsingContext" -- "WindowContext" [style=dotted];
     87  "WindowContext" -- "nsGlobalWindowInner";
     88 
     89  subgraph cluster_synced {
     90    label = "Synced Contexts";
     91    "BrowsingContext" "WindowContext";
     92  }