v8  4.2.77(io.js2.5.0)
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 // 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,
26 };
27 
28 
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:
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 
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 
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_
virtual DebugEvent GetEvent() const =0
virtual bool WillStartRunning() const =0
virtual ~Message()
Definition: v8-debug.h:90
Definition: v8.h:1593
virtual Handle< Object > GetEventData() const =0
V8_INLINE Handle()
Definition: v8.h:222
DebugEvent
Definition: v8-debug.h:16
virtual Handle< Value > GetCallbackData() const =0
static Local< Context > GetDebugContext()
virtual DebugEvent GetEvent() const =0
virtual bool IsEvent() const =0
virtual ClientData * GetClientData() const =0
virtual bool IsResponse() const =0
virtual ~EventDetails()
Definition: v8-debug.h:131
virtual Isolate * GetIsolate() const =0
static bool SetDebugEventListener(EventCallback that, Handle< Value > data=Handle< Value >())
void(* MessageHandler)(const Message &message)
Definition: v8-debug.h:152
static void DebugBreakForCommand(Isolate *isolate, ClientData *data)
Definition: libplatform.h:10
virtual Handle< Object > GetExecutionState() const =0
virtual Handle< String > GetJSON() const =0
static void DebugBreak(Isolate *isolate)
static bool CheckDebugBreak(Isolate *isolate)
static void CancelDebugBreak(Isolate *isolate)
virtual ClientData * GetClientData() const =0
static void SendCommand(Isolate *isolate, const uint16_t *command, int length, ClientData *client_data=NULL)
virtual Handle< Object > GetEventData() const =0
static Local< Value > Call(v8::Handle< v8::Function > fun, Handle< Value > data=Handle< Value >())
virtual ~ClientData()
Definition: v8-debug.h:37
virtual Handle< Object > GetExecutionState() const =0
virtual Handle< Context > GetEventContext() const =0
virtual Handle< Context > GetEventContext() const =0
static void SetMessageHandler(MessageHandler handler)
void(* EventCallback)(const EventDetails &event_details)
Definition: v8-debug.h:142
static void SetLiveEditEnabled(Isolate *isolate, bool enable)
static Local< Value > GetMirror(v8::Handle< v8::Value > obj)
#define V8_EXPORT
Definition: v8.h:57
static void ProcessDebugMessages()
void(* DebugMessageDispatchHandler)()
Definition: v8-debug.h:157