1 // Copyright 2008 the V8 project authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef V8_V8_DEBUG_H_ 6 #define V8_V8_DEBUG_H_ 7 8 #include "v8.h" 9 10 /** 11 * Debugger support for the V8 JavaScript engine. 12 */ 13 namespace v8 { 14 15 // Debug events which can occur in the V8 JavaScript engine. 16 enum DebugEvent { 17 Break = 1, 18 Exception = 2, 19 NewFunction = 3, 20 BeforeCompile = 4, 21 AfterCompile = 5, 22 CompileError = 6, 23 PromiseEvent = 7, 24 AsyncTaskEvent = 8, 25 BreakForCommand = 9 26 }; 27 28 29 class V8_EXPORT Debug { 30 public: 31 /** 32 * A client object passed to the v8 debugger whose ownership will be taken by 33 * it. v8 is always responsible for deleting the object. 34 */ 35 class ClientData { 36 public: ~ClientData()37 virtual ~ClientData() {} 38 }; 39 40 41 /** 42 * A message object passed to the debug message handler. 43 */ 44 class Message { 45 public: 46 /** 47 * Check type of message. 48 */ 49 virtual bool IsEvent() const = 0; 50 virtual bool IsResponse() const = 0; 51 virtual DebugEvent GetEvent() const = 0; 52 53 /** 54 * Indicate whether this is a response to a continue command which will 55 * start the VM running after this is processed. 56 */ 57 virtual bool WillStartRunning() const = 0; 58 59 /** 60 * Access to execution state and event data. Don't store these cross 61 * callbacks as their content becomes invalid. These objects are from the 62 * debugger event that started the debug message loop. 63 */ 64 virtual Handle<Object> GetExecutionState() const = 0; 65 virtual Handle<Object> GetEventData() const = 0; 66 67 /** 68 * Get the debugger protocol JSON. 69 */ 70 virtual Handle<String> GetJSON() const = 0; 71 72 /** 73 * Get the context active when the debug event happened. Note this is not 74 * the current active context as the JavaScript part of the debugger is 75 * running in its own context which is entered at this point. 76 */ 77 virtual Handle<Context> GetEventContext() const = 0; 78 79 /** 80 * Client data passed with the corresponding request if any. This is the 81 * client_data data value passed into Debug::SendCommand along with the 82 * request that led to the message or NULL if the message is an event. The 83 * debugger takes ownership of the data and will delete it even if there is 84 * no message handler. 85 */ 86 virtual ClientData* GetClientData() const = 0; 87 88 virtual Isolate* GetIsolate() const = 0; 89 ~Message()90 virtual ~Message() {} 91 }; 92 93 94 /** 95 * An event details object passed to the debug event listener. 96 */ 97 class EventDetails { 98 public: 99 /** 100 * Event type. 101 */ 102 virtual DebugEvent GetEvent() const = 0; 103 104 /** 105 * Access to execution state and event data of the debug event. Don't store 106 * these cross callbacks as their content becomes invalid. 107 */ 108 virtual Handle<Object> GetExecutionState() const = 0; 109 virtual Handle<Object> GetEventData() const = 0; 110 111 /** 112 * Get the context active when the debug event happened. Note this is not 113 * the current active context as the JavaScript part of the debugger is 114 * running in its own context which is entered at this point. 115 */ 116 virtual Handle<Context> GetEventContext() const = 0; 117 118 /** 119 * Client data passed with the corresponding callback when it was 120 * registered. 121 */ 122 virtual Handle<Value> GetCallbackData() const = 0; 123 124 /** 125 * Client data passed to DebugBreakForCommand function. The 126 * debugger takes ownership of the data and will delete it even if 127 * there is no message handler. 128 */ 129 virtual ClientData* GetClientData() const = 0; 130 ~EventDetails()131 virtual ~EventDetails() {} 132 }; 133 134 /** 135 * Debug event callback function. 136 * 137 * \param event_details object providing information about the debug event 138 * 139 * A EventCallback2 does not take possession of the event data, 140 * and must not rely on the data persisting after the handler returns. 141 */ 142 typedef void (*EventCallback)(const EventDetails& event_details); 143 144 /** 145 * Debug message callback function. 146 * 147 * \param message the debug message handler message object 148 * 149 * A MessageHandler2 does not take possession of the message data, 150 * and must not rely on the data persisting after the handler returns. 151 */ 152 typedef void (*MessageHandler)(const Message& message); 153 154 /** 155 * Callback function for the host to ensure debug messages are processed. 156 */ 157 typedef void (*DebugMessageDispatchHandler)(); 158 159 static bool SetDebugEventListener(EventCallback that, 160 Handle<Value> data = Handle<Value>()); 161 162 // Schedule a debugger break to happen when JavaScript code is run 163 // in the given isolate. 164 static void DebugBreak(Isolate* isolate); 165 166 // Remove scheduled debugger break in given isolate if it has not 167 // happened yet. 168 static void CancelDebugBreak(Isolate* isolate); 169 170 // Check if a debugger break is scheduled in the given isolate. 171 static bool CheckDebugBreak(Isolate* isolate); 172 173 // Break execution of JavaScript in the given isolate (this method 174 // can be invoked from a non-VM thread) for further client command 175 // execution on a VM thread. Client data is then passed in 176 // EventDetails to EventCallback2 at the moment when the VM actually 177 // stops. 178 static void DebugBreakForCommand(Isolate* isolate, ClientData* data); 179 180 // Message based interface. The message protocol is JSON. 181 static void SetMessageHandler(MessageHandler handler); 182 183 static void SendCommand(Isolate* isolate, 184 const uint16_t* command, int length, 185 ClientData* client_data = NULL); 186 187 /** 188 * Run a JavaScript function in the debugger. 189 * \param fun the function to call 190 * \param data passed as second argument to the function 191 * With this call the debugger is entered and the function specified is called 192 * with the execution state as the first argument. This makes it possible to 193 * get access to information otherwise not available during normal JavaScript 194 * execution e.g. details on stack frames. Receiver of the function call will 195 * be the debugger context global object, however this is a subject to change. 196 * The following example shows a JavaScript function which when passed to 197 * v8::Debug::Call will return the current line of JavaScript execution. 198 * 199 * \code 200 * function frame_source_line(exec_state) { 201 * return exec_state.frame(0).sourceLine(); 202 * } 203 * \endcode 204 */ 205 static Local<Value> Call(v8::Handle<v8::Function> fun, 206 Handle<Value> data = Handle<Value>()); 207 208 /** 209 * Returns a mirror object for the given object. 210 */ 211 static Local<Value> GetMirror(v8::Handle<v8::Value> obj); 212 213 /** 214 * Makes V8 process all pending debug messages. 215 * 216 * From V8 point of view all debug messages come asynchronously (e.g. from 217 * remote debugger) but they all must be handled synchronously: V8 cannot 218 * do 2 things at one time so normal script execution must be interrupted 219 * for a while. 220 * 221 * Generally when message arrives V8 may be in one of 3 states: 222 * 1. V8 is running script; V8 will automatically interrupt and process all 223 * pending messages; 224 * 2. V8 is suspended on debug breakpoint; in this state V8 is dedicated 225 * to reading and processing debug messages; 226 * 3. V8 is not running at all or has called some long-working C++ function; 227 * by default it means that processing of all debug messages will be deferred 228 * until V8 gets control again; however, embedding application may improve 229 * this by manually calling this method. 230 * 231 * Technically this method in many senses is equivalent to executing empty 232 * script: 233 * 1. It does nothing except for processing all pending debug messages. 234 * 2. It should be invoked with the same precautions and from the same context 235 * as V8 script would be invoked from, because: 236 * a. with "evaluate" command it can do whatever normal script can do, 237 * including all native calls; 238 * b. no other thread should call V8 while this method is running 239 * (v8::Locker may be used here). 240 * 241 * "Evaluate" debug command behavior currently is not specified in scope 242 * of this method. 243 */ 244 static void ProcessDebugMessages(); 245 246 /** 247 * Debugger is running in its own context which is entered while debugger 248 * messages are being dispatched. This is an explicit getter for this 249 * debugger context. Note that the content of the debugger context is subject 250 * to change. 251 */ 252 static Local<Context> GetDebugContext(); 253 254 255 /** 256 * Enable/disable LiveEdit functionality for the given Isolate 257 * (default Isolate if not provided). V8 will abort if LiveEdit is 258 * unexpectedly used. LiveEdit is enabled by default. 259 */ 260 static void SetLiveEditEnabled(Isolate* isolate, bool enable); 261 }; 262 263 264 } // namespace v8 265 266 267 #undef EXPORT 268 269 270 #endif // V8_V8_DEBUG_H_ 271