Compare Revisions

Jetpack Processes

Revision 30545:

Revision 30545 by Avarma on

Revision 30546:

Revision 30546 by Avarma on

Jetpack Processes
Jetpack Processes

Revision 30545
Revision 30546
n8      {{ Xpcomapi() }}n8      Jetpack processes are created by <code><a href="/en/nsIJetp
 >ackService">nsIJetpackService</a></code> interfaces, and their pa
 >rent chrome process communicates with them via a <code><a href="/
 >en/nsIJetpackService">nsIJetpack</a></code> interface.
9    </p>
10    <h3 name="Summary">
11      Summary
12    </h3>
13    <p>
14      The <code>nsIJetpack</code> interface enables communication
> between the chrome process and a remote <a href="/en/Jetpack_Pro 
>cesses">Jetpack process</a>. 
n17      {{ InterfaceStatus("nsIJetpack", "js/jetpack/nsIJetpack.idln11      These processes are relatively lightweight, don't have acce
>", "unfrozen", "Mozilla 2.0", "yes") }}>ss to XPCOM, and can innately do little other than compute. Messa
 >ging facilities that allow them to communicate with their parent 
 >chrome process are the only means by which they can be endowed wi
 >th any real power.
nn13    <h2 name="Privileged_APIs">
14      Privileged APIs
15    </h2>
n20      Inherits from: {{ Interface("nsISupports") }}n17      When script is evaluated in a Jetpack process via a call to
 > <code><a href="/en/nsIJetpack#evalScript()">nsIJetpack.evalScrip
 >t()</a></code>, the script's global scope is endowed with the fol
 >lowing privileged APIs:
n22    <h2 name="Method_overview">n
23      Method overview
24    </h2>
25    <table class="standard-table">
26      <tbody>
27        <tr>
28          <td>
29            <code>void <a href="#sendMessage()">sendMessage</a>(i
>n AString aMessageName /* [optional] in jsval v1, [optional] in j 
>sval v2, ... */);</code> 
30          </td>
31        </tr>
32        <tr>
33          <td>
34            <code>void <a href="#registerReceiver()">registerRece
>iver</a>(in AString aMessageName, in jsval aReceiver);</code> 
35          </td>
36        </tr>
37        <tr>
38          <td>
39            <code>void <a href="#unregisterReceiver()">unregister
>Receiver</a>(in AString aMessageName, in jsval aReceiver);</code> 
40          </td>
41        </tr>
42        <tr>
43          <td>
44            <code>void <a href="#unregisterReceivers()">unregiste
>rReceivers</a>(in AString aMessageName);</code> 
45          </td>
46        </tr>
47        <tr>
48          <td>
49            <code>void <a href="#evalScript()">evalScript</a>(in 
>AString aScript);</code> 
50          </td>
51        </tr>
52        <tr>
53          <td>
54            <code>nsIVariant <a href="#createHandle()">createHand
55          </td>
56        </tr>
57        <tr>
58          <td>
59            <code>void <a href="#destroy()">destroy</a>();</code>
60          </td>
61        </tr>
62      </tbody>
63    </table>
64    <h2 name="Methods">
65      Methods
66    </h2>
67    <h3 name="sendMessage()">
68      sendMessage()
69    </h3>
70    <p>
71      This method asynchronously sends a message to the Jetpack p
72    </p>
73    <pre class="eval">
74void sendMessage(in AString aMessageName
75                 /* [optional] in jsval v1,
76                    [optional] in jsval v2,
77                    ... */);
79    <h6 name="Parameters_5">
80      Parameters
81    </h6>
n84        <code>aMessageName</code>n21        <code>sendMessage(aMessageName [, v1 [, v2 [, ...]]])</co
n87        The name of the message to send.n24        Similar to <code><a href="/en/nsIJetpack#sendMessage()">n
 >sIJetpack.sendMessage()</a></code>, this function asynchronously 
 >sends a message to the chrome process.
25      </dd>
26      <dt>
27        <code>callMessage(aMessageName [, v1 [, v2 [, ...]]])</co
28      </dt>
29      <dd>
30        This function is like <code>sendMessage()</code> but send
 >s the message synchronously. It returns an <code>Array</code> who
 >se elements are the return values of each receiver in the chrome 
 >process that was triggered by the message.
31      </dd>
32      <dt>
33        <code>registerReceiver(aMessageName, aReceiver)</code>
34      </dt>
35      <dd>
36        Similar to <code><a href="/en/nsIJetpack#registerReceiver
 >()">nsIJetpack.registerReceiver()</a></code>, this function regis
 >ters a callback that's triggered when the chrome process sends a 
 >message with the given name.
37      </dd>
38      <dt>
39        <code>unregisterReceiver(aMessageName, aReceiver)</code>
40      </dt>
41      <dd>
42        Similar to <code><a href="/en/nsIJetpack#unregisterReceiv
 >er()">nsIJetpack.unregisterReceiver()</a></code>, this function u
 >nregisters a callback previously registered with <code>registerRe
43      </dd>
44      <dt>
45        <code>unregisterReceivers(aMessageName)</code>
46      </dt>
47      <dd>
48        Similar to <code><a href="/en/nsIJetpack#unregisterReceiv
 >ers()">nsIJetpack.unregisterReceivers()</a></code>, this function
 > unregisters all callbacks for the given message name.
49      </dd>
50      <dt>
51        <code>createHandle()</code>
52      </dt>
53      <dd>
54        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.
55      </dd>
56      <dt>
57        <code>createSandbox()</code>
58      </dt>
59      <dd>
60        This creates a new JavaScript sandbox and returns its glo
 >bal scope. This global scope does <em>not</em> contain privileged
 > APIs, or any non-standard JavaScript objects for that matter, th
 >ough new globals can be endowed by simply attaching them to the g
 >lobal scope as properties.
61      </dd>
62      <dt>
63        <code>evalInSandbox(aSandbox, aScript)</code>
64      </dt>
65      <dd>
66        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 purpos
67      </dd>
68      <dt>
69        <code>gc()</code>
70      </dt>
71      <dd>
72        Synchronously performs garbage collection.
nn75    <h2 name="Handles">
76      Handles
77    </h2>
78    <p>
79      Messages that communicate between the browser and jetpack p
 >rocess may contain only serializable (JSON) data and <em>handles<
 >/em>. A handle can be used to provide context for messages. Eithe
 >r 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:
80    </p>
n92        <code>v1, v2, ...</code>n83        <code>invalidate()</code>
n95        JavaScript values to send with the message; they must be n86        Invalidates the handle. Either process may invalidate a h
>either JSON-serializable types or <a href="/en/Jetpack_Processes#>andle when it is no longer useful.
n97    </dl>n
98    <h3 name="registerReceiver()">
99      registerReceiver()
100    </h3>
101    <p>
102      This registers a callback to be triggered whenever the Jetp
>ack process sends a particular message. 
103    </p>
104    <pre class="eval">
105void registerReceiver(in AString aMessageName,
106                      in jsval aReceiver);
108    <h6 name="Parameters_5">
109      Parameters
110    </h6>
111    <dl>
n113        <code>aMessageName</code>n89        <code>createHandle()</code>
n116        The name of the message from the Jetpack process on whichn92        Creates a child handle which becomes invalid when its par
> the callback is triggered.>ent does. This is useful for associating handles to the lifetime 
 >of a particular window, context menu, or other element, and helpi
 >ng ensure that they do not leak.
n118    </dl>n
119    <dl>
n121        <code>aReceiver</code>n95        <code>parent</code>
n124        A JavaScript function. The first argument passed to it isn98        The parent handle of the object, if any. Read-only.
> the name of the message, and all arguments following it are eith 
>er JSON-serializable types or handles. If the message was sent sy 
>nchronously from the Jetpack process via <code>callMessage()</cod 
>e>, then the return value of this function is passed back to the  
>Jetpack process. 
99      </dd>
100      <dt>
101        <code>isValid</code>
102      </dt>
103      <dd>
104        Whether the handle is still valid or not. Read-only.
105      </dd>
106      <dt>
107        <code>isRooted</code>
108      </dt>
109      <dd>
110        Whether the handle is GC rooted or not. Read-write.
111      </dd>
112      <dt>
113        <code>onInvalidate</code>
114      </dt>
115      <dd>
116        A callback to call when the handle is garbage collected, 
 >either through an explicit call to <code>invalidate()</code> or b
 >eing unrooted and then unreachable. The callback is only called f
 >rom the process that the handle <em>wasn't</em> garbage collected
 > in. Read-write.
n128      Note that multiple callbacks may be registered for the samen120      A handle that is created without a parent stays alive until
> message; they will all be triggered.> it is either explicitly invalidated or unrooted.
n130    <h3 name="unregisterReceiver()">n122    <h2 name="History">
131      unregisterReceiver()123      History
132    </h3>124    </h2>
n134      This unregisters a callback previously registered with <codn
135    </p>
136    <pre class="eval">
137void unregisterReceiver(in AString aMessageName,
138                        in jsval aReceiver);
140    <h6 name="Parameters_5">
141      Parameters
142    </h6>
143    <dl>
144      <dt>
145        <code>aMessageName</code>
146      </dt>
147      <dd>
148        The name of the message on which the callback should no l
>onger be triggered. 
149      </dd>
150    </dl>
151    <dl>
152      <dt>
153        <code>aReceiver</code>
154      </dt>
155      <dd>
156        The JavaScript function that should no longer be triggere
157      </dd>
158    </dl>
159    <h3 name="unregisterReceivers()">
160      unregisterReceivers()
161    </h3>
162    <p>
163      This unregisters all callbacks previously registered with <
>code>registerReceiver()</code> for a particular message. 
164    </p>
165    <pre class="eval">
166void unregisterReceivers(in AString aMessageName);
168    <h6 name="Parameters_5">
169      Parameters
170    </h6>
171    <dl>
172      <dt>
173        <code>aMessageName</code>
174      </dt>
175      <dd>
176        The name of the message to unregister all callbacks from.
177      </dd>
178    </dl>
179    <h3 name="evalScript()">
180      evalScript()
181    </h3>
182    <p>
183      This asynchronously sends code to the Jetpack process for e
184    </p>
185    <pre class="eval">
186void evalScript(in AString aScript);
188    <h6 name="Parameters_5">
189      Parameters
190    </h6>
191    <dl>
192      <dt>
193        <code>aScript</code>
194      </dt>
195      <dd>
196        The full contents of the script to evaluate in the Jetpac
>k process. 
197      </dd>
198    </dl>
199    <p>
200      The code will be evaluated using at least JavaScript 1.8.1.
201    </p>
202    <p>
203      When evaluated, the script's global scope will include all 
><a href="/en/Jetpack_Processes#Privileged_APIs">privileged APIs</ 
204    </p>
205    <p>
206      Individual lines of the form <code>//@line 1 "foo.js"</code
>> can be used to specify filename and line number information for 
> debugging purposes. 
207    </p>
208    <h3 name="createHandle()">
209      createHandle()
210    </h3>
211    <p>
212      This creates an opaque handle that can transparently be exc
>hanged between processes. 
213    </p>
214    <pre class="eval">
215nsIVariant createHandle();
217    <h6 name="Return_value">
218      Return value
219    </h6>
220    <p>
221      The new <a href="/en/Jetpack_Processes#Handles">handle</a>.
222    </p>
223    <h3 name="destroy()">
224      destroy()
225    </h3>
226    <p>
227      This terminates the Jetpack process.
228    </p>
229    <pre class="eval">
230void destroy();
232    <h3 name="History">
233      History
234    </h3>
235    <p>
236      See {{ Bug("556846") }} for details.126      See {{ Bug("556846") }} and {{ Bug("578821") }} for details
t250      <li>t140      <li>{{ Interface("nsIJetpack") }}
251        <a href="/en/Jetpack_Processes">Jetpack Processes</a>

Back to History