Jetpack Processes

  • Revision slug: Jetpack_Processes
  • Revision title: Jetpack Processes
  • Revision id: 30546
  • Created:
  • Creator: Avarma
  • Is current revision? No
  • Comment 565 words added, 453 words removed; page display name reset to default

Revision Content

Jetpack processes are created by nsIJetpackService interfaces, and their parent chrome process communicates with them via a nsIJetpack interface.

These processes are relatively lightweight, don't have access to XPCOM, and can innately do little other than compute. Messaging facilities that allow them to communicate with their parent chrome process are the only means by which they can be endowed with any real power.

Privileged APIs

When script is evaluated in a Jetpack process via a call to nsIJetpack.evalScript(), the script's global scope is endowed with the following privileged APIs:

sendMessage(aMessageName [, v1 [, v2 [, ...]]])
Similar to nsIJetpack.sendMessage(), this function asynchronously sends a message to the chrome process.
callMessage(aMessageName [, v1 [, v2 [, ...]]])
This function is like sendMessage() but sends the message synchronously. It returns an Array whose elements are the return values of each receiver in the chrome process that was triggered by the message.
registerReceiver(aMessageName, aReceiver)
Similar to nsIJetpack.registerReceiver(), this function registers a callback that's triggered when the chrome process sends a message with the given name.
unregisterReceiver(aMessageName, aReceiver)
Similar to nsIJetpack.unregisterReceiver(), this function unregisters a callback previously registered with registerReceiver().
unregisterReceivers(aMessageName)
Similar to nsIJetpack.unregisterReceivers(), this function unregisters all callbacks for the given message name.
createHandle()
Similar to nsIJetpack.createHandle(), this function creates a new handle and returns it.
createSandbox()
This creates a new JavaScript sandbox and returns its global scope. This global scope does not contain privileged APIs, or any non-standard JavaScript objects for that matter, though new globals can be endowed by simply attaching them to the global scope as properties.
evalInSandbox(aSandbox, aScript)
Evaluates the given script contents in the given sandbox's global scope. At minimum, JavaScript 1.8.1 is used. Individual lines of the form //@line 1 "foo.js" can be used to specify filename and line number information for debugging purposes.
gc()
Synchronously performs garbage collection.

Handles

Messages that communicate between the browser and jetpack process may contain only serializable (JSON) data and handles. A handle can be used to provide context for messages. Either the browser or the jetpack implementation may create a handle. A handle keeps any arbitrary properties attached to it alive, and has the following native methods and properties:

invalidate()
Invalidates the handle. Either process may invalidate a handle when it is no longer useful.
createHandle()
Creates a child handle which becomes invalid when its parent does. This is useful for associating handles to the lifetime of a particular window, context menu, or other element, and helping ensure that they do not leak.
parent
The parent handle of the object, if any. Read-only.
isValid
Whether the handle is still valid or not. Read-only.
isRooted
Whether the handle is GC rooted or not. Read-write.
onInvalidate
A callback to call when the handle is garbage collected, either through an explicit call to invalidate() or being unrooted and then unreachable. The callback is only called from the process that the handle wasn't garbage collected in. Read-write.

A handle that is created without a parent stays alive until it is either explicitly invalidated or unrooted.

History

See {{ Bug("556846") }} and {{ Bug("578821") }} for details.

Sample Code

For example code, check out the unit tests.

See also

  • {{ Interface("nsIJetpackService") }}
  • {{ Interface("nsIJetpack") }}

Revision Source

<p>Jetpack processes are created by <code><a href="/en/nsIJetpackService">nsIJetpackService</a></code> interfaces, and their parent chrome process communicates with them via a <code><a href="/en/nsIJetpackService">nsIJetpack</a></code> interface.</p>
<p>These processes are relatively lightweight, don't have access to XPCOM, and can innately do little other than compute. Messaging facilities that allow them to communicate with their parent chrome process are the only means by which they can be endowed with any real power.</p>
<h2 name="Privileged_APIs">Privileged APIs</h2>
<p>When script is evaluated in a Jetpack process via a call to <code><a href="/en/nsIJetpack#evalScript()">nsIJetpack.evalScript()</a></code>, the script's global scope is endowed with the following privileged APIs:</p>
<dl> <dt><code>sendMessage(aMessageName [, v1 [, v2 [, ...]]])</code></dt> <dd>Similar to <code><a href="/en/nsIJetpack#sendMessage()">nsIJetpack.sendMessage()</a></code>, this function asynchronously sends a message to the chrome process.</dd> <dt><code>callMessage(aMessageName [, v1 [, v2 [, ...]]])</code></dt> <dd>This function is like <code>sendMessage()</code> but sends the message synchronously. It returns an <code>Array</code> whose elements are the return values of each receiver in the chrome process that was triggered by the message.</dd> <dt><code>registerReceiver(aMessageName, aReceiver)</code></dt> <dd>Similar to <code><a href="/en/nsIJetpack#registerReceiver()">nsIJetpack.registerReceiver()</a></code>, this function registers a callback that's triggered when the chrome process sends a message with the given name.</dd> <dt><code>unregisterReceiver(aMessageName, aReceiver)</code></dt> <dd>Similar to <code><a href="/en/nsIJetpack#unregisterReceiver()">nsIJetpack.unregisterReceiver()</a></code>, this function unregisters a callback previously registered with <code>registerReceiver()</code>.</dd> <dt><code>unregisterReceivers(aMessageName)</code></dt> <dd>Similar to <code><a href="/en/nsIJetpack#unregisterReceivers()">nsIJetpack.unregisterReceivers()</a></code>, this function unregisters all callbacks for the given message name.</dd> <dt><code>createHandle()</code></dt> <dd>Similar to <code><a href="/en/nsIJetpack#createHandle()">nsIJetpack.createHandle()</a></code>, this function creates a new <a href="#Handles">handle</a> and returns it.</dd> <dt><code>createSandbox()</code></dt> <dd>This creates a new JavaScript sandbox and returns its global scope. This global scope does <em>not</em> contain privileged APIs, or any non-standard JavaScript objects for that matter, though new globals can be endowed by simply attaching them to the global scope as properties.</dd> <dt><code>evalInSandbox(aSandbox, aScript)</code></dt> <dd>Evaluates the given script contents in the given sandbox's global scope. At minimum, JavaScript 1.8.1 is used. Individual lines of the form <code>//@line 1 "foo.js"</code> can be used to specify filename and line number information for debugging purposes.</dd> <dt><code>gc()</code></dt> <dd>Synchronously performs garbage collection.</dd>
</dl> <h2 name="Handles">Handles</h2> <p>Messages that communicate between the browser and jetpack process may contain only serializable (JSON) data and <em>handles</em>. A handle can be used to provide context for messages. Either the browser or the jetpack implementation may create a handle. A handle keeps any arbitrary properties attached to it alive, and has the following native methods and properties:</p> <dl> <dt><code>invalidate()</code></dt> <dd>Invalidates the handle. Either process may invalidate a handle when it is no longer useful.</dd> <dt><code>createHandle()</code></dt> <dd>Creates a child handle which becomes invalid when its parent does. This is useful for associating handles to the lifetime of a particular window, context menu, or other element, and helping ensure that they do not leak.</dd> <dt><code>parent</code></dt> <dd>The parent handle of the object, if any. Read-only.</dd> <dt><code>isValid</code></dt> <dd>Whether the handle is still valid or not. Read-only.</dd> <dt><code>isRooted</code></dt> <dd>Whether the handle is GC rooted or not. Read-write.</dd> <dt><code>onInvalidate</code></dt> <dd>A callback to call when the handle is garbage collected, either through an explicit call to <code>invalidate()</code> or being unrooted and then unreachable. The callback is only called from the process that the handle <em>wasn't</em> garbage collected in. Read-write.</dd>
</dl> <p>A handle that is created without a parent stays alive until it is either explicitly invalidated or unrooted.</p> <h2 name="History">History</h2> <p>See {{ Bug("556846") }} and {{ Bug("578821") }} for details.</p> <h2 name="Sample_Code">Sample Code</h2>
<p>For example code, check out the <a class=" external" href="http://mxr.mozilla.org/mozilla-central/source/js/jetpack/tests/unit/">unit tests</a>.</p> <h2 name="See_also">See also</h2>
<ul> <li>{{ Interface("nsIJetpackService") }}</li> <li>{{ Interface("nsIJetpack") }}</li>
</ul>
Revert to this revision