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