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: ~ClientData()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 ~Message()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 // Set a C debug event listener. 192 static bool SetDebugEventListener(EventCallback that, 193 Handle<Value> data = Handle<Value>()); 194 195 // Set a JavaScript debug event listener. 196 static bool SetDebugEventListener(v8::Handle<v8::Object> that, 197 Handle<Value> data = Handle<Value>()); 198 199 // Break execution of JavaScript. 200 static void DebugBreak(); 201 202 // Message based interface. The message protocol is JSON. NOTE the message 203 // handler thread is not supported any more parameter must be false. 204 static void SetMessageHandler(MessageHandler handler, 205 bool message_handler_thread = false); 206 static void SetMessageHandler2(MessageHandler2 handler); 207 static void SendCommand(const uint16_t* command, int length, 208 ClientData* client_data = NULL); 209 210 // Dispatch interface. 211 static void SetHostDispatchHandler(HostDispatchHandler handler, 212 int period = 100); 213 214 /** 215 * Run a JavaScript function in the debugger. 216 * \param fun the function to call 217 * \param data passed as second argument to the function 218 * With this call the debugger is entered and the function specified is called 219 * with the execution state as the first argument. This makes it possible to 220 * get access to information otherwise not available during normal JavaScript 221 * execution e.g. details on stack frames. The following example show a 222 * JavaScript function which when passed to v8::Debug::Call will return the 223 * current line of JavaScript execution. 224 * 225 * \code 226 * function frame_source_line(exec_state) { 227 * return exec_state.frame(0).sourceLine(); 228 * } 229 * \endcode 230 */ 231 static Local<Value> Call(v8::Handle<v8::Function> fun, 232 Handle<Value> data = Handle<Value>()); 233 234 /** 235 * Returns a mirror object for the given object. 236 */ 237 static Local<Value> GetMirror(v8::Handle<v8::Value> obj); 238 239 /** 240 * Enable the V8 builtin debug agent. The debugger agent will listen on the 241 * supplied TCP/IP port for remote debugger connection. 242 * \param name the name of the embedding application 243 * \param port the TCP/IP port to listen on 244 */ 245 static bool EnableAgent(const char* name, int port); 246 }; 247 248 249 } // namespace v8 250 251 252 #undef EXPORT 253 254 255 #endif // V8_V8_DEBUG_H_ 256