v8  3.11.10 (node 0.8.28)
V8 is Google's open source JavaScript engine
v8-debug.h
Go to the documentation of this file.
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,
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:
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 
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 
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.
249  Handle<Value> data = Handle<Value>());
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.
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  */
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  */
391 };
392 
393 
394 } // namespace v8
395 
396 
397 #undef EXPORT
398 
399 
400 #endif // V8_V8_DEBUG_H_