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 }; 81 82 83 class EXPORT Debug { 84 public: 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 /** 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 /** 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, 156 Handle<Object> exec_state, 157 Handle<Object> event_data, 158 Handle<Value> data); 159 160 161 /** 162 * Debug message callback function. 163 * 164 * \param message the debug message handler message object 165 * \param length length of the message 166 * \param client_data the data value passed when registering the message handler 167 168 * A MessageHandler does not take posession of the message string, 169 * and must not rely on the data persisting after the handler returns. 170 * 171 * This message handler is deprecated. Use MessageHandler2 instead. 172 */ 173 typedef void (*MessageHandler)(const uint16_t* message, int length, 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); 185 186 /** 187 * Debug host dispatch callback function. 188 */ 189 typedef void (*HostDispatchHandler)(); 190 191 /** 192 * Callback function for the host to ensure debug messages are processed. 193 */ 194 typedef void (*DebugMessageDispatchHandler)(); 195 196 // Set a C debug event listener. 197 static bool SetDebugEventListener(EventCallback that, 198 Handle<Value> data = Handle<Value>()); 199 200 // Set a JavaScript debug event listener. 201 static bool SetDebugEventListener(v8::Handle<v8::Object> that, 202 Handle<Value> data = Handle<Value>()); 203 204 // Break execution of JavaScript. 205 static void DebugBreak(); 206 207 // Message based interface. The message protocol is JSON. NOTE the message 208 // handler thread is not supported any more parameter must be false. 209 static void SetMessageHandler(MessageHandler handler, 210 bool message_handler_thread = false); 211 static void SetMessageHandler2(MessageHandler2 handler); 212 static void SendCommand(const uint16_t* command, int length, 213 ClientData* client_data = NULL); 214 215 // Dispatch interface. 216 static void SetHostDispatchHandler(HostDispatchHandler handler, 217 int period = 100); 218 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. 227 * \param provide_locker requires that V8 acquires v8::Locker for you before 228 * calling handler 229 */ 230 static void SetDebugMessageDispatchHandler( 231 DebugMessageDispatchHandler handler, bool provide_locker = false); 232 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 240 * execution e.g. details on stack frames. The following example show a 241 * JavaScript function which when passed to v8::Debug::Call will return the 242 * current line of JavaScript execution. 243 * 244 * \code 245 * function frame_source_line(exec_state) { 246 * return exec_state.frame(0).sourceLine(); 247 * } 248 * \endcode 249 */ 250 static Local<Value> Call(v8::Handle<v8::Function> fun, 251 Handle<Value> data = Handle<Value>()); 252 253 /** 254 * Returns a mirror object for the given object. 255 */ 256 static Local<Value> GetMirror(v8::Handle<v8::Value> obj); 257 258 /** 259 * Enable the V8 builtin debug agent. The debugger agent will listen on the 260 * supplied TCP/IP port for remote debugger connection. 261 * \param name the name of the embedding application 262 * \param port the TCP/IP port to listen on 263 * \param wait_for_connection whether V8 should pause on a first statement 264 * allowing remote debugger to connect before anything interesting happened 265 */ 266 static bool EnableAgent(const char* name, int port, 267 bool wait_for_connection = false); 268 269 /** 270 * Makes V8 process all pending debug messages. 271 * 272 * From V8 point of view all debug messages come asynchronously (e.g. from 273 * remote debugger) but they all must be handled synchronously: V8 cannot 274 * do 2 things at one time so normal script execution must be interrupted 275 * for a while. 276 * 277 * Generally when message arrives V8 may be in one of 3 states: 278 * 1. V8 is running script; V8 will automatically interrupt and process all 279 * pending messages (however auto_break flag should be enabled); 280 * 2. V8 is suspended on debug breakpoint; in this state V8 is dedicated 281 * to reading and processing debug messages; 282 * 3. V8 is not running at all or has called some long-working C++ function; 283 * by default it means that processing of all debug message will be deferred 284 * until V8 gets control again; however, embedding application may improve 285 * this by manually calling this method. 286 * 287 * It makes sense to call this method whenever a new debug message arrived and 288 * V8 is not already running. Method v8::Debug::SetDebugMessageDispatchHandler 289 * should help with the former condition. 290 * 291 * Technically this method in many senses is equivalent to executing empty 292 * script: 293 * 1. It does nothing except for processing all pending debug messages. 294 * 2. It should be invoked with the same precautions and from the same context 295 * as V8 script would be invoked from, because: 296 * a. with "evaluate" command it can do whatever normal script can do, 297 * including all native calls; 298 * b. no other thread should call V8 while this method is running 299 * (v8::Locker may be used here). 300 * 301 * "Evaluate" debug command behavior currently is not specified in scope 302 * of this method. 303 */ 304 static void ProcessDebugMessages(); 305 }; 306 307 308 } // namespace v8 309 310 311 #undef EXPORT 312 313 314 #endif // V8_V8_DEBUG_H_ 315
