ager@chromium.org | 9258b6b | 2008-09-11 09:11:10 +0000 | [diff] [blame] | 1 | // Copyright 2008 the V8 project authors. All rights reserved. |
christian.plesner.hansen | 43d26ec | 2008-07-03 15:10:15 +0000 | [diff] [blame] | 2 | // Redistribution and use in source and binary forms, with or without |
| 3 | // modification, are permitted provided that the following conditions are |
| 4 | // met: |
| 5 | // |
| 6 | // * Redistributions of source code must retain the above copyright |
| 7 | // notice, this list of conditions and the following disclaimer. |
| 8 | // * Redistributions in binary form must reproduce the above |
| 9 | // copyright notice, this list of conditions and the following |
| 10 | // disclaimer in the documentation and/or other materials provided |
| 11 | // with the distribution. |
| 12 | // * Neither the name of Google Inc. nor the names of its |
| 13 | // contributors may be used to endorse or promote products derived |
| 14 | // from this software without specific prior written permission. |
| 15 | // |
| 16 | // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| 17 | // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| 18 | // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
| 19 | // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
| 20 | // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| 21 | // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| 22 | // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| 23 | // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| 24 | // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| 25 | // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
| 26 | // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 27 | |
ager@chromium.org | 5ec4892 | 2009-05-05 07:25:34 +0000 | [diff] [blame] | 28 | #ifndef V8_V8_DEBUG_H_ |
| 29 | #define V8_V8_DEBUG_H_ |
christian.plesner.hansen | 43d26ec | 2008-07-03 15:10:15 +0000 | [diff] [blame] | 30 | |
| 31 | #include "v8.h" |
| 32 | |
mads.s.ager@gmail.com | 9a4089a | 2008-09-01 08:55:01 +0000 | [diff] [blame] | 33 | #ifdef _WIN32 |
| 34 | typedef int int32_t; |
| 35 | typedef unsigned int uint32_t; |
| 36 | typedef unsigned short uint16_t; // NOLINT |
| 37 | typedef long long int64_t; // NOLINT |
| 38 | |
| 39 | // Setup for Windows DLL export/import. See v8.h in this directory for |
| 40 | // information on how to build/use V8 as a DLL. |
| 41 | #if defined(BUILDING_V8_SHARED) && defined(USING_V8_SHARED) |
| 42 | #error both BUILDING_V8_SHARED and USING_V8_SHARED are set - please check the\ |
| 43 | build configuration to ensure that at most one of these is set |
| 44 | #endif |
| 45 | |
| 46 | #ifdef BUILDING_V8_SHARED |
| 47 | #define EXPORT __declspec(dllexport) |
| 48 | #elif USING_V8_SHARED |
| 49 | #define EXPORT __declspec(dllimport) |
christian.plesner.hansen | 43d26ec | 2008-07-03 15:10:15 +0000 | [diff] [blame] | 50 | #else |
| 51 | #define EXPORT |
| 52 | #endif |
| 53 | |
mads.s.ager@gmail.com | 9a4089a | 2008-09-01 08:55:01 +0000 | [diff] [blame] | 54 | #else // _WIN32 |
| 55 | |
| 56 | // Setup for Linux shared library export. See v8.h in this directory for |
| 57 | // information on how to build/use V8 as shared library. |
sgjesse@chromium.org | b9d7da1 | 2009-08-05 08:38:10 +0000 | [diff] [blame] | 58 | #if defined(__GNUC__) && (__GNUC__ >= 4) && defined(V8_SHARED) |
mads.s.ager@gmail.com | 9a4089a | 2008-09-01 08:55:01 +0000 | [diff] [blame] | 59 | #define EXPORT __attribute__ ((visibility("default"))) |
| 60 | #else // defined(__GNUC__) && (__GNUC__ >= 4) |
| 61 | #define EXPORT |
| 62 | #endif // defined(__GNUC__) && (__GNUC__ >= 4) |
| 63 | |
| 64 | #endif // _WIN32 |
| 65 | |
| 66 | |
christian.plesner.hansen | 43d26ec | 2008-07-03 15:10:15 +0000 | [diff] [blame] | 67 | /** |
| 68 | * Debugger support for the V8 JavaScript engine. |
| 69 | */ |
| 70 | namespace v8 { |
| 71 | |
kasper.lund | 7276f14 | 2008-07-30 08:49:36 +0000 | [diff] [blame] | 72 | // Debug events which can occur in the V8 JavaScript engine. |
christian.plesner.hansen | 43d26ec | 2008-07-03 15:10:15 +0000 | [diff] [blame] | 73 | enum DebugEvent { |
| 74 | Break = 1, |
| 75 | Exception = 2, |
| 76 | NewFunction = 3, |
| 77 | BeforeCompile = 4, |
kasperl@chromium.org | 71affb5 | 2009-05-26 05:44:31 +0000 | [diff] [blame] | 78 | AfterCompile = 5, |
| 79 | ScriptCollected = 6 |
christian.plesner.hansen | 43d26ec | 2008-07-03 15:10:15 +0000 | [diff] [blame] | 80 | }; |
| 81 | |
| 82 | |
christian.plesner.hansen | 43d26ec | 2008-07-03 15:10:15 +0000 | [diff] [blame] | 83 | class EXPORT Debug { |
| 84 | public: |
ager@chromium.org | 65dad4b | 2009-04-23 08:48:43 +0000 | [diff] [blame] | 85 | /** |
| 86 | * A client object passed to the v8 debugger whose ownership will be taken by |
| 87 | * it. v8 is always responsible for deleting the object. |
| 88 | */ |
| 89 | class ClientData { |
| 90 | public: |
| 91 | virtual ~ClientData() {} |
| 92 | }; |
| 93 | |
| 94 | |
| 95 | /** |
ager@chromium.org | 5ec4892 | 2009-05-05 07:25:34 +0000 | [diff] [blame] | 96 | * A message object passed to the debug message handler. |
| 97 | */ |
| 98 | class Message { |
| 99 | public: |
| 100 | /** |
| 101 | * Check type of message. |
| 102 | */ |
| 103 | virtual bool IsEvent() const = 0; |
| 104 | virtual bool IsResponse() const = 0; |
| 105 | virtual DebugEvent GetEvent() const = 0; |
| 106 | |
| 107 | /** |
| 108 | * Indicate whether this is a response to a continue command which will |
| 109 | * start the VM running after this is processed. |
| 110 | */ |
| 111 | virtual bool WillStartRunning() const = 0; |
| 112 | |
| 113 | /** |
| 114 | * Access to execution state and event data. Don't store these cross |
| 115 | * callbacks as their content becomes invalid. These objects are from the |
| 116 | * debugger event that started the debug message loop. |
| 117 | */ |
| 118 | virtual Handle<Object> GetExecutionState() const = 0; |
| 119 | virtual Handle<Object> GetEventData() const = 0; |
| 120 | |
| 121 | /** |
| 122 | * Get the debugger protocol JSON. |
| 123 | */ |
| 124 | virtual Handle<String> GetJSON() const = 0; |
| 125 | |
| 126 | /** |
| 127 | * Get the context active when the debug event happened. Note this is not |
| 128 | * the current active context as the JavaScript part of the debugger is |
| 129 | * running in it's own context which is entered at this point. |
| 130 | */ |
| 131 | virtual Handle<Context> GetEventContext() const = 0; |
| 132 | |
| 133 | /** |
| 134 | * Client data passed with the corresponding request if any. This is the |
| 135 | * client_data data value passed into Debug::SendCommand along with the |
| 136 | * request that led to the message or NULL if the message is an event. The |
| 137 | * debugger takes ownership of the data and will delete it even if there is |
| 138 | * no message handler. |
| 139 | */ |
| 140 | virtual ClientData* GetClientData() const = 0; |
| 141 | |
| 142 | virtual ~Message() {} |
| 143 | }; |
| 144 | |
| 145 | |
| 146 | /** |
ager@chromium.org | 65dad4b | 2009-04-23 08:48:43 +0000 | [diff] [blame] | 147 | * Debug event callback function. |
| 148 | * |
| 149 | * \param event the type of the debug event that triggered the callback |
| 150 | * (enum DebugEvent) |
| 151 | * \param exec_state execution state (JavaScript object) |
| 152 | * \param event_data event specific data (JavaScript object) |
| 153 | * \param data value passed by the user to SetDebugEventListener |
| 154 | */ |
| 155 | typedef void (*EventCallback)(DebugEvent event, |
ager@chromium.org | 5ec4892 | 2009-05-05 07:25:34 +0000 | [diff] [blame] | 156 | Handle<Object> exec_state, |
| 157 | Handle<Object> event_data, |
| 158 | Handle<Value> data); |
ager@chromium.org | 65dad4b | 2009-04-23 08:48:43 +0000 | [diff] [blame] | 159 | |
| 160 | |
| 161 | /** |
| 162 | * Debug message callback function. |
| 163 | * |
ager@chromium.org | 5ec4892 | 2009-05-05 07:25:34 +0000 | [diff] [blame] | 164 | * \param message the debug message handler message object |
ager@chromium.org | 65dad4b | 2009-04-23 08:48:43 +0000 | [diff] [blame] | 165 | * \param length length of the message |
ager@chromium.org | 5ec4892 | 2009-05-05 07:25:34 +0000 | [diff] [blame] | 166 | * \param client_data the data value passed when registering the message handler |
| 167 | |
ager@chromium.org | 65dad4b | 2009-04-23 08:48:43 +0000 | [diff] [blame] | 168 | * A MessageHandler does not take posession of the message string, |
| 169 | * and must not rely on the data persisting after the handler returns. |
ager@chromium.org | 5ec4892 | 2009-05-05 07:25:34 +0000 | [diff] [blame] | 170 | * |
| 171 | * This message handler is deprecated. Use MessageHandler2 instead. |
ager@chromium.org | 65dad4b | 2009-04-23 08:48:43 +0000 | [diff] [blame] | 172 | */ |
| 173 | typedef void (*MessageHandler)(const uint16_t* message, int length, |
ager@chromium.org | 5ec4892 | 2009-05-05 07:25:34 +0000 | [diff] [blame] | 174 | ClientData* client_data); |
| 175 | |
| 176 | /** |
| 177 | * Debug message callback function. |
| 178 | * |
| 179 | * \param message the debug message handler message object |
| 180 | |
| 181 | * A MessageHandler does not take posession of the message data, |
| 182 | * and must not rely on the data persisting after the handler returns. |
| 183 | */ |
| 184 | typedef void (*MessageHandler2)(const Message& message); |
ager@chromium.org | 65dad4b | 2009-04-23 08:48:43 +0000 | [diff] [blame] | 185 | |
| 186 | /** |
| 187 | * Debug host dispatch callback function. |
| 188 | */ |
| 189 | typedef void (*HostDispatchHandler)(); |
| 190 | |
ager@chromium.org | c4c9272 | 2009-11-18 14:12:51 +0000 | [diff] [blame] | 191 | /** |
| 192 | * Callback function for the host to ensure debug messages are processed. |
| 193 | */ |
| 194 | typedef void (*DebugMessageDispatchHandler)(); |
| 195 | |
iposva@chromium.org | 245aa85 | 2009-02-10 00:49:54 +0000 | [diff] [blame] | 196 | // Set a C debug event listener. |
ager@chromium.org | 65dad4b | 2009-04-23 08:48:43 +0000 | [diff] [blame] | 197 | static bool SetDebugEventListener(EventCallback that, |
christian.plesner.hansen | 43d26ec | 2008-07-03 15:10:15 +0000 | [diff] [blame] | 198 | Handle<Value> data = Handle<Value>()); |
| 199 | |
iposva@chromium.org | 245aa85 | 2009-02-10 00:49:54 +0000 | [diff] [blame] | 200 | // Set a JavaScript debug event listener. |
| 201 | static bool SetDebugEventListener(v8::Handle<v8::Object> that, |
christian.plesner.hansen | 43d26ec | 2008-07-03 15:10:15 +0000 | [diff] [blame] | 202 | Handle<Value> data = Handle<Value>()); |
| 203 | |
christian.plesner.hansen | 43d26ec | 2008-07-03 15:10:15 +0000 | [diff] [blame] | 204 | // Break execution of JavaScript. |
| 205 | static void DebugBreak(); |
| 206 | |
ager@chromium.org | 3a37e9b | 2009-04-27 09:26:21 +0000 | [diff] [blame] | 207 | // Message based interface. The message protocol is JSON. NOTE the message |
| 208 | // handler thread is not supported any more parameter must be false. |
ager@chromium.org | 65dad4b | 2009-04-23 08:48:43 +0000 | [diff] [blame] | 209 | static void SetMessageHandler(MessageHandler handler, |
ager@chromium.org | 3a37e9b | 2009-04-27 09:26:21 +0000 | [diff] [blame] | 210 | bool message_handler_thread = false); |
ager@chromium.org | 5ec4892 | 2009-05-05 07:25:34 +0000 | [diff] [blame] | 211 | static void SetMessageHandler2(MessageHandler2 handler); |
ager@chromium.org | 65dad4b | 2009-04-23 08:48:43 +0000 | [diff] [blame] | 212 | static void SendCommand(const uint16_t* command, int length, |
| 213 | ClientData* client_data = NULL); |
ager@chromium.org | a74f0da | 2008-12-03 16:05:52 +0000 | [diff] [blame] | 214 | |
ager@chromium.org | 381abbb | 2009-02-25 13:23:22 +0000 | [diff] [blame] | 215 | // Dispatch interface. |
ager@chromium.org | 65dad4b | 2009-04-23 08:48:43 +0000 | [diff] [blame] | 216 | static void SetHostDispatchHandler(HostDispatchHandler handler, |
| 217 | int period = 100); |
ager@chromium.org | 381abbb | 2009-02-25 13:23:22 +0000 | [diff] [blame] | 218 | |
ager@chromium.org | c4c9272 | 2009-11-18 14:12:51 +0000 | [diff] [blame] | 219 | /** |
| 220 | * Register a callback function to be called when a debug message has been |
| 221 | * received and is ready to be processed. For the debug messages to be |
| 222 | * processed V8 needs to be entered, and in certain embedding scenarios this |
| 223 | * callback can be used to make sure V8 is entered for the debug message to |
| 224 | * be processed. Note that debug messages will only be processed if there is |
| 225 | * a V8 break. This can happen automatically by using the option |
| 226 | * --debugger-auto-break. |
sgjesse@chromium.org | b302e56 | 2010-02-03 11:26:59 +0000 | [diff] [blame] | 227 | * \param provide_locker requires that V8 acquires v8::Locker for you before |
| 228 | * calling handler |
ager@chromium.org | c4c9272 | 2009-11-18 14:12:51 +0000 | [diff] [blame] | 229 | */ |
| 230 | static void SetDebugMessageDispatchHandler( |
sgjesse@chromium.org | b302e56 | 2010-02-03 11:26:59 +0000 | [diff] [blame] | 231 | DebugMessageDispatchHandler handler, bool provide_locker = false); |
ager@chromium.org | c4c9272 | 2009-11-18 14:12:51 +0000 | [diff] [blame] | 232 | |
ager@chromium.org | a74f0da | 2008-12-03 16:05:52 +0000 | [diff] [blame] | 233 | /** |
| 234 | * Run a JavaScript function in the debugger. |
| 235 | * \param fun the function to call |
| 236 | * \param data passed as second argument to the function |
| 237 | * With this call the debugger is entered and the function specified is called |
| 238 | * with the execution state as the first argument. This makes it possible to |
| 239 | * get access to information otherwise not available during normal JavaScript |
sgjesse@chromium.org | df7a284 | 2010-03-25 14:34:15 +0000 | [diff] [blame] | 240 | * execution e.g. details on stack frames. Receiver of the function call will |
| 241 | * be the debugger context global object, however this is a subject to change. |
| 242 | * The following example show a JavaScript function which when passed to |
| 243 | * v8::Debug::Call will return the current line of JavaScript execution. |
ager@chromium.org | a74f0da | 2008-12-03 16:05:52 +0000 | [diff] [blame] | 244 | * |
| 245 | * \code |
| 246 | * function frame_source_line(exec_state) { |
| 247 | * return exec_state.frame(0).sourceLine(); |
| 248 | * } |
| 249 | * \endcode |
| 250 | */ |
sgjesse@chromium.org | 911335c | 2009-08-19 12:59:44 +0000 | [diff] [blame] | 251 | static Local<Value> Call(v8::Handle<v8::Function> fun, |
ager@chromium.org | a74f0da | 2008-12-03 16:05:52 +0000 | [diff] [blame] | 252 | Handle<Value> data = Handle<Value>()); |
kasperl@chromium.org | 7be3c99 | 2009-03-12 07:19:55 +0000 | [diff] [blame] | 253 | |
sgjesse@chromium.org | 911335c | 2009-08-19 12:59:44 +0000 | [diff] [blame] | 254 | /** |
| 255 | * Returns a mirror object for the given object. |
| 256 | */ |
| 257 | static Local<Value> GetMirror(v8::Handle<v8::Value> obj); |
| 258 | |
kasperl@chromium.org | 7be3c99 | 2009-03-12 07:19:55 +0000 | [diff] [blame] | 259 | /** |
| 260 | * Enable the V8 builtin debug agent. The debugger agent will listen on the |
| 261 | * supplied TCP/IP port for remote debugger connection. |
ager@chromium.org | bb29dc9 | 2009-03-24 13:25:23 +0000 | [diff] [blame] | 262 | * \param name the name of the embedding application |
kasperl@chromium.org | 7be3c99 | 2009-03-12 07:19:55 +0000 | [diff] [blame] | 263 | * \param port the TCP/IP port to listen on |
fschneider@chromium.org | 0c20e67 | 2010-01-14 15:28:53 +0000 | [diff] [blame] | 264 | * \param wait_for_connection whether V8 should pause on a first statement |
| 265 | * allowing remote debugger to connect before anything interesting happened |
kasperl@chromium.org | 7be3c99 | 2009-03-12 07:19:55 +0000 | [diff] [blame] | 266 | */ |
fschneider@chromium.org | 0c20e67 | 2010-01-14 15:28:53 +0000 | [diff] [blame] | 267 | static bool EnableAgent(const char* name, int port, |
| 268 | bool wait_for_connection = false); |
sgjesse@chromium.org | b302e56 | 2010-02-03 11:26:59 +0000 | [diff] [blame] | 269 | |
| 270 | /** |
| 271 | * Makes V8 process all pending debug messages. |
| 272 | * |
| 273 | * From V8 point of view all debug messages come asynchronously (e.g. from |
| 274 | * remote debugger) but they all must be handled synchronously: V8 cannot |
| 275 | * do 2 things at one time so normal script execution must be interrupted |
| 276 | * for a while. |
| 277 | * |
| 278 | * Generally when message arrives V8 may be in one of 3 states: |
| 279 | * 1. V8 is running script; V8 will automatically interrupt and process all |
| 280 | * pending messages (however auto_break flag should be enabled); |
| 281 | * 2. V8 is suspended on debug breakpoint; in this state V8 is dedicated |
| 282 | * to reading and processing debug messages; |
| 283 | * 3. V8 is not running at all or has called some long-working C++ function; |
| 284 | * by default it means that processing of all debug message will be deferred |
| 285 | * until V8 gets control again; however, embedding application may improve |
| 286 | * this by manually calling this method. |
| 287 | * |
| 288 | * It makes sense to call this method whenever a new debug message arrived and |
| 289 | * V8 is not already running. Method v8::Debug::SetDebugMessageDispatchHandler |
| 290 | * should help with the former condition. |
| 291 | * |
| 292 | * Technically this method in many senses is equivalent to executing empty |
| 293 | * script: |
| 294 | * 1. It does nothing except for processing all pending debug messages. |
| 295 | * 2. It should be invoked with the same precautions and from the same context |
| 296 | * as V8 script would be invoked from, because: |
| 297 | * a. with "evaluate" command it can do whatever normal script can do, |
| 298 | * including all native calls; |
| 299 | * b. no other thread should call V8 while this method is running |
| 300 | * (v8::Locker may be used here). |
| 301 | * |
| 302 | * "Evaluate" debug command behavior currently is not specified in scope |
| 303 | * of this method. |
| 304 | */ |
| 305 | static void ProcessDebugMessages(); |
sgjesse@chromium.org | df7a284 | 2010-03-25 14:34:15 +0000 | [diff] [blame] | 306 | |
| 307 | /** |
| 308 | * Debugger is running in it's own context which is entered while debugger |
| 309 | * messages are being dispatched. This is an explicit getter for this |
| 310 | * debugger context. Note that the content of the debugger context is subject |
| 311 | * to change. |
| 312 | */ |
| 313 | static Local<Context> GetDebugContext(); |
christian.plesner.hansen | 43d26ec | 2008-07-03 15:10:15 +0000 | [diff] [blame] | 314 | }; |
| 315 | |
| 316 | |
| 317 | } // namespace v8 |
| 318 | |
| 319 | |
| 320 | #undef EXPORT |
| 321 | |
| 322 | |
ager@chromium.org | 5ec4892 | 2009-05-05 07:25:34 +0000 | [diff] [blame] | 323 | #endif // V8_V8_DEBUG_H_ |