Source code
Revision control
Copy as Markdown
Other Tools
# Objects Replaced by Navigations
There are 3 major types of navigations, each of which can cause different
objects to be replaced. The general rules look something like this:
| Class/Id | [in-process navigations](#in-process-navigations) | [cross-process navigations](#cross-process-navigations) | [cross-group navigations](#cross-group-navigations) |
| --- | --- | --- | --- |
| BrowserId [^bid] | preserved | preserved | preserved |
| BrowsingContextWebProgress | preserved | preserved | preserved |
| BrowsingContextGroup | preserved | preserved | replaced |
| BrowsingContext | preserved | preserved | replaced |
| nsFrameLoader | preserved | replaced | replaced |
| RemoteBrowser | preserved | replaced | replaced |
| Browser{Parent,Child} | preserved | replaced | replaced |
| nsDocShell | preserved | replaced | replaced |
| nsGlobalWindowOuter | preserved | replaced | replaced |
| nsGlobalWindowInner | replaced [^inner] | replaced | replaced |
| WindowContext | replaced [^inner] | replaced | replaced |
| WindowGlobal{Parent,Child} | replaced [^inner] | replaced | replaced |
| Document | replaced | replaced | replaced |
[^bid]: The BrowserId is a unique ID on each `BrowsingContext` object, obtained
using `GetBrowserId`, not a class. This ID will persist even when a
`BrowsingContext` is replaced (e.g. due to
`Cross-Origin-Opener-Policy`).
[^inner]: When navigating from the initial `about:blank` document to a same-origin
document, the same `nsGlobalWindowInner`, `WindowContext` and
`WindowGlobal{Parent,Child}` may be used. This initial `about:blank`
document is the one created when synchronously accessing a newly-created
pop-up window from `window.open`, or a newly-created document in an
`<iframe>`.
## Types of Navigations
(in-process-navigations)=
### in-process navigations
An in-process navigation is the traditional type of navigation, and the most
common type of navigation when Fission is not enabled.
These navigations are used when no process switching or BrowsingContext
replacement is required, which includes most navigations with Fission
disabled, and most same site-origin navigations when Fission is enabled.
(cross-process-navigations)=
### cross-process navigations
A cross-process navigation is used when a navigation requires a process
switch to occur, and no BrowsingContext replacement is required. This is a
common type of load when Fission is enabled, though it is also used
Fission is disabled.
These process changes are triggered by `DocumentLoadListener` when it
determines that a process switch is required. See that class's documentation
for more details.
(cross-group-navigations)=
### cross-group navigations
A cross-group navigation is used when the navigation's [response requires
a browsing context group switch](https://html.spec.whatwg.org/multipage/origin.html#browsing-context-group-switches-due-to-cross-origin-opener-policy).
These types of switches may or may not cause the process to change, but will
finish within a different `BrowsingContextGroup` than they started with.
Like [cross-process navigations](#cross-process-navigations), these navigations are triggered using
the process switching logic in `DocumentLoadListener`.
As the parent of a content browsing context cannot change due to a navigation,
only toplevel content browsing contexts can cross-group navigate. Navigations in
chrome browsing contexts [^chromebc] or content subframes only experience
either in-process or cross-process navigations.
As of the time of this writing, we currently trigger a cross-group navigation
in the following circumstances, though this may change in the future:
- If the [Cross-Origin-Opener-Policy](https://html.spec.whatwg.org/multipage/origin.html#the-cross-origin-opener-policy-header)
header is specified, and a mismatch is detected.
- When switching processes between the parent process, and a content process.
- When loading an extension document in a toplevel browsing context.
- When navigating away from a preloaded `about:newtab` document.
- When putting a `BrowsingContext` into BFCache for the session history
in-parent BFCache implementation. This will happen on most toplevel
navigations without opener relationships when the `fission.bfcacheInParent`
pref is enabled.
State which needs to be saved over cross-group navigations on
`BrowsingContext` instances is copied in the
`CanonicalBrowsingContext::ReplacedBy` method.
[^chromebc]: A chrome browsing context does **not** refer to pages with the system
principal loaded in the content area such as `about:preferences`.
Chrome browsing contexts are generally used as the root context in a chrome
window, such where `browser.xhtml` is loaded for a browser window.
All chrome browsing contexts exclusively load in the parent process and
cannot process switch when navigating.