Mobile/Fennec/Extensions/Electrolysis

Introduction

Fennec 2.0 will move the Electrolysis platform. This means that chrome windows (the main application window) and content windows (web content in browser tabs) will be in separate processes. This impacts application and add-on code in a few ways:

• Code in one process will not be able to directly access code in the other process.
• Inter process communication will use a message based system to communicate.

An example will help illustrate the affect of the changes. First, let's look at how code in the application (or add-on overlay) would access the DOM of a web page:

alert(gBrowser.contentDocument.title);                 // in Firefox
alert(Browser.selectedBrowser.contentDocument.title);  // in Fennec

This code will break because contentDocument will always return null (or perhaps it will throw an exception). In any case, it just won't work. Other properties of <browser> will also fail, such as contentWindow, ...(add more)...

Another common use-case is listening for DOM event bubble up from the web content:

gBrowser.addEventListener("DOMLinkAdded", myHandler, true); // in Firefox
Browser.selectedBrowser.addEventListener("DOMLinkAdded", myHandler, true); // in Fennec

This will no longer work. DOM events do not pass across the process boundary.

Glossary

Before diving into more details about how multi-process works in Mozilla, let's create a glossary of terms:

• chrome: Any JS code that runs at a high level of privilege. This code has access to the Mozilla platform.
• content: A web page, including the HTML, JS and CSS. Code in this scope is sandboxed and has limited capabilities.
• process: An instance of a computer program that executed independently from other processes. Direct communication between processes is not allowed, but indirect communication, via messages is allowed.
• in-process: content is running in the same process as the main application.
• out-of-process: content is running in a separate process. This process does have chrome script, but does not have direct access to the main application.
• messaging system: A system built into all Mozilla processes that enables sending and receiving messages.
• browser: A XUL element that provides a surface for browsing web and chrome content. A browser can be set to allow multi-process support (<browser remote="true"/>) or traditional, in-process support (<browser />).
• message manager: See messaging system

Overview

You might be wondering how in the world any application code or add-on code is supposed to work in the world of multi-process. Mozilla has implemented a few different ways to help get your code working. The most powerful system is the IPC Messaging System. The Messaging System is used to pass messages and JSON data back and forth across the process boundary. The way to access the system is by using the MessageManager object.

MessageManager object is available to the chrome script in both processes, as well as JS XPCOM components too. See the MXR link for a full description of the interfaces. The API is slightly different though:

Main (application) Process

  void addMessageListener(in AString aMessage, in nsIFrameMessageListener aListener);
  void removeMessageListener(in AString aMessage, in nsIFrameMessageListener aListener);

  void sendAsyncMessage(in messageName, in JSON);

  void loadFrameScript(in AString aURL, in boolean aAllowDelayedLoad);

In the main process, window.messageManager is how you access the MessageManager. This manager can communicate to all browser child processes in the window's scope. You can also access an individual child process by using the browser.messageManager.

Child (content) Process

  void addMessageListener(in AString aMessage, in nsIFrameMessageListener aListener);
  void removeMessageListener(in AString aMessage, in nsIFrameMessageListener aListener);

  void sendAsyncMessage(in messageName, in JSON);
  void sendSyncMessage(in messageName, in JSON);

  readonly attribute nsIDOMWindow content;
  readonly attribute nsIDocShell docShell;

  void dump(in DOMString aStr);

In the child process, MessageManager is the root JS object, so you have direct access to all the members.

Note: You can also access in-process content using the same MessageManager API

Message Listeners

  /**
   * receiveMessage is called with one parameter, which has the following
   * properties:
   *   {
   *     name:    %message name%,
   *     sync:    %true or false%,
   *     target:  %browser%,
   *     json:    %json object or null%
   *   }
   *
   * if the message is synchronous, possible return value is sent back
   * as JSON.
   *
   * When the listener is called, 'this' value is the target of the message.
   */
  void receiveMessage(in Object aMessage);

Sending and receiving messages across processes is a lot like the window.postMessage system. Instead of events, the code deals with messages. Just like event listeners, message listeners can be implemented as JS objects or JS functions.

Examples

Working in XUL

Let's look at getting document title changes and <link> notifications using the messaging system.

The key to starting the whole system is loading a chrome script in the content process. The is done using the loadFrameScript method in the main process. Child process chrome scripts are loaded for each browser created.

main process code

function onWindowLoad(e) {
  // Register some listeners for messages sent from the content process
  messageManager.addMessageListener("MyCode:TitleChanged", titleChanged);
  messageManager.addMessageListener("MyCode:LinkAdded", linkAdded);

  messageManager.loadFrameScript("chrome://mycode/content/content.js", true);
}

function titleChanged(message) {
  // Pull the title out of the JSON payload of the messaage
  alert(message.json.title);
}

function linkAdded(message) {
  // Pull out some link state from the JSON payload of the message
  let type = message.json.type;
  let rel = mmessagejson.ref;
  let href = message.json.href;

  /* do something */
}

child process code

// this is content.js

function domTitleChanged(e) {
  // Send the title to the main application process
  let title = content.document.title;
  sendAsyncMessage("MyCode:TitleChanged", { title: title });
}

function domLinkAdded(e) {
  // Send the link state to the main application process
  let link = e.originalTarget;
  let json = {
    type: link.type,
    rel: link.rel,
    href: link.href
  };
  sendAsyncMessage("MyCode:LinkAdded", json);
}

addEventListener("DOMTitleChanged", domTitleChanged, false);
addEventListener("DOMLinkAdded", domLinkAdded, false);

Working in JS XPCOM

Components are only really loaded in the main application process, not in the child content process. If your component tries to listen for DOM events from the content, you need to refactor the code to use messages instead. Unlike XUL scripts, window.messageManager does not exist in components. Instead, you can access a global MessageManager service:

JS XPCOM code

function MyComponent() {
  this.messageManager = Cc["@mozilla.org/globalmessagemanager;1"]
                        .getService(Ci.nsIChromeFrameMessageManager);
  this.messageManager.loadFrameScript("chrome://mycode/content/content.js", true);
  this.messageManager.addMessageListener("MyCode:TitleChanged", this);
}

MyComponent.prototype = {
  classDescription: "My Component",
  contractID: "@example.org/mycomponent;1",
  classID: Components.ID("{some-uuid-goes-here}"),
  QueryInterface: XPCOMUtils.generateQI([Ci.nsIMyComponent, Ci.nsIFrameMessageListener]),

  receiveMessage: function(message) {
    if (message.name == "MyCode:TitleChanged")
      // do something with the title
  }
}

The example uses the same child process script as the previous example. Note that we use the receiveMessage style of handling the messages, instead of using a JS function.

Mixing In-Process and Out-of-Process Content

As shown in the above diagram, it is possible to have both in-process browsers and out-of-process browsers in the same application. In fact Fennec uses this to support about: pages, which require full chrome privileges. In-process browser work the same way content has always worked in Mozilla. The chrome application code has full access to the content.

However, when creating an application that mixes in-process and out-of-process content, you would be wise to access both types using the MessageManager. It will keep your code cleaner and easier to maintain.

Determining Script Process Type

Usually, your code never needs to know if it's running in the main application process or in a child content process. However, if there is some reason you do need to figure this out, use nsIXULRuntime.processType:

• nsIXULRuntime.PROCESS_TYPE_DEFAULT (0) means you are running in the main application process.
• nsIXULRuntime.PROCESS_TYPE_CONTENT (2) means you are running in a child content process.