[chromium-blink-merge.git] / native_client_sdk / src / doc / devguide / coding / progress-events.rst
| blob | af0803f35e003d446cbbc2c64d3e101f8f1b1d8c |
1 .. _devcycle-progress-events:
3 ###############
4 Progress Events
5 ###############
7 .. contents::
8 :local:
9 :backlinks: none
10 :depth: 2
12 There are five types of events that developers can respond to in Native Client:
13 progress, message, view change, focus, and input events (each described in the
14 glossary below). This chapter describes how to monitor progress events (events
15 that occur during the loading and execution of a Native Client module). This
16 chapter assumes you are familiar with the material presented in the
17 :doc:`Technical Overview <../../overview>`.
19 .. Note::
20 :class: note
22 The load_progress example illustrates progress event handling. You can find
23 this code in the ``/examples/tutorial/load_progress/`` directory in the Native
24 Client SDK download.
26 Module loading and progress events
27 ==================================
29 The Native Client runtime reports a set of state changes during the module
30 loading process by means of DOM progress events. This set of events is a direct
31 port of the proposed W3C `Progress Events
32 <http://www.w3.org/TR/progress-events/>`_ standard (except for the ``crash``
33 event which is an extension of the W3C standard). The following table lists the
34 events types reported by the Native Client runtime:
36 +-------------+--------------------+-----------+---------------+---------------+
37 | Event | Description | Number of | When event is | How you might |
38 | | | times | triggered | react to |
39 | | | triggered | | event |
40 +=============+====================+===========+===============+===============+
41 |``loadstart``| Native Client has | once | This is the | Display a |
42 | | started to load a | | first | status |
43 | | Native Client | | progress | message, such |
44 | | module. | | event | as |
45 | | | | triggered | "Loading..." |
46 | | | | after the | |
47 | | | | Native Client | |
48 | | | | module is | |
49 | | | | instantiated | |
50 | | | | and | |
51 | | | | initialized. | |
52 +-------------+--------------------+-----------+---------------+---------------+
53 |``progress`` | Part of the module | zero or | After | Display a |
54 | | has been loaded. | more | ``loadstart`` | progress bar. |
55 | | | | has been | |
56 | | | | dispatched. | |
57 +-------------+--------------------+-----------+---------------+---------------+
58 |``error`` | The Native Client | zero or | After the | Inform user |
59 | | module failed to | once | last | that the |
60 | | start execution | | ``progress`` | application |
61 | | (includes any | | event has | failed to |
62 | | error before or | | been | load. |
63 | | during | | dispatched, | |
64 | | initialization of | | or after | |
65 | | the module). The | | ``loadstart`` | |
66 | | ``lastError`` | | if no | |
67 | | attribute | | ``progress`` | |
68 | | (mentioned later) | | event was | |
69 | | provides details | | dispatched. | |
70 | | on the error | | | |
71 | | (initialization | | | |
72 | | failed, sel_ldr | | | |
73 | | did not start, | | | |
74 | | and so on). | | | |
75 +-------------+--------------------+-----------+---------------+---------------+
76 |``abort`` | Loading of the | zero or | After the | It's not |
77 | | Native Client | once | last | likely you |
78 | | module was | | ``progress`` | will want to |
79 | | aborted by the | | event has | respond to |
80 | | user. | | been | this event. |
81 | | | | dispatched, | |
82 | | | | or after | |
83 | | | | ``loadstart`` | |
84 | | | | if no | |
85 | | | | ``progress`` | |
86 | | | | event was | |
87 | | | | dispatched. | |
88 +-------------+--------------------+-----------+---------------+---------------+
89 |``load`` | The Native Client | zero or | After the | Remove the |
90 | | module was | once | last | progress bar. |
91 | | successfully | | ``progress`` | |
92 | | loaded, and | | event has | |
93 | | execution was | | been | |
94 | | started. (The | | dispatched, | |
95 | | module was | | or after | |
96 | | initialized | | ``loadstart`` | |
97 | | successfully.) | | if no | |
98 | | | | ``progress`` | |
99 | | | | event was | |
100 | | | | dispatched. | |
101 +-------------+--------------------+-----------+---------------+---------------+
102 |``loadend`` | Loading of the | once | After an | Indicate |
103 | | Native Client | | ``error``, | loading is |
104 | | module has | | ``abort``, or | over |
105 | | stopped. Load | | ``load`` | (regardless |
106 | | succeeded | | event was | of failure or |
107 | | (``load``), | | dispatched. | not). |
108 | | failed | | | |
109 | | (``error``), or | | | |
110 | | was aborted | | | |
111 | | (``abort``). | | | |
112 +-------------+--------------------+-----------+---------------+---------------+
113 |``crash`` | The Native Client | zero or | After a | Notify user |
114 | | module is not | once | ``loadend``. | that the |
115 | | responding (died | | | module did |
116 | | on an | | | something |
117 | | ``assert()`` or | | | illegal. |
118 | | ``exit()``) after | | | |
119 | | a successful | | | |
120 | | load. This event | | | |
121 | | is unique to | | | |
122 | | Native Client and | | | |
123 | | is not part of | | | |
124 | | the W3C Progress | | | |
125 | | Events standard. | | | |
126 | | The ``exitStatus`` | | | |
127 | | attribute provides | | | |
128 | | the numeric exit | | | |
129 | | status value. | | | |
130 +-------------+--------------------+-----------+---------------+---------------+
132 The sequence of events for a successful module load is as follows:
134 =============================== ===============================
135 Event is dispatched ... then this task is attempted
136 =============================== ===============================
137 ``loadstart`` load the manifest file
138 ``progress`` (first time) load the module
139 ``progress`` (subsequent times)
140 ``load`` start executing the module
141 ``loadend``
142 =============================== ===============================
144 Errors that occur during loading are logged to the JavaScript console in Google
145 Chrome (select the menu icon |menu-icon| > Tools > JavaScript console).
147 .. |menu-icon| image:: /images/menu-icon.png
149 Handling progress events
150 ========================
152 You should add event listeners in a ``<script>`` element to listen for these
153 events before the ``<embed>`` element is parsed. For example, the following code
154 adds a listener for the ``load`` event to a parent ``<div>`` element that also
155 contains the Native Client ``<embed>`` element. First, the listener is
156 attached. Then, when the listener ``<div>`` receives the ``load`` event, the
157 JavaScript ``moduleDidLoad()`` function is called. The following code is
158 excerpted from the example in ``getting_started/part1/``:
160 .. naclcode::
162 <!--
163 Load the published pexe.
164 Note: Since this module does not use any real-estate in the browser, its
165 width and height are set to 0.
167 Note: The <embed> element is wrapped inside a <div>, which has both a 'load'
168 and a 'message' event listener attached. This wrapping method is used
169 instead of attaching the event listeners directly to the <embed> element to
170 ensure that the listeners are active before the NaCl module 'load' event
171 fires. This also allows you to use PPB_Messaging.PostMessage() (in C) or
172 pp::Instance.PostMessage() (in C++) from within the initialization code in
173 your module.
174 -->
175 <div id="listener">
176 <script type="text/javascript">
177 var listener = document.getElementById('listener');
178 listener.addEventListener('load', moduleDidLoad, true);
179 listener.addEventListener('message', handleMessage, true);
180 </script>
182 <embed id="hello_tutorial"
183 width=0 height=0
184 src="hello_tutorial.nmf"
185 type="application/x-pnacl" />
186 </div>
188 Event listeners can be added to any DOM object. Since listeners set at the
189 outermost scope capture events for their contained elements, you can set
190 listeners on outer elements (including the ``<body>`` element) to handle events
191 from inner elements. For more information, see the W3 specifications for `event
192 flow capture
193 <http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-flow-capture>`_ and
194 `event listener registration
195 <http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-registration>`_.
197 Displaying load status
198 ======================
200 One common response to progress events is to display the percentage of the
201 module that has been loaded. In the load_progress example, when the ``progress``
202 event is triggered the ``moduleLoadProgress`` function is called. This function
203 uses the ``lengthComputable``, ``loaded``, and ``total`` attributes (described
204 in the proposed W3C `Progress Events <http://www.w3.org/TR/progress-events/>`_
205 standard) of the event to calculate the percentage of the module that has
206 loaded.
208 .. naclcode::
210 function moduleLoadProgress(event) {
211 var loadPercent = 0.0;
212 var loadPercentString;
213 if (event.lengthComputable && event.total > 0) {
214 loadPercent = event.loaded / event.total * 100.0;
215 loadPercentString = loadPercent + '%';
216 common.logMessage('progress: ' + event.url + ' ' + loadPercentString +
217 ' (' + event.loaded + ' of ' + event.total + ' bytes)');
218 } else {
219 // The total length is not yet known.
220 common.logMessage('progress: Computing...');
221 }
222 }
224 The ``lastError`` attribute
225 ===========================
227 The ``<embed>`` element has a ``lastError`` attribute that is set to an
228 informative string whenever a load failure (an ``error`` or ``abort`` event)
229 occurs.
231 The following code adds an event listener before the ``<embed>`` element to
232 capture and handle an error in loading the Native Client module. The
233 ``handleError()`` function listens for an ``error`` event. When an error occurs,
234 this function prints the contents of the ``lastError`` attribute
235 (``embed_element.lastError``) as an alert.
237 .. naclcode::
239 function domContentLoaded(name, tc, config, width, height) {
240 var listener = document.getElementById('listener');
241 ...
242 listener.addEventListener('error', moduleLoadError, true);
243 ...
244 common.createNaClModule(name, tc, config, width, height);
245 }
247 function moduleLoadError() {
248 common.logMessage('error: ' + common.naclModule.lastError);
249 }
251 The ``readyState`` attribute
252 ============================
254 You can use the ``readyState`` attribute to monitor the loading process. This
255 attribute is particularly useful if you don't care about the details of
256 individual progress events or when you want to poll for current load state
257 without registering listeners. The value of ``readyState`` progresses as follows
258 for a successful load:
260 =================== ====================
261 Event ``readyState`` value
262 =================== ====================
263 (before any events) ``undefined``
264 ``loadstart`` 1
265 ``progress`` 3
266 ``load`` 4
267 ``loadend`` 4
268 =================== ====================
270 The following code demonstrates how to monitor the loading process using the
271 ``readyState`` attribute. As before, the script that adds the event listeners
272 precedes the ``<embed>`` element so that the event listeners are in place before
273 the progress events are generated.
275 .. naclcode::
277 <html>
278 ...
279 <body id="body">
280 <div id="status_div">
281 </div>
282 <div id="listener_div">
283 <script type="text/javascript">
284 var stat = document.getElementById('status_div');
285 function handleEvent(e) {
286 var embed_element = document.getElementById('my_embed');
287 stat.innerHTML +=
288 '<br>' + e.type + ': readyState = ' + embed_element.readyState;
289 }
290 var listener_element = document.getElementById('listener_div');
291 listener_element.addEventListener('loadstart', handleEvent, true);
292 listener_element.addEventListener('progress', handleEvent, true);
293 listener_element.addEventListener('load', handleEvent, true);
294 listener_element.addEventListener('loadend', handleEvent, true);
295 </script>
296 <embed
297 name="naclModule"
298 id="my_embed"
299 width=0 height=0
300 src="my_example.nmf"
301 type="application/x-pnacl" />
302 </div>
303 </body>
304 </html>
306 The ``exitStatus`` attribute
307 ============================
309 This read-only attribute is set if the application calls ``exit(n)``,
310 ``abort()``, or crashes. Since NaCl modules are event handlers, there is no
311 need to call ``exit(n)`` in normal execution. If the module does exit or
312 crash, the ``crash`` progress event is issued and the ``exitStatus`` attribute
313 will contain the numeric value of the exit status:
315 * In the case of explicit calls to ``exit(n)``, the numeric value will be
316 ``n`` (between 0 and 255).
317 * In the case of crashes and calls to ``abort()``, the numeric value will
318 be non-zero, but the exact value will depend on the chosen libc and the
319 target architecture, and may change in the future. Applications should not
320 rely on the ``exitStatus`` value being stable in these cases, but the value
321 may nevertheless be useful for temporary debugging.