Steve Block | a7e24c1 | 2009-10-30 11:49:00 +0000 | [diff] [blame] | 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 | |
Steve Block | d0582a6 | 2009-12-15 09:54:21 +0000 | [diff] [blame] | 191 | /** |
| 192 | * Callback function for the host to ensure debug messages are processed. |
| 193 | */ |
| 194 | typedef void (*DebugMessageDispatchHandler)(); |
| 195 | |
Steve Block | a7e24c1 | 2009-10-30 11:49:00 +0000 | [diff] [blame] | 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 | |
Steve Block | d0582a6 | 2009-12-15 09:54:21 +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. |
Leon Clarke | e46be81 | 2010-01-19 14:06:41 +0000 | [diff] [blame] | 227 | * \param provide_locker requires that V8 acquires v8::Locker for you before |
| 228 | * calling handler |
Steve Block | d0582a6 | 2009-12-15 09:54:21 +0000 | [diff] [blame] | 229 | */ |
| 230 | static void SetDebugMessageDispatchHandler( |
Leon Clarke | e46be81 | 2010-01-19 14:06:41 +0000 | [diff] [blame] | 231 | DebugMessageDispatchHandler handler, bool provide_locker = false); |
Steve Block | d0582a6 | 2009-12-15 09:54:21 +0000 | [diff] [blame] | 232 | |
Steve Block | a7e24c1 | 2009-10-30 11:49:00 +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 |
| 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 |
Leon Clarke | e46be81 | 2010-01-19 14:06:41 +0000 | [diff] [blame] | 263 | * \param wait_for_connection whether V8 should pause on a first statement |
| 264 | * allowing remote debugger to connect before anything interesting happened |
Steve Block | a7e24c1 | 2009-10-30 11:49:00 +0000 | [diff] [blame] | 265 | */ |
Leon Clarke | e46be81 | 2010-01-19 14:06:41 +0000 | [diff] [blame] | 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(); |
Steve Block | a7e24c1 | 2009-10-30 11:49:00 +0000 | [diff] [blame] | 305 | }; |
| 306 | |
| 307 | |
| 308 | } // namespace v8 |
| 309 | |
| 310 | |
| 311 | #undef EXPORT |
| 312 | |
| 313 | |
| 314 | #endif // V8_V8_DEBUG_H_ |