Line data Source code
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,
21 : AfterCompile = 3,
22 : CompileError = 4,
23 : AsyncTaskEvent = 5,
24 : };
25 :
26 : class V8_EXPORT Debug {
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 0 : 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 0 : virtual ~Message() {}
88 : };
89 :
90 : /**
91 : * An event details object passed to the debug event listener.
92 : */
93 39740 : 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 0 : 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 : */
215 : V8_DEPRECATED(
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_
|