src/native_client_sdk/src/examples/tutorial/debugging/index.html

   1 <!DOCTYPE html>
   2 <html>
   3   <!--
   4   Copyright (c) 2012 The Chromium Authors. All rights reserved.
   5   Use of this source code is governed by a BSD-style license that can be
   6   found in the LICENSE file.
   7   -->
   8 <head>
   9   <meta http-equiv="Pragma" content="no-cache">
  10   <meta http-equiv="Expires" content="-1">
  11   <title>Logging and Crash Handling</title>
  12   <script type="text/javascript" src="common.js"></script>
  13   <script type="text/javascript" src="example.js"></script>
  14 </head>
  15 <body data-width="0" data-height="0" data-custom-load="true" {{attrs}}>
  16  <h1>Logging and Crash Handling</h1>
  17   <p> This example illustrates techniques for tracking the state of a NaCl
  18   module via PostMessage and status of the module's lastError attribute.
  19   Messages from the modules are in the form of
  20   <ul>
  21     <li>
  22       "LOG: &lt;data&gt;" which adds the message to the log.
  23     </li>
  24     <li>
  25       "TRC: &lt;data&gt;" which provides a JSON string defining an exception.
  26     </li>
  27   </ul>
  28   <h2> Exception API </h2>
  29   <p> As of Chrome 28, NativeClient exception handling is possible without
  30   requiring special command-line flags.  This feature is not always available
  31   so developers should avoid requring it under normal operation.  However it
  32   can be a very useful tool for diagnosing crashes, especially in the field.
  33   NativeClient provides a library called "error_handling" for registering
  34   the exception handler, as well as unwinding the exception context.
  35   <br><b>NOTE: The library requires '-fno-omit-frame-pointer' to facilitate
  36   unwinding the stack.</b></p>
  37   <h2> Trace Walkthrough </h2>
  38   <p> First we request the exception handler interface, and use it to register
  39   both a handler and an exception stack.  We use a separate stack since we
  40   do not know the state of stack for the thread handling the exception.
  41   Next, we create a worker thread which will take the exception.  It is
  42   recommended that modules do as much work as possible off the main thread.
  43   Failure to do so can block the browser, making the page unresponsive and/or
  44   preventing communication with JavaScript.  In addition blocking calls,
  45   which can greatly simplify code, are only allowed off the main thread.</p>
  46   <p> After two seconds, JavaScript sends a message to the module which will
  47   cause it take an exception on the worker thread.  The exception handler
  48   unwinds the stack while creating a stringified JSON object containing the
  49   stack frame information.  Once unwound, or the buffer is exhausted, the
  50   JSON object is sent to JavaScript for processing.
  51   <p> The message handler in JavaScript takes the JSON object and uses the
  52   arch key to load the appropriate MAP file using an XMLHttpRequest.  It
  53   then processes the MAP file and prints out a stack trace using the exception
  54   data in the JSON object.</p>
  55   <h2> Exception Handling in the Field </h2>
  56   <p>
  57   For real world applications, it's important to get the crash information
  58   back the developer.  In this case, the JSON object could be sent via
  59   XMLHttpRequest.  The JSON object can the be processed by the developers
  60   QA team to manage bugs in the field.  The handler.py script provided in
  61   the example sources shows how the JSON object can be used with the tools
  62   to provide a better stack trace.   Simply cut and paste the JSON object
  63   to a text file and run the handler.py script on it.
  64   </p>
  65
  66   <div id="listener"></div>
  67   <hr>
  68   <h2>Status: <code id="statusField">NO-STATUS</code></h2>
  69   <table>
  70    <tr>
  71     <td><h2>Log</h2></td>
  72     <td><h2>JSON</h2></td>
  73    </tr>
  74    <tr>
  75     <td>
  76      <textarea id="log" rows="10" cols="60" readonly="readonly"></textarea>
  77     </td>
  78     <td>
  79      <textarea id="json" rows="10" cols="60" readonly="readonly"></textarea>
  80     </td>
  81    </tr>
  82   </table>
  83   <br>
  84   <h2>Stack Trace</h2>
  85   <textarea id="trace" rows="10" cols="130" readonly="readonly"></textarea>
  86 </body>
  87 </html>