mozilla

Compare Revisions

Jetpack Processes

Change Revisions

Revision 30544:

Revision 30544 by Avarma on

Revision 30545:

Revision 30545 by Avarma on

Title:
Jetpack Processes
Jetpack Processes
Slug:
Jetpack_Processes
Jetpack_Processes
Tags:
Jetpack
Jetpack
Content:

Revision 30544
Revision 30545
n8      Jetpack processes are created by <code><a href="/en/nsIJetpn8      {{ Xpcomapi() }}
>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    <p>9    </p>
11      These processes are relatively lightweight, don't have acce10    <h3 name="Summary">
>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. 
11      Summary
12    </h3>
12    </p>13    <p>
13    <h2 name="Privileged_APIs">14      The <code>nsIJetpack</code> interface enables communication
 > between the chrome process and a remote <a href="/en/Jetpack_Pro
 >cesses">Jetpack process</a>.
14      Privileged APIs
15    </h2>
16    <p>15    </p>
17      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: 
18    </p>16    <p>
17      {{ InterfaceStatus("nsIJetpack", "js/jetpack/nsIJetpack.idl
 >", "unfrozen", "Mozilla 2.0", "yes") }}
18    </p>
19    <dl>19    <p>
20      Inherits from: {{ Interface("nsISupports") }}
21    </p>
22    <h2 name="Method_overview">
23      Method overview
24    </h2>
25    <table class="standard-table">
26      <tbody>
20      <dt>27        <tr>
21        <code>sendMessage(aMessageName [, v1 [, v2 [, ...]]])</co28          <td>
>de> 
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
 >le</a>();</code>
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
 >rocess.
72    </p>
73    <pre class="eval">
74void sendMessage(in AString aMessageName
75                 /* [optional] in jsval v1,
76                    [optional] in jsval v2,
77                    ... */);
78</pre>
79    <h6 name="Parameters_5">
80      Parameters
81    </h6>
82    <dl>
22      </dt>83      <dt>
23      <dd>84        <code>aMessageName</code>
24        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>85      </dt>
27        <code>callMessage(aMessageName [, v1 [, v2 [, ...]]])</co
>de> 
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>86      <dd>
32      <dt>87        The name of the message to send.
33        <code>registerReceiver(aMessageName, aReceiver)</code>
34      </dt>
35      <dd>88      </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>89    </dl>
38      <dt>90    <dl>
39        <code>unregisterReceiver(aMessageName, aReceiver)</code>
40      </dt>91      <dt>
41      <dd>92        <code>v1, v2, ...</code>
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 
>ceiver()</code>. 
43      </dd>
44      <dt>93      </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>94      <dd>
50      <dt>95        JavaScript values to send with the message; they must be 
 >either JSON-serializable types or <a href="/en/Jetpack_Processes#
 >Handles">handles</a>.
51        <code>createHandle()</code>
52      </dt>
53      <dd>96      </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>97    </dl>
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);
107</pre>
108    <h6 name="Parameters_5">
109      Parameters
110    </h6>
56      <dt>111    <dl>
57        <code>createSandbox()</code>
58      </dt>112      <dt>
59      <dd>113        <code>aMessageName</code>
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>114      </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 
>es. 
67      </dd>115      <dd>
68      <dt>116        The name of the message from the Jetpack process on which
 > the callback is triggered.
69        <code>gc()</code>
70      </dt>
71      <dd>117      </dd>
72        Synchronously performs garbage collection.
73      </dd>
74    </dl>
75    <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>
81    <dl>118    </dl>
82      <dt>119    <dl>
83        <code>invalidate()</code>
84      </dt>120      <dt>
85      <dd>121        <code>aReceiver</code>
86        Invalidates the handle. Either process may invalidate a h
>andle when it is no longer useful. 
87      </dd>
88      <dt>122      </dt>
89        <code>createHandle()</code>
90      </dt>
91      <dd>
92        Creates a child handle which becomes invalid when its par
>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. 
93      </dd>123      <dd>
94      <dt>124        A JavaScript function. The first argument passed to it is
 > 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.
95        <code>parent</code>
96      </dt>
97      <dd>125      </dd>
98        The parent handle of the object, if any. Read-only.
99      </dd>126    </dl>
127    <p>
128      Note that multiple callbacks may be registered for the same
 > message; they will all be triggered.
129    </p>
130    <h3 name="unregisterReceiver()">
131      unregisterReceiver()
132    </h3>
133    <p>
134      This unregisters a callback previously registered with <cod
 >e>registerReceiver()</code>.
135    </p>
136    <pre class="eval">
137void unregisterReceiver(in AString aMessageName,
138                        in jsval aReceiver);
139</pre>
140    <h6 name="Parameters_5">
141      Parameters
142    </h6>
100      <dt>143    <dl>
101        <code>isValid</code>
102      </dt>144      <dt>
103      <dd>145        <code>aMessageName</code>
104        Whether the handle is still valid or not. Read-only.
105      </dd>
106      <dt>146      </dt>
107        <code>isRooted</code>
108      </dt>
109      <dd>
110        Whether the handle is GC rooted or not. Read-write.
111      </dd>147      <dd>
112      <dt>148        The name of the message on which the callback should no l
 >onger be triggered.
113        <code>onInvalidate</code>
114      </dt>
115      <dd>149      </dd>
116        A callback to call when the handle is garbage collected, 150    </dl>
>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. 
151    <dl>
152      <dt>
153        <code>aReceiver</code>
154      </dt>
117      </dd>155      <dd>
156        The JavaScript function that should no longer be triggere
 >d.
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);
167</pre>
168    <h6 name="Parameters_5">
169      Parameters
170    </h6>
118    </dl>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>
119    <p>178    </dl>
120      A handle that is created without a parent stays alive until179    <h3 name="evalScript()">
> it is either explicitly invalidated or unrooted. 
180      evalScript()
181    </h3>
121    </p>182    <p>
183      This asynchronously sends code to the Jetpack process for e
 >valuation.
184    </p>
185    <pre class="eval">
186void evalScript(in AString aScript);
187</pre>
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</
 >a>.
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();
216</pre>
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();
231</pre>
122    <h2 name="History">232    <h3 name="History">
n124    </h2>n234    </h3>
235    <p>
236      See {{ Bug("556846") }} for details.
125    <p>237    </p>
126      See {{ Bug("556846") }} and {{ Bug("578821") }} for details238    <h2 name="Sample_Code">
>. 
239      Sample Code
240    </h2>
241    <p>
242      For example code, check out the <a class=" external" href="
 >http://mxr.mozilla.org/mozilla-central/source/js/jetpack/tests/un
 >it/">unit tests</a>.
t134      <li>{{ Interface("nsIJetpack") }}t250      <li>
251        <a href="/en/Jetpack_Processes">Jetpack Processes</a>

Back to History