| <!DOCTYPE html> |
| <html> |
| <!-- |
| Copyright (c) 2012 The Chromium Authors. All rights reserved. |
| Use of this source code is governed by a BSD-style license that can be |
| found in the LICENSE file. |
| --> |
| <head> |
| <meta http-equiv="Pragma" content="no-cache"> |
| <meta http-equiv="Expires" content="-1"> |
| <title>Logging and Crash Handling</title> |
| <script type="text/javascript" src="common.js"></script> |
| <script type="text/javascript" src="example.js"></script> |
| </head> |
| <body data-width="0" data-height="0" data-custom-load="true" {{attrs}}> |
| <h1>Logging and Crash Handling</h1> |
| <p> This example illustrates techniques for tracking the state of a NaCl |
| module via PostMessage and status of the module's lastError attribute. |
| Messages from the modules are in the form of |
| <ul> |
| <li> |
| "LOG: <data>" which adds the message to the log. |
| </li> |
| <li> |
| "TRC: <data>" which provides a JSON string defining an exception. |
| </li> |
| </ul> |
| <h2> Exception API </h2> |
| <p> As of Chrome 28, NativeClient exception handling is possible without |
| requiring special command-line flags. This feature is not always available |
| so developers should avoid requring it under normal operation. However it |
| can be a very useful tool for diagnosing crashes, especially in the field. |
| NativeClient provides a library called "error_handling" for registering |
| the exception handler, as well as unwinding the exception context. |
| <br><b>NOTE: The library requires '-fno-omit-frame-pointer' to facilitate |
| unwinding the stack.</b></p> |
| <h2> Trace Walkthrough </h2> |
| <p> First we request the exception handler interface, and use it to register |
| both a handler and an exception stack. We use a separate stack since we |
| do not know the state of stack for the thread handling the exception. |
| Next, we create a worker thread which will take the exception. It is |
| recommended that modules do as much work as possible off the main thread. |
| Failure to do so can block the browser, making the page unresponsive and/or |
| preventing communication with JavaScript. In addition blocking calls, |
| which can greatly simplify code, are only allowed off the main thread.</p> |
| <p> After two seconds, JavaScript sends a message to the module which will |
| cause it take an exception on the worker thread. The exception handler |
| unwinds the stack while creating a stringified JSON object containing the |
| stack frame information. Once unwound, or the buffer is exhausted, the |
| JSON object is sent to JavaScript for processing. |
| <p> The message handler in JavaScript takes the JSON object and uses the |
| arch key to load the appropriate MAP file using an XMLHttpRequest. It |
| then processes the MAP file and prints out a stack trace using the exception |
| data in the JSON object.</p> |
| <h2> Exception Handling in the Field </h2> |
| <p> |
| For real world applications, it's important to get the crash information |
| back the developer. In this case, the JSON object could be sent via |
| XMLHttpRequest. The JSON object can the be processed by the developers |
| QA team to manage bugs in the field. The handler.py script provided in |
| the example sources shows how the JSON object can be used with the tools |
| to provide a better stack trace. Simply cut and paste the JSON object |
| to a text file and run the handler.py script on it. |
| </p> |
| |
| <div id="listener"></div> |
| <hr> |
| <h2>Status: <code id="statusField">NO-STATUS</code></h2> |
| <table> |
| <tr> |
| <td><h2>Log</h2></td> |
| <td><h2>JSON</h2></td> |
| </tr> |
| <tr> |
| <td> |
| <textarea id="log" rows="10" cols="60" readonly="readonly"></textarea> |
| </td> |
| <td> |
| <textarea id="json" rows="10" cols="60" readonly="readonly"></textarea> |
| </td> |
| </tr> |
| </table> |
| <br> |
| <h2>Stack Trace</h2> |
| <textarea id="trace" rows="10" cols="130" readonly="readonly"></textarea> |
| </body> |
| </html> |
