v8  5.1.281(node6.10.3)
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" // NOLINT(build/include)
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,
24 };
25 
27  public:
28  /**
29  * A client object passed to the v8 debugger whose ownership will be taken by
30  * it. v8 is always responsible for deleting the object.
31  */
32  class ClientData {
33  public:
34  virtual ~ClientData() {}
35  };
36 
37 
38  /**
39  * A message object passed to the debug message handler.
40  */
41  class Message {
42  public:
43  /**
44  * Check type of message.
45  */
46  virtual bool IsEvent() const = 0;
47  virtual bool IsResponse() const = 0;
48  virtual DebugEvent GetEvent() const = 0;
49 
50  /**
51  * Indicate whether this is a response to a continue command which will
52  * start the VM running after this is processed.
53  */
54  virtual bool WillStartRunning() const = 0;
55 
56  /**
57  * Access to execution state and event data. Don't store these cross
58  * callbacks as their content becomes invalid. These objects are from the
59  * debugger event that started the debug message loop.
60  */
61  virtual Local<Object> GetExecutionState() const = 0;
62  virtual Local<Object> GetEventData() const = 0;
63 
64  /**
65  * Get the debugger protocol JSON.
66  */
67  virtual Local<String> GetJSON() const = 0;
68 
69  /**
70  * Get the context active when the debug event happened. Note this is not
71  * the current active context as the JavaScript part of the debugger is
72  * running in its own context which is entered at this point.
73  */
74  virtual Local<Context> GetEventContext() const = 0;
75 
76  /**
77  * Client data passed with the corresponding request if any. This is the
78  * client_data data value passed into Debug::SendCommand along with the
79  * request that led to the message or NULL if the message is an event. The
80  * debugger takes ownership of the data and will delete it even if there is
81  * no message handler.
82  */
83  virtual ClientData* GetClientData() const = 0;
84 
85  virtual Isolate* GetIsolate() const = 0;
86 
87  virtual ~Message() {}
88  };
89 
90 
91  /**
92  * An event details object passed to the debug event listener.
93  */
94  class EventDetails {
95  public:
96  /**
97  * Event type.
98  */
99  virtual DebugEvent GetEvent() const = 0;
100 
101  /**
102  * Access to execution state and event data of the debug event. Don't store
103  * these cross callbacks as their content becomes invalid.
104  */
105  virtual Local<Object> GetExecutionState() const = 0;
106  virtual Local<Object> GetEventData() const = 0;
107 
108  /**
109  * Get the context active when the debug event happened. Note this is not
110  * the current active context as the JavaScript part of the debugger is
111  * running in its own context which is entered at this point.
112  */
113  virtual Local<Context> GetEventContext() const = 0;
114 
115  /**
116  * Client data passed with the corresponding callback when it was
117  * registered.
118  */
119  virtual Local<Value> GetCallbackData() const = 0;
120 
121  /**
122  * Client data passed to DebugBreakForCommand function. The
123  * debugger takes ownership of the data and will delete it even if
124  * there is no message handler.
125  */
126  virtual ClientData* GetClientData() const = 0;
127 
128  virtual ~EventDetails() {}
129  };
130 
131  /**
132  * Debug event callback function.
133  *
134  * \param event_details object providing information about the debug event
135  *
136  * A EventCallback2 does not take possession of the event data,
137  * and must not rely on the data persisting after the handler returns.
138  */
139  typedef void (*EventCallback)(const EventDetails& event_details);
140 
141  /**
142  * Debug message callback function.
143  *
144  * \param message the debug message handler message object
145  *
146  * A MessageHandler2 does not take possession of the message data,
147  * and must not rely on the data persisting after the handler returns.
148  */
149  typedef void (*MessageHandler)(const Message& message);
150 
151  /**
152  * Callback function for the host to ensure debug messages are processed.
153  */
154  typedef void (*DebugMessageDispatchHandler)();
155 
156  static bool SetDebugEventListener(Isolate* isolate, EventCallback that,
157  Local<Value> data = Local<Value>());
158  V8_DEPRECATED("Use version with an Isolate",
159  static bool SetDebugEventListener(
160  EventCallback that, Local<Value> data = Local<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  // Message based interface. The message protocol is JSON.
174  static void SetMessageHandler(Isolate* isolate, MessageHandler handler);
175  V8_DEPRECATED("Use version with an Isolate",
176  static void SetMessageHandler(MessageHandler handler));
177 
178  static void SendCommand(Isolate* isolate,
179  const uint16_t* command, int length,
180  ClientData* client_data = NULL);
181 
182  /**
183  * Run a JavaScript function in the debugger.
184  * \param fun the function to call
185  * \param data passed as second argument to the function
186  * With this call the debugger is entered and the function specified is called
187  * with the execution state as the first argument. This makes it possible to
188  * get access to information otherwise not available during normal JavaScript
189  * execution e.g. details on stack frames. Receiver of the function call will
190  * be the debugger context global object, however this is a subject to change.
191  * The following example shows a JavaScript function which when passed to
192  * v8::Debug::Call will return the current line of JavaScript execution.
193  *
194  * \code
195  * function frame_source_line(exec_state) {
196  * return exec_state.frame(0).sourceLine();
197  * }
198  * \endcode
199  */
200  static V8_DEPRECATED("Use maybe version",
201  Local<Value> Call(v8::Local<v8::Function> fun,
202  Local<Value> data = Local<Value>()));
203  // TODO(dcarney): data arg should be a MaybeLocal
204  static MaybeLocal<Value> Call(Local<Context> context,
205  v8::Local<v8::Function> fun,
206  Local<Value> data = Local<Value>());
207 
208  /**
209  * Returns a mirror object for the given object.
210  */
211  static V8_DEPRECATED("Use maybe version",
212  Local<Value> GetMirror(v8::Local<v8::Value> obj));
213  static MaybeLocal<Value> GetMirror(Local<Context> context,
214  v8::Local<v8::Value> obj);
215 
216  /**
217  * Makes V8 process all pending debug messages.
218  *
219  * From V8 point of view all debug messages come asynchronously (e.g. from
220  * remote debugger) but they all must be handled synchronously: V8 cannot
221  * do 2 things at one time so normal script execution must be interrupted
222  * for a while.
223  *
224  * Generally when message arrives V8 may be in one of 3 states:
225  * 1. V8 is running script; V8 will automatically interrupt and process all
226  * pending messages;
227  * 2. V8 is suspended on debug breakpoint; in this state V8 is dedicated
228  * to reading and processing debug messages;
229  * 3. V8 is not running at all or has called some long-working C++ function;
230  * by default it means that processing of all debug messages will be deferred
231  * until V8 gets control again; however, embedding application may improve
232  * this by manually calling this method.
233  *
234  * Technically this method in many senses is equivalent to executing empty
235  * script:
236  * 1. It does nothing except for processing all pending debug messages.
237  * 2. It should be invoked with the same precautions and from the same context
238  * as V8 script would be invoked from, because:
239  * a. with "evaluate" command it can do whatever normal script can do,
240  * including all native calls;
241  * b. no other thread should call V8 while this method is running
242  * (v8::Locker may be used here).
243  *
244  * "Evaluate" debug command behavior currently is not specified in scope
245  * of this method.
246  */
247  static void ProcessDebugMessages(Isolate* isolate);
248  V8_DEPRECATED("Use version with an Isolate",
249  static void ProcessDebugMessages());
250 
251  /**
252  * Debugger is running in its own context which is entered while debugger
253  * messages are being dispatched. This is an explicit getter for this
254  * debugger context. Note that the content of the debugger context is subject
255  * to change. The Context exists only when the debugger is active, i.e. at
256  * least one DebugEventListener or MessageHandler is set.
257  */
258  static Local<Context> GetDebugContext(Isolate* isolate);
259  V8_DEPRECATED("Use version with an Isolate",
260  static Local<Context> GetDebugContext());
261 
262 
263  /**
264  * Enable/disable LiveEdit functionality for the given Isolate
265  * (default Isolate if not provided). V8 will abort if LiveEdit is
266  * unexpectedly used. LiveEdit is enabled by default.
267  */
268  static void SetLiveEditEnabled(Isolate* isolate, bool enable);
269 
270  /**
271  * Returns array of internal properties specific to the value type. Result has
272  * the following format: [<name>, <value>,...,<name>, <value>]. Result array
273  * will be allocated in the current context.
274  */
275  static MaybeLocal<Array> GetInternalProperties(Isolate* isolate,
276  Local<Value> value);
277 
278  /**
279  * Defines if the ES2015 tail call elimination feature is enabled or not.
280  * The change of this flag triggers deoptimization of all functions that
281  * contain calls at tail position.
282  */
283  static bool IsTailCallEliminationEnabled(Isolate* isolate);
284  static void SetTailCallEliminationEnabled(Isolate* isolate, bool enabled);
285 };
286 
287 
288 } // namespace v8
289 
290 
291 #undef EXPORT
292 
293 
294 #endif // V8_V8_DEBUG_H_
virtual Local< Value > GetCallbackData() const =0
virtual DebugEvent GetEvent() const =0
virtual Local< Context > GetEventContext() const =0
virtual bool WillStartRunning() const =0
virtual Local< Object > GetEventData() const =0
virtual ~Message()
Definition: v8-debug.h:87
static MaybeLocal< Value > Call(Local< Context > context, v8::Local< v8::Function > fun, Local< Value > data=Local< Value >())
Definition: v8.h:1707
virtual Local< Object > GetExecutionState() const =0
static void ProcessDebugMessages(Isolate *isolate)
DebugEvent
Definition: v8-debug.h:16
static void SetTailCallEliminationEnabled(Isolate *isolate, bool enabled)
virtual DebugEvent GetEvent() const =0
virtual bool IsEvent() const =0
virtual ClientData * GetClientData() const =0
static MaybeLocal< Value > GetMirror(Local< Context > context, v8::Local< v8::Value > obj)
virtual bool IsResponse() const =0
virtual Local< Context > GetEventContext() const =0
virtual ~EventDetails()
Definition: v8-debug.h:128
virtual Isolate * GetIsolate() const =0
virtual Local< String > GetJSON() const =0
static bool IsTailCallEliminationEnabled(Isolate *isolate)
void(* MessageHandler)(const Message &message)
Definition: v8-debug.h:149
Definition: libplatform.h:10
V8_INLINE Local()
Definition: v8.h:220
static bool SetDebugEventListener(Isolate *isolate, EventCallback that, Local< Value > data=Local< Value >())
static void DebugBreak(Isolate *isolate)
static bool CheckDebugBreak(Isolate *isolate)
#define V8_DEPRECATED(message, declarator)
Definition: v8config.h:340
static void SetMessageHandler(Isolate *isolate, MessageHandler handler)
Definition: v8.h:3010
static MaybeLocal< Array > GetInternalProperties(Isolate *isolate, Local< Value > value)
static void CancelDebugBreak(Isolate *isolate)
static Local< Context > GetDebugContext(Isolate *isolate)
virtual ClientData * GetClientData() const =0
virtual Local< Object > GetEventData() const =0
static void SendCommand(Isolate *isolate, const uint16_t *command, int length, ClientData *client_data=NULL)
virtual ~ClientData()
Definition: v8-debug.h:34
void(* EventCallback)(const EventDetails &event_details)
Definition: v8-debug.h:139
static void SetLiveEditEnabled(Isolate *isolate, bool enable)
#define V8_EXPORT
Definition: v8.h:60
virtual Local< Object > GetExecutionState() const =0
void(* DebugMessageDispatchHandler)()
Definition: v8-debug.h:154