src/native_client_sdk/doc_generated/devguide/coding/progress-events.html

   1 {{+bindTo:partials.standard_nacl_api}}
   2
   3 <section id="progress-events">
   4 <h1 id="progress-events">Progress Events</h1>
   5 <div class="contents local" id="contents" style="display: none">
   6 <ul class="small-gap">
   7 <li><a class="reference internal" href="#module-loading-and-progress-events" id="id3">Module loading and progress events</a></li>
   8 <li><a class="reference internal" href="#handling-progress-events" id="id4">Handling progress events</a></li>
   9 <li><a class="reference internal" href="#displaying-load-status" id="id5">Displaying load status</a></li>
  10 <li><a class="reference internal" href="#the-lasterror-attribute" id="id6">The <code>lastError</code> attribute</a></li>
  11 <li><a class="reference internal" href="#the-readystate-attribute" id="id7">The <code>readyState</code> attribute</a></li>
  12 <li><a class="reference internal" href="#the-exitstatus-attribute" id="id8">The <code>exitStatus</code> attribute</a></li>
  13 </ul>
  14
  15 </div><p>There are five types of events that developers can respond to in Native Client:
  16 progress, message, view change, focus, and input events (each described in the
  17 glossary below). This chapter describes how to monitor progress events (events
  18 that occur during the loading and execution of a Native Client module). This
  19 chapter assumes you are familiar with the material presented in the
  20 <a class="reference internal" href="/native-client/overview.html"><em>Technical Overview</em></a>.</p>
  21 <aside class="note">
  22 The load_progress example illustrates progress event handling. You can find
  23 this code in the <code>/examples/tutorial/load_progress/</code> directory in the Native
  24 Client SDK download.
  25 </aside>
  26 <h2 id="module-loading-and-progress-events">Module loading and progress events</h2>
  27 <p>The Native Client runtime reports a set of state changes during the module
  28 loading process by means of DOM progress events. This set of events is a direct
  29 port of the proposed W3C <a class="reference external" href="http://www.w3.org/TR/progress-events/">Progress Events</a> standard (except for the <code>crash</code>
  30 event which is an extension of the W3C standard). The following table lists the
  31 events types reported by the Native Client runtime:</p>
  32 <table border="1" class="docutils">
  33 <colgroup>
  34 </colgroup>
  35 <thead valign="bottom">
  36 <tr class="row-odd"><th class="head">Event</th>
  37 <th class="head">Description</th>
  38 <th class="head">Number of
  39 times
  40 triggered</th>
  41 <th class="head">When event is
  42 triggered</th>
  43 <th class="head">How you might
  44 react to
  45 event</th>
  46 </tr>
  47 </thead>
  48 <tbody valign="top">
  49 <tr class="row-even"><td><code>loadstart</code></td>
  50 <td>Native Client has
  51 started to load a
  52 Native Client
  53 module.</td>
  54 <td>once</td>
  55 <td>This is the
  56 first
  57 progress
  58 event
  59 triggered
  60 after the
  61 Native Client
  62 module is
  63 instantiated
  64 and
  65 initialized.</td>
  66 <td>Display a
  67 status
  68 message, such
  69 as
  70 &#8220;Loading...&#8221;</td>
  71 </tr>
  72 <tr class="row-odd"><td><code>progress</code></td>
  73 <td>Part of the module
  74 has been loaded.</td>
  75 <td>zero or
  76 more</td>
  77 <td>After
  78 <code>loadstart</code>
  79 has been
  80 dispatched.</td>
  81 <td>Display a
  82 progress bar.</td>
  83 </tr>
  84 <tr class="row-even"><td><code>error</code></td>
  85 <td>The Native Client
  86 module failed to
  87 start execution
  88 (includes any
  89 error before or
  90 during
  91 initialization of
  92 the module). The
  93 <code>lastError</code>
  94 attribute
  95 (mentioned later)
  96 provides details
  97 on the error
  98 (initialization
  99 failed, sel_ldr
 100 did not start,
 101 and so on).</td>
 102 <td>zero or
 103 once</td>
 104 <td>After the
 105 last
 106 <code>progress</code>
 107 event has
 108 been
 109 dispatched,
 110 or after
 111 <code>loadstart</code>
 112 if no
 113 <code>progress</code>
 114 event was
 115 dispatched.</td>
 116 <td>Inform user
 117 that the
 118 application
 119 failed to
 120 load.</td>
 121 </tr>
 122 <tr class="row-odd"><td><code>abort</code></td>
 123 <td>Loading of the
 124 Native Client
 125 module was
 126 aborted by the
 127 user.</td>
 128 <td>zero or
 129 once</td>
 130 <td>After the
 131 last
 132 <code>progress</code>
 133 event has
 134 been
 135 dispatched,
 136 or after
 137 <code>loadstart</code>
 138 if no
 139 <code>progress</code>
 140 event was
 141 dispatched.</td>
 142 <td>It&#8217;s not
 143 likely you
 144 will want to
 145 respond to
 146 this event.</td>
 147 </tr>
 148 <tr class="row-even"><td><code>load</code></td>
 149 <td>The Native Client
 150 module was
 151 successfully
 152 loaded, and
 153 execution was
 154 started. (The
 155 module was
 156 initialized
 157 successfully.)</td>
 158 <td>zero or
 159 once</td>
 160 <td>After the
 161 last
 162 <code>progress</code>
 163 event has
 164 been
 165 dispatched,
 166 or after
 167 <code>loadstart</code>
 168 if no
 169 <code>progress</code>
 170 event was
 171 dispatched.</td>
 172 <td>Remove the
 173 progress bar.</td>
 174 </tr>
 175 <tr class="row-odd"><td><code>loadend</code></td>
 176 <td>Loading of the
 177 Native Client
 178 module has
 179 stopped. Load
 180 succeeded
 181 (<code>load</code>),
 182 failed
 183 (<code>error</code>), or
 184 was aborted
 185 (<code>abort</code>).</td>
 186 <td>once</td>
 187 <td>After an
 188 <code>error</code>,
 189 <code>abort</code>, or
 190 <code>load</code>
 191 event was
 192 dispatched.</td>
 193 <td>Indicate
 194 loading is
 195 over
 196 (regardless
 197 of failure or
 198 not).</td>
 199 </tr>
 200 <tr class="row-even"><td><code>crash</code></td>
 201 <td>The Native Client
 202 module is not
 203 responding (died
 204 on an
 205 <code>assert()</code> or
 206 <code>exit()</code>) after
 207 a successful
 208 load. This event
 209 is unique to
 210 Native Client and
 211 is not part of
 212 the W3C Progress
 213 Events standard.
 214 The <code>exitStatus</code>
 215 attribute provides
 216 the numeric exit
 217 status value.</td>
 218 <td>zero or
 219 once</td>
 220 <td>After a
 221 <code>loadend</code>.</td>
 222 <td>Notify user
 223 that the
 224 module did
 225 something
 226 illegal.</td>
 227 </tr>
 228 </tbody>
 229 </table>
 230 <p>The sequence of events for a successful module load is as follows:</p>
 231 <table border="1" class="docutils">
 232 <colgroup>
 233 </colgroup>
 234 <thead valign="bottom">
 235 <tr class="row-odd"><th class="head">Event is dispatched</th>
 236 <th class="head">... then this task is attempted</th>
 237 </tr>
 238 </thead>
 239 <tbody valign="top">
 240 <tr class="row-even"><td><code>loadstart</code></td>
 241 <td>load the manifest file</td>
 242 </tr>
 243 <tr class="row-odd"><td><code>progress</code> (first time)</td>
 244 <td>load the module</td>
 245 </tr>
 246 <tr class="row-even"><td><code>progress</code> (subsequent times)</td>
 247 <td>&nbsp;</td>
 248 </tr>
 249 <tr class="row-odd"><td><code>load</code></td>
 250 <td>start executing the module</td>
 251 </tr>
 252 <tr class="row-even"><td><code>loadend</code></td>
 253 <td>&nbsp;</td>
 254 </tr>
 255 </tbody>
 256 </table>
 257 <p>Errors that occur during loading are logged to the JavaScript console in Google
 258 Chrome (select the menu icon <img alt="menu-icon" src="/native-client/images/menu-icon.png" /> &gt; Tools &gt; JavaScript console).</p>
 259 <h2 id="handling-progress-events">Handling progress events</h2>
 260 <p>You should add event listeners in a <code>&lt;script&gt;</code> element to listen for these
 261 events before the <code>&lt;embed&gt;</code> element is parsed. For example, the following code
 262 adds a listener for the <code>load</code> event to a parent <code>&lt;div&gt;</code> element that also
 263 contains the Native Client <code>&lt;embed&gt;</code> element. First, the listener is
 264 attached. Then, when the listener <code>&lt;div&gt;</code> receives the <code>load</code> event, the
 265 JavaScript <code>moduleDidLoad()</code> function is called. The following code is
 266 excerpted from the example in <code>getting_started/part1/</code>:</p>
 267 <pre class="prettyprint">
 268 &lt;!--
 269 Load the published pexe.
 270 Note: Since this module does not use any real-estate in the browser, its
 271 width and height are set to 0.
 272
 273 Note: The &lt;embed&gt; element is wrapped inside a &lt;div&gt;, which has both a 'load'
 274 and a 'message' event listener attached.  This wrapping method is used
 275 instead of attaching the event listeners directly to the &lt;embed&gt; element to
 276 ensure that the listeners are active before the NaCl module 'load' event
 277 fires.  This also allows you to use PPB_Messaging.PostMessage() (in C) or
 278 pp::Instance.PostMessage() (in C++) from within the initialization code in
 279 your module.
 280 --&gt;
 281 &lt;div id=&quot;listener&quot;&gt;
 282   &lt;script type=&quot;text/javascript&quot;&gt;
 283     var listener = document.getElementById('listener');
 284     listener.addEventListener('load', moduleDidLoad, true);
 285     listener.addEventListener('message', handleMessage, true);
 286   &lt;/script&gt;
 287
 288   &lt;embed id=&quot;hello_tutorial&quot;
 289          width=0 height=0
 290          src=&quot;hello_tutorial.nmf&quot;
 291          type=&quot;application/x-pnacl&quot; /&gt;
 292 &lt;/div&gt;
 293 </pre>
 294 <p>Event listeners can be added to any DOM object. Since listeners set at the
 295 outermost scope capture events for their contained elements, you can set
 296 listeners on outer elements (including the <code>&lt;body&gt;</code> element) to handle events
 297 from inner elements. For more information, see the W3 specifications for <a class="reference external" href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-flow-capture">event
 298 flow capture</a> and
 299 <a class="reference external" href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-registration">event listener registration</a>.</p>
 300 <h2 id="displaying-load-status">Displaying load status</h2>
 301 <p>One common response to progress events is to display the percentage of the
 302 module that has been loaded. In the load_progress example, when the <code>progress</code>
 303 event is triggered the <code>moduleLoadProgress</code> function is called. This function
 304 uses the <code>lengthComputable</code>, <code>loaded</code>, and <code>total</code> attributes (described
 305 in the proposed W3C <a class="reference external" href="http://www.w3.org/TR/progress-events/">Progress Events</a>
 306 standard) of the event to calculate the percentage of the module that has
 307 loaded.</p>
 308 <pre class="prettyprint">
 309 function moduleLoadProgress(event) {
 310   var loadPercent = 0.0;
 311   var loadPercentString;
 312   if (event.lengthComputable &amp;&amp; event.total &gt; 0) {
 313     loadPercent = event.loaded / event.total * 100.0;
 314     loadPercentString = loadPercent + '%';
 315     common.logMessage('progress: ' + event.url + ' ' + loadPercentString +
 316                      ' (' + event.loaded + ' of ' + event.total + ' bytes)');
 317   } else {
 318     // The total length is not yet known.
 319     common.logMessage('progress: Computing...');
 320   }
 321 }
 322 </pre>
 323 <h2 id="the-lasterror-attribute">The <code>lastError</code> attribute</h2>
 324 <p>The <code>&lt;embed&gt;</code> element has a <code>lastError</code> attribute that is set to an
 325 informative string whenever a load failure (an <code>error</code> or <code>abort</code> event)
 326 occurs.</p>
 327 <p>The following code adds an event listener before the <code>&lt;embed&gt;</code> element to
 328 capture and handle an error in loading the Native Client module. The
 329 <code>handleError()</code> function listens for an <code>error</code> event. When an error occurs,
 330 this function prints the contents of the <code>lastError</code> attribute
 331 (<code>embed_element.lastError</code>) as an alert.</p>
 332 <pre class="prettyprint">
 333 function domContentLoaded(name, tc, config, width, height) {
 334   var listener = document.getElementById('listener');
 335   ...
 336   listener.addEventListener('error', moduleLoadError, true);
 337   ...
 338   common.createNaClModule(name, tc, config, width, height);
 339 }
 340
 341 function moduleLoadError() {
 342   common.logMessage('error: ' + common.naclModule.lastError);
 343 }
 344 </pre>
 345 <h2 id="the-readystate-attribute">The <code>readyState</code> attribute</h2>
 346 <p>You can use the <code>readyState</code> attribute to monitor the loading process. This
 347 attribute is particularly useful if you don&#8217;t care about the details of
 348 individual progress events or when you want to poll for current load state
 349 without registering listeners. The value of <code>readyState</code> progresses as follows
 350 for a successful load:</p>
 351 <table border="1" class="docutils">
 352 <colgroup>
 353 </colgroup>
 354 <thead valign="bottom">
 355 <tr class="row-odd"><th class="head">Event</th>
 356 <th class="head"><code>readyState</code> value</th>
 357 </tr>
 358 </thead>
 359 <tbody valign="top">
 360 <tr class="row-even"><td>(before any events)</td>
 361 <td><code>undefined</code></td>
 362 </tr>
 363 <tr class="row-odd"><td><code>loadstart</code></td>
 364 <td>1</td>
 365 </tr>
 366 <tr class="row-even"><td><code>progress</code></td>
 367 <td>3</td>
 368 </tr>
 369 <tr class="row-odd"><td><code>load</code></td>
 370 <td>4</td>
 371 </tr>
 372 <tr class="row-even"><td><code>loadend</code></td>
 373 <td>4</td>
 374 </tr>
 375 </tbody>
 376 </table>
 377 <p>The following code demonstrates how to monitor the loading process using the
 378 <code>readyState</code> attribute. As before, the script that adds the event listeners
 379 precedes the <code>&lt;embed&gt;</code> element so that the event listeners are in place before
 380 the progress events are generated.</p>
 381 <pre class="prettyprint">
 382 &lt;html&gt;
 383 ...
 384   &lt;body id=&quot;body&quot;&gt;
 385     &lt;div id=&quot;status_div&quot;&gt;
 386     &lt;/div&gt;
 387     &lt;div id=&quot;listener_div&quot;&gt;
 388       &lt;script type=&quot;text/javascript&quot;&gt;
 389          var stat = document.getElementById('status_div');
 390          function handleEvent(e) {
 391            var embed_element = document.getElementById('my_embed');
 392            stat.innerHTML +=
 393            '&lt;br&gt;' + e.type + ': readyState = ' + embed_element.readyState;
 394          }
 395          var listener_element = document.getElementById('listener_div');
 396          listener_element.addEventListener('loadstart', handleEvent, true);
 397          listener_element.addEventListener('progress', handleEvent, true);
 398          listener_element.addEventListener('load', handleEvent, true);
 399          listener_element.addEventListener('loadend', handleEvent, true);
 400       &lt;/script&gt;
 401       &lt;embed
 402         name=&quot;naclModule&quot;
 403         id=&quot;my_embed&quot;
 404         width=0 height=0
 405         src=&quot;my_example.nmf&quot;
 406         type=&quot;application/x-pnacl&quot; /&gt;
 407     &lt;/div&gt;
 408   &lt;/body&gt;
 409 &lt;/html&gt;
 410 </pre>
 411 <h2 id="the-exitstatus-attribute">The <code>exitStatus</code> attribute</h2>
 412 <p>This read-only attribute is set if the application calls <code>exit(n)</code>,
 413 <code>abort()</code>, or crashes. Since NaCl modules are event handlers, there is no
 414 need to call <code>exit(n)</code> in normal execution. If the module does exit or
 415 crash, the <code>crash</code> progress event is issued and the <code>exitStatus</code> attribute
 416 will contain the numeric value of the exit status:</p>
 417 <ul class="small-gap">
 418 <li>In the case of explicit calls to <code>exit(n)</code>, the numeric value will be
 419 <code>n</code> (between 0 and 255).</li>
 420 <li>In the case of crashes and calls to <code>abort()</code>, the numeric value will
 421 be non-zero, but the exact value will depend on the chosen libc and the
 422 target architecture, and may change in the future. Applications should not
 423 rely on the <code>exitStatus</code> value being stable in these cases, but the value
 424 may nevertheless be useful for temporary debugging.</li>
 425 </ul>
 426 </section>
 427
 428 {{/partials.standard_nacl_api}}