v8  6.2.414 (node 8.16.2)
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  * ATTENTION: The debugger API exposed by this file is deprecated and will be
12  * removed by the end of 2017. Please use the V8 inspector declared
13  * in include/v8-inspector.h instead.
14  */
15 namespace v8 {
16 
17 // Debug events which can occur in the V8 JavaScript engine.
18 enum DebugEvent {
19  Break = 1,
20  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  * An event details object passed to the debug event listener.
92  */
93  class EventDetails {
94  public:
95  /**
96  * Event type.
97  */
98  virtual DebugEvent GetEvent() const = 0;
99 
100  /**
101  * Access to execution state and event data of the debug event. Don't store
102  * these cross callbacks as their content becomes invalid.
103  */
104  virtual Local<Object> GetExecutionState() const = 0;
105  virtual Local<Object> GetEventData() const = 0;
106 
107  /**
108  * Get the context active when the debug event happened. Note this is not
109  * the current active context as the JavaScript part of the debugger is
110  * running in its own context which is entered at this point.
111  */
112  virtual Local<Context> GetEventContext() const = 0;
113 
114  /**
115  * Client data passed with the corresponding callback when it was
116  * registered.
117  */
118  virtual Local<Value> GetCallbackData() const = 0;
119 
120  /**
121  * This is now a dummy that returns nullptr.
122  */
123  virtual ClientData* GetClientData() const = 0;
124 
125  virtual Isolate* GetIsolate() const = 0;
126 
127  virtual ~EventDetails() {}
128  };
129 
130  /**
131  * Debug event callback function.
132  *
133  * \param event_details object providing information about the debug event
134  *
135  * A EventCallback does not take possession of the event data,
136  * and must not rely on the data persisting after the handler returns.
137  */
138  typedef void (*EventCallback)(const EventDetails& event_details);
139 
140  /**
141  * This is now a no-op.
142  */
143  typedef void (*MessageHandler)(const Message& message);
144 
145  V8_DEPRECATED("No longer supported", static bool SetDebugEventListener(
146  Isolate* isolate, EventCallback that,
147  Local<Value> data = Local<Value>()));
148 
149  // Schedule a debugger break to happen when JavaScript code is run
150  // in the given isolate.
151  V8_DEPRECATED("No longer supported",
152  static void DebugBreak(Isolate* isolate));
153 
154  // Remove scheduled debugger break in given isolate if it has not
155  // happened yet.
156  V8_DEPRECATED("No longer supported",
157  static void CancelDebugBreak(Isolate* isolate));
158 
159  // Check if a debugger break is scheduled in the given isolate.
160  V8_DEPRECATED("No longer supported",
161  static bool CheckDebugBreak(Isolate* isolate));
162 
163  // This is now a no-op.
164  V8_DEPRECATED("No longer supported",
165  static void SetMessageHandler(Isolate* isolate,
166  MessageHandler handler));
167 
168  // This is now a no-op.
169  V8_DEPRECATED("No longer supported",
170  static void SendCommand(Isolate* isolate,
171  const uint16_t* command, int length,
172  ClientData* client_data = NULL));
173 
174  /**
175  * Run a JavaScript function in the debugger.
176  * \param fun the function to call
177  * \param data passed as second argument to the function
178  * With this call the debugger is entered and the function specified is called
179  * with the execution state as the first argument. This makes it possible to
180  * get access to information otherwise not available during normal JavaScript
181  * execution e.g. details on stack frames. Receiver of the function call will
182  * be the debugger context global object, however this is a subject to change.
183  * The following example shows a JavaScript function which when passed to
184  * v8::Debug::Call will return the current line of JavaScript execution.
185  *
186  * \code
187  * function frame_source_line(exec_state) {
188  * return exec_state.frame(0).sourceLine();
189  * }
190  * \endcode
191  */
192  V8_DEPRECATED("No longer supported",
193  static MaybeLocal<Value> Call(
194  Local<Context> context, v8::Local<v8::Function> fun,
195  Local<Value> data = Local<Value>()));
196 
197  // This is now a no-op.
198  V8_DEPRECATED("No longer supported",
199  static void ProcessDebugMessages(Isolate* isolate));
200 
201  /**
202  * Debugger is running in its own context which is entered while debugger
203  * messages are being dispatched. This is an explicit getter for this
204  * debugger context. Note that the content of the debugger context is subject
205  * to change. The Context exists only when the debugger is active, i.e. at
206  * least one DebugEventListener or MessageHandler is set.
207  */
208  V8_DEPRECATED("Use v8-inspector",
209  static Local<Context> GetDebugContext(Isolate* isolate));
210 
211  /**
212  * While in the debug context, this method returns the top-most non-debug
213  * context, if it exists.
214  */
216  "No longer supported",
217  static MaybeLocal<Context> GetDebuggedContext(Isolate* isolate));
218 
219  /**
220  * Enable/disable LiveEdit functionality for the given Isolate
221  * (default Isolate if not provided). V8 will abort if LiveEdit is
222  * unexpectedly used. LiveEdit is enabled by default.
223  */
224  V8_DEPRECATED("No longer supported",
225  static void SetLiveEditEnabled(Isolate* isolate, bool enable));
226 
227  /**
228  * Returns array of internal properties specific to the value type. Result has
229  * the following format: [<name>, <value>,...,<name>, <value>]. Result array
230  * will be allocated in the current context.
231  */
232  V8_DEPRECATED("No longer supported",
233  static MaybeLocal<Array> GetInternalProperties(
234  Isolate* isolate, Local<Value> value));
235 
236  /**
237  * Defines if the ES2015 tail call elimination feature is enabled or not.
238  * The change of this flag triggers deoptimization of all functions that
239  * contain calls at tail position.
240  */
241  V8_DEPRECATED("No longer supported",
242  static bool IsTailCallEliminationEnabled(Isolate* isolate));
243  V8_DEPRECATED("No longer supported",
244  static void SetTailCallEliminationEnabled(Isolate* isolate,
245  bool enabled));
246 };
247 
248 
249 } // namespace v8
250 
251 
252 #undef EXPORT
253 
254 
255 #endif // V8_V8_DEBUG_H_