1 // Copyright 2008 the V8 project authors. All rights reserved. 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 28 #ifndef V8_V8_DEBUG_H_ 29 #define V8_V8_DEBUG_H_ 30 31 #include "v8.h" 32 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) 50 #else 51 #define EXPORT 52 #endif 53 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. 58 #if defined(__GNUC__) && (__GNUC__ >= 4) && defined(V8_SHARED) 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 67 /** 68 * Debugger support for the V8 JavaScript engine. 69 */ 70 namespace v8 { 71 72 // Debug events which can occur in the V8 JavaScript engine. 73 enum DebugEvent { 74 Break = 1, 75 Exception = 2, 76 NewFunction = 3, 77 BeforeCompile = 4, 78 AfterCompile = 5, 79 ScriptCollected = 6, 80 BreakForCommand = 7 81 }; 82 83 84 class EXPORT Debug { 85 public: 86 /** 87 * A client object passed to the v8 debugger whose ownership will be taken by 88 * it. v8 is always responsible for deleting the object. 89 */ 90 class ClientData { 91 public: ~ClientData()92 virtual ~ClientData() {} 93 }; 94 95 96 /** 97 * A message object passed to the debug message handler. 98 */ 99 class Message { 100 public: 101 /** 102 * Check type of message. 103 */ 104 virtual bool IsEvent() const = 0; 105 virtual bool IsResponse() const = 0; 106 virtual DebugEvent GetEvent() const = 0; 107 108 /** 109 * Indicate whether this is a response to a continue command which will 110 * start the VM running after this is processed. 111 */ 112 virtual bool WillStartRunning() const = 0; 113 114 /** 115 * Access to execution state and event data. Don't store these cross 116 * callbacks as their content becomes invalid. These objects are from the 117 * debugger event that started the debug message loop. 118 */ 119 virtual Handle<Object> GetExecutionState() const = 0; 120 virtual Handle<Object> GetEventData() const = 0; 121 122 /** 123 * Get the debugger protocol JSON. 124 */ 125 virtual Handle<String> GetJSON() const = 0; 126 127 /** 128 * Get the context active when the debug event happened. Note this is not 129 * the current active context as the JavaScript part of the debugger is 130 * running in its own context which is entered at this point. 131 */ 132 virtual Handle<Context> GetEventContext() const = 0; 133 134 /** 135 * Client data passed with the corresponding request if any. This is the 136 * client_data data value passed into Debug::SendCommand along with the 137 * request that led to the message or NULL if the message is an event. The 138 * debugger takes ownership of the data and will delete it even if there is 139 * no message handler. 140 */ 141 virtual ClientData* GetClientData() const = 0; 142 ~Message()143 virtual ~Message() {} 144 }; 145 146 147 /** 148 * An event details object passed to the debug event listener. 149 */ 150 class EventDetails { 151 public: 152 /** 153 * Event type. 154 */ 155 virtual DebugEvent GetEvent() const = 0; 156 157 /** 158 * Access to execution state and event data of the debug event. Don't store 159 * these cross callbacks as their content becomes invalid. 160 */ 161 virtual Handle<Object> GetExecutionState() const = 0; 162 virtual Handle<Object> GetEventData() const = 0; 163 164 /** 165 * Get the context active when the debug event happened. Note this is not 166 * the current active context as the JavaScript part of the debugger is 167 * running in its own context which is entered at this point. 168 */ 169 virtual Handle<Context> GetEventContext() const = 0; 170 171 /** 172 * Client data passed with the corresponding callback when it was 173 * registered. 174 */ 175 virtual Handle<Value> GetCallbackData() const = 0; 176 177 /** 178 * Client data passed to DebugBreakForCommand function. The 179 * debugger takes ownership of the data and will delete it even if 180 * there is no message handler. 181 */ 182 virtual ClientData* GetClientData() const = 0; 183 ~EventDetails()184 virtual ~EventDetails() {} 185 }; 186 187 188 /** 189 * Debug event callback function. 190 * 191 * \param event the type of the debug event that triggered the callback 192 * (enum DebugEvent) 193 * \param exec_state execution state (JavaScript object) 194 * \param event_data event specific data (JavaScript object) 195 * \param data value passed by the user to SetDebugEventListener 196 */ 197 typedef void (*EventCallback)(DebugEvent event, 198 Handle<Object> exec_state, 199 Handle<Object> event_data, 200 Handle<Value> data); 201 202 /** 203 * Debug event callback function. 204 * 205 * \param event_details object providing information about the debug event 206 * 207 * A EventCallback2 does not take possession of the event data, 208 * and must not rely on the data persisting after the handler returns. 209 */ 210 typedef void (*EventCallback2)(const EventDetails& event_details); 211 212 /** 213 * Debug message callback function. 214 * 215 * \param message the debug message handler message object 216 * \param length length of the message 217 * \param client_data the data value passed when registering the message handler 218 219 * A MessageHandler does not take possession of the message string, 220 * and must not rely on the data persisting after the handler returns. 221 * 222 * This message handler is deprecated. Use MessageHandler2 instead. 223 */ 224 typedef void (*MessageHandler)(const uint16_t* message, int length, 225 ClientData* client_data); 226 227 /** 228 * Debug message callback function. 229 * 230 * \param message the debug message handler message object 231 * 232 * A MessageHandler does not take possession of the message data, 233 * and must not rely on the data persisting after the handler returns. 234 */ 235 typedef void (*MessageHandler2)(const Message& message); 236 237 /** 238 * Debug host dispatch callback function. 239 */ 240 typedef void (*HostDispatchHandler)(); 241 242 /** 243 * Callback function for the host to ensure debug messages are processed. 244 */ 245 typedef void (*DebugMessageDispatchHandler)(); 246 247 // Set a C debug event listener. 248 static bool SetDebugEventListener(EventCallback that, 249 Handle<Value> data = Handle<Value>()); 250 static bool SetDebugEventListener2(EventCallback2 that, 251 Handle<Value> data = Handle<Value>()); 252 253 // Set a JavaScript debug event listener. 254 static bool SetDebugEventListener(v8::Handle<v8::Object> that, 255 Handle<Value> data = Handle<Value>()); 256 257 // Schedule a debugger break to happen when JavaScript code is run 258 // in the given isolate. If no isolate is provided the default 259 // isolate is used. 260 static void DebugBreak(Isolate* isolate = NULL); 261 262 // Remove scheduled debugger break in given isolate if it has not 263 // happened yet. If no isolate is provided the default isolate is 264 // used. 265 static void CancelDebugBreak(Isolate* isolate = NULL); 266 267 // Break execution of JavaScript in the given isolate (this method 268 // can be invoked from a non-VM thread) for further client command 269 // execution on a VM thread. Client data is then passed in 270 // EventDetails to EventCallback at the moment when the VM actually 271 // stops. If no isolate is provided the default isolate is used. 272 static void DebugBreakForCommand(ClientData* data = NULL, 273 Isolate* isolate = NULL); 274 275 // Message based interface. The message protocol is JSON. NOTE the message 276 // handler thread is not supported any more parameter must be false. 277 static void SetMessageHandler(MessageHandler handler, 278 bool message_handler_thread = false); 279 static void SetMessageHandler2(MessageHandler2 handler); 280 281 // If no isolate is provided the default isolate is 282 // used. 283 static void SendCommand(const uint16_t* command, int length, 284 ClientData* client_data = NULL, 285 Isolate* isolate = NULL); 286 287 // Dispatch interface. 288 static void SetHostDispatchHandler(HostDispatchHandler handler, 289 int period = 100); 290 291 /** 292 * Register a callback function to be called when a debug message has been 293 * received and is ready to be processed. For the debug messages to be 294 * processed V8 needs to be entered, and in certain embedding scenarios this 295 * callback can be used to make sure V8 is entered for the debug message to 296 * be processed. Note that debug messages will only be processed if there is 297 * a V8 break. This can happen automatically by using the option 298 * --debugger-auto-break. 299 * \param provide_locker requires that V8 acquires v8::Locker for you before 300 * calling handler 301 */ 302 static void SetDebugMessageDispatchHandler( 303 DebugMessageDispatchHandler handler, bool provide_locker = false); 304 305 /** 306 * Run a JavaScript function in the debugger. 307 * \param fun the function to call 308 * \param data passed as second argument to the function 309 * With this call the debugger is entered and the function specified is called 310 * with the execution state as the first argument. This makes it possible to 311 * get access to information otherwise not available during normal JavaScript 312 * execution e.g. details on stack frames. Receiver of the function call will 313 * be the debugger context global object, however this is a subject to change. 314 * The following example shows a JavaScript function which when passed to 315 * v8::Debug::Call will return the current line of JavaScript execution. 316 * 317 * \code 318 * function frame_source_line(exec_state) { 319 * return exec_state.frame(0).sourceLine(); 320 * } 321 * \endcode 322 */ 323 static Local<Value> Call(v8::Handle<v8::Function> fun, 324 Handle<Value> data = Handle<Value>()); 325 326 /** 327 * Returns a mirror object for the given object. 328 */ 329 static Local<Value> GetMirror(v8::Handle<v8::Value> obj); 330 331 /** 332 * Enable the V8 builtin debug agent. The debugger agent will listen on the 333 * supplied TCP/IP port for remote debugger connection. 334 * \param name the name of the embedding application 335 * \param port the TCP/IP port to listen on 336 * \param wait_for_connection whether V8 should pause on a first statement 337 * allowing remote debugger to connect before anything interesting happened 338 */ 339 static bool EnableAgent(const char* name, int port, 340 bool wait_for_connection = false); 341 342 /** 343 * Disable the V8 builtin debug agent. The TCP/IP connection will be closed. 344 */ 345 static void DisableAgent(); 346 347 /** 348 * Makes V8 process all pending debug messages. 349 * 350 * From V8 point of view all debug messages come asynchronously (e.g. from 351 * remote debugger) but they all must be handled synchronously: V8 cannot 352 * do 2 things at one time so normal script execution must be interrupted 353 * for a while. 354 * 355 * Generally when message arrives V8 may be in one of 3 states: 356 * 1. V8 is running script; V8 will automatically interrupt and process all 357 * pending messages (however auto_break flag should be enabled); 358 * 2. V8 is suspended on debug breakpoint; in this state V8 is dedicated 359 * to reading and processing debug messages; 360 * 3. V8 is not running at all or has called some long-working C++ function; 361 * by default it means that processing of all debug messages will be deferred 362 * until V8 gets control again; however, embedding application may improve 363 * this by manually calling this method. 364 * 365 * It makes sense to call this method whenever a new debug message arrived and 366 * V8 is not already running. Method v8::Debug::SetDebugMessageDispatchHandler 367 * should help with the former condition. 368 * 369 * Technically this method in many senses is equivalent to executing empty 370 * script: 371 * 1. It does nothing except for processing all pending debug messages. 372 * 2. It should be invoked with the same precautions and from the same context 373 * as V8 script would be invoked from, because: 374 * a. with "evaluate" command it can do whatever normal script can do, 375 * including all native calls; 376 * b. no other thread should call V8 while this method is running 377 * (v8::Locker may be used here). 378 * 379 * "Evaluate" debug command behavior currently is not specified in scope 380 * of this method. 381 */ 382 static void ProcessDebugMessages(); 383 384 /** 385 * Debugger is running in its own context which is entered while debugger 386 * messages are being dispatched. This is an explicit getter for this 387 * debugger context. Note that the content of the debugger context is subject 388 * to change. 389 */ 390 static Local<Context> GetDebugContext(); 391 }; 392 393 394 } // namespace v8 395 396 397 #undef EXPORT 398 399 400 #endif // V8_V8_DEBUG_H_ 401