index.html revision c2e0dbddbe15c98d52c4786dac06cb8952a8ae6d
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> 9c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <meta http-equiv="Pragma" content="no-cache" /> 10c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <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 20c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <li>"LOG: <data>" which adds the message to the log.</li> 21c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <li>"STS: <data>" which updates the status string.</li> 22c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <li>"TRC: <data>" which provides a JSON string defining an exception.</li> 23c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <h2> Exception API </h2> 24c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <p> As of Chrome 28, NativeClient exception handling is possible without 25c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) requiring special command-line flags. This feature is not always available 26c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) so developers should avoid requring it under normal operation. However it 27c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) can be a very useful tool for diagnosing crashes, especially in the field. 28c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) NativeClient provides a library called "error_handling" for registering 29c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) the exception handler, as well as unwinding the exception context. 30c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <br><b>NOTE: The library requires '-fno-omit-frame-pointer' to facilitate 31c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) unwinding the stack.</b></p> 32c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <h2> Trace Walkthrough </h2> 33c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <p> First we request the exception handler interface, and use it to register 34c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) both a handler and an exception stack. We use a separate stack since we 35c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) do not know the state of stack for the thread handling the exception. 36c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) Next, we create a worker thread which will take the exception. It is 37c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) recommended that modules do as much work as possible off the main thread. 38c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) Failure to do so can block the browser, making the page unresponsive and/or 39c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) preventing communication with JavaScript. In addition blocking calls, 40c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) which can greatly simplify code, are only allowed off the main thread.</p> 41c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <p> After two seconds, JavaScript sends a message to the module which will 42c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) cause it take an exception on the worker thread. The exception handler 43c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) unwinds the stack while creating a stringified JSON object containing the 44c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) stack frame information. Once unwound, or the buffer is exhausted, the 45c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) JSON object is sent to JavaScript for processing. 46c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <p> The message handler in JavaScript takes the JSON object and uses the 47c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) arch key to load the appropriate MAP file using an XMLHttpRequest. It 48c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) then processes the MAP file and prints out a stack trace using the exception 49c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) data in the JSON object.</p> 50c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <h2> Exception Handling in the Field </h2> 51c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <p> 52c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) For real world applications, it's important to get the crash information 53c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) back the developer. In this case, the JSON object could be sent via 54c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) XMLHttpRequest. The JSON object can the be processed by the developers 55c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) QA team to manage bugs in the field. The handler.py script provided in 56c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) the example sources shows how the JSON object can be used with the tools 57c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) to provide a better stack trace. Simply cut and paste the JSON object 58c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) to a text file and run the handler.py script on it. 59c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) </p> 60c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 61c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <div id="listener"></div> 62c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <hr> 63c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <h2>Status: <code id="statusField">NO-STATUS</code></h2> 64c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <table> 65c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <tr> 66c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <td><h2>Log</h2></td> 67c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <td><h2>JSON</h2></td> 68c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) </tr> 69c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <tr> 70c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <td> 71c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <textarea id="log" rows="10" cols="60" readonly="readonly"></textarea> 72c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) </td> 73c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <td> 74c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <textarea id="json" rows="10" cols="60" readonly="readonly"></textarea> 75c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) </td> 76c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) </tr> 77c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) </table> 78c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <br> 79c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <h2>Stack Trace</h2> 80c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) <textarea id="trace" rows="10" cols="130" readonly="readonly"></textarea> 81c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)</body> 82c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)</html> 83