Line data Source code
1 : // Copyright 2016 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_DEBUG_DEBUG_INTERFACE_H_
6 : #define V8_DEBUG_DEBUG_INTERFACE_H_
7 :
8 : #include <functional>
9 :
10 : #include "include/v8-debug.h"
11 : #include "include/v8-util.h"
12 : #include "include/v8.h"
13 :
14 : #include "src/debug/interface-types.h"
15 : #include "src/globals.h"
16 :
17 : namespace v8 {
18 :
19 : namespace internal {
20 : struct CoverageFunction;
21 : struct CoverageScript;
22 : class Coverage;
23 : class Script;
24 : }
25 :
26 : namespace debug {
27 :
28 : void SetContextId(Local<Context> context, int id);
29 : int GetContextId(Local<Context> context);
30 :
31 : /**
32 : * Debugger is running in its own context which is entered while debugger
33 : * messages are being dispatched. This is an explicit getter for this
34 : * debugger context. Note that the content of the debugger context is subject
35 : * to change. The Context exists only when the debugger is active, i.e. at
36 : * least one DebugEventListener or MessageHandler is set.
37 : */
38 : Local<Context> GetDebugContext(Isolate* isolate);
39 :
40 : /**
41 : * Run a JavaScript function in the debugger.
42 : * \param fun the function to call
43 : * \param data passed as second argument to the function
44 : * With this call the debugger is entered and the function specified is called
45 : * with the execution state as the first argument. This makes it possible to
46 : * get access to information otherwise not available during normal JavaScript
47 : * execution e.g. details on stack frames. Receiver of the function call will
48 : * be the debugger context global object, however this is a subject to change.
49 : * The following example shows a JavaScript function which when passed to
50 : * v8::Debug::Call will return the current line of JavaScript execution.
51 : *
52 : * \code
53 : * function frame_source_line(exec_state) {
54 : * return exec_state.frame(0).sourceLine();
55 : * }
56 : * \endcode
57 : */
58 : // TODO(dcarney): data arg should be a MaybeLocal
59 : MaybeLocal<Value> Call(Local<Context> context, v8::Local<v8::Function> fun,
60 : Local<Value> data = Local<Value>());
61 :
62 : /**
63 : * Enable/disable LiveEdit functionality for the given Isolate
64 : * (default Isolate if not provided). V8 will abort if LiveEdit is
65 : * unexpectedly used. LiveEdit is enabled by default.
66 : */
67 : V8_EXPORT_PRIVATE void SetLiveEditEnabled(Isolate* isolate, bool enable);
68 :
69 : // Schedule a debugger break to happen when JavaScript code is run
70 : // in the given isolate.
71 : void DebugBreak(Isolate* isolate);
72 :
73 : // Remove scheduled debugger break in given isolate if it has not
74 : // happened yet.
75 : void CancelDebugBreak(Isolate* isolate);
76 :
77 : /**
78 : * Returns array of internal properties specific to the value type. Result has
79 : * the following format: [<name>, <value>,...,<name>, <value>]. Result array
80 : * will be allocated in the current context.
81 : */
82 : MaybeLocal<Array> GetInternalProperties(Isolate* isolate, Local<Value> value);
83 :
84 : enum ExceptionBreakState {
85 : NoBreakOnException = 0,
86 : BreakOnUncaughtException = 1,
87 : BreakOnAnyException = 2
88 : };
89 :
90 : /**
91 : * Defines if VM will pause on exceptions or not.
92 : * If BreakOnAnyExceptions is set then VM will pause on caught and uncaught
93 : * exception, if BreakOnUncaughtException is set then VM will pause only on
94 : * uncaught exception, otherwise VM won't stop on any exception.
95 : */
96 : void ChangeBreakOnException(Isolate* isolate, ExceptionBreakState state);
97 :
98 : void SetBreakPointsActive(Isolate* isolate, bool is_active);
99 :
100 : enum StepAction {
101 : StepOut = 0, // Step out of the current function.
102 : StepNext = 1, // Step to the next statement in the current function.
103 : StepIn = 2 // Step into new functions invoked or the next statement
104 : // in the current function.
105 : };
106 :
107 : void PrepareStep(Isolate* isolate, StepAction action);
108 : void ClearStepping(Isolate* isolate);
109 : void BreakRightNow(Isolate* isolate);
110 :
111 : bool AllFramesOnStackAreBlackboxed(Isolate* isolate);
112 :
113 : /**
114 : * Out-of-memory callback function.
115 : * The function is invoked when the heap size is close to the hard limit.
116 : *
117 : * \param data the parameter provided during callback installation.
118 : */
119 : typedef void (*OutOfMemoryCallback)(void* data);
120 : void SetOutOfMemoryCallback(Isolate* isolate, OutOfMemoryCallback callback,
121 : void* data);
122 :
123 : /**
124 : * Native wrapper around v8::internal::Script object.
125 : */
126 : class V8_EXPORT_PRIVATE Script {
127 : public:
128 : v8::Isolate* GetIsolate() const;
129 :
130 : ScriptOriginOptions OriginOptions() const;
131 : bool WasCompiled() const;
132 : bool IsEmbedded() const;
133 : int Id() const;
134 : int LineOffset() const;
135 : int ColumnOffset() const;
136 : std::vector<int> LineEnds() const;
137 : MaybeLocal<String> Name() const;
138 : MaybeLocal<String> SourceURL() const;
139 : MaybeLocal<String> SourceMappingURL() const;
140 : Maybe<int> ContextId() const;
141 : MaybeLocal<String> Source() const;
142 : bool IsWasm() const;
143 : bool IsModule() const;
144 : bool GetPossibleBreakpoints(
145 : const debug::Location& start, const debug::Location& end,
146 : bool restrict_to_function,
147 : std::vector<debug::BreakLocation>* locations) const;
148 : int GetSourceOffset(const debug::Location& location) const;
149 : v8::debug::Location GetSourceLocation(int offset) const;
150 : };
151 :
152 : // Specialization for wasm Scripts.
153 : class WasmScript : public Script {
154 : public:
155 : static WasmScript* Cast(Script* script);
156 :
157 : int NumFunctions() const;
158 : int NumImportedFunctions() const;
159 :
160 : std::pair<int, int> GetFunctionRange(int function_index) const;
161 :
162 : debug::WasmDisassembly DisassembleFunction(int function_index) const;
163 : };
164 :
165 : void GetLoadedScripts(Isolate* isolate, PersistentValueVector<Script>& scripts);
166 :
167 : MaybeLocal<UnboundScript> CompileInspectorScript(Isolate* isolate,
168 : Local<String> source);
169 :
170 5296 : class DebugDelegate {
171 : public:
172 5296 : virtual ~DebugDelegate() {}
173 0 : virtual void PromiseEventOccurred(debug::PromiseDebugActionType type, int id,
174 0 : int parent_id, bool created_by_user) {}
175 0 : virtual void ScriptCompiled(v8::Local<Script> script,
176 0 : bool has_compile_error) {}
177 0 : virtual void BreakProgramRequested(v8::Local<v8::Context> paused_context,
178 : v8::Local<v8::Object> exec_state,
179 0 : v8::Local<v8::Value> break_points_hit) {}
180 0 : virtual void ExceptionThrown(v8::Local<v8::Context> paused_context,
181 : v8::Local<v8::Object> exec_state,
182 : v8::Local<v8::Value> exception,
183 : v8::Local<v8::Value> promise, bool is_uncaught) {
184 0 : }
185 0 : virtual bool IsFunctionBlackboxed(v8::Local<debug::Script> script,
186 : const debug::Location& start,
187 : const debug::Location& end) {
188 0 : return false;
189 : }
190 : };
191 :
192 : void SetDebugDelegate(Isolate* isolate, DebugDelegate* listener);
193 :
194 : void ResetBlackboxedStateCache(Isolate* isolate,
195 : v8::Local<debug::Script> script);
196 :
197 : int EstimatedValueSize(Isolate* isolate, v8::Local<v8::Value> value);
198 :
199 : v8::MaybeLocal<v8::Array> EntriesPreview(Isolate* isolate,
200 : v8::Local<v8::Value> value,
201 : bool* is_key_value);
202 :
203 : enum Builtin {
204 : kObjectKeys,
205 : kObjectGetPrototypeOf,
206 : kObjectGetOwnPropertyDescriptor,
207 : kObjectGetOwnPropertyNames,
208 : kObjectGetOwnPropertySymbols,
209 : };
210 :
211 : Local<Function> GetBuiltin(Isolate* isolate, Builtin builtin);
212 :
213 : V8_EXPORT_PRIVATE void SetConsoleDelegate(Isolate* isolate,
214 : ConsoleDelegate* delegate);
215 :
216 : int GetStackFrameId(v8::Local<v8::StackFrame> frame);
217 :
218 : /**
219 : * Native wrapper around v8::internal::JSGeneratorObject object.
220 : */
221 : class GeneratorObject {
222 : public:
223 : v8::MaybeLocal<debug::Script> Script();
224 : v8::Local<v8::Function> Function();
225 : debug::Location SuspendedLocation();
226 : bool IsSuspended();
227 :
228 : static v8::Local<debug::GeneratorObject> Cast(v8::Local<v8::Value> value);
229 : };
230 :
231 : /*
232 : * Provide API layer between inspector and code coverage.
233 : */
234 : class V8_EXPORT_PRIVATE Coverage {
235 : public:
236 : enum Mode {
237 : // Make use of existing information in feedback vectors on the heap.
238 : // Only return a yes/no result. Optimization and GC are not affected.
239 : // Collecting best effort coverage does not reset counters.
240 : kBestEffort,
241 : // Disable optimization and prevent feedback vectors from being garbage
242 : // collected in order to preserve precise invocation counts. Collecting
243 : // precise count coverage resets counters to get incremental updates.
244 : kPreciseCount,
245 : // We are only interested in a yes/no result for the function. Optimization
246 : // and GC can be allowed once a function has been invoked. Collecting
247 : // precise binary coverage resets counters for incremental updates.
248 : kPreciseBinary
249 : };
250 :
251 : class ScriptData; // Forward declaration.
252 :
253 : class V8_EXPORT_PRIVATE FunctionData {
254 : public:
255 : int StartOffset() const;
256 : int EndOffset() const;
257 : uint32_t Count() const;
258 : MaybeLocal<String> Name() const;
259 :
260 : private:
261 : explicit FunctionData(i::CoverageFunction* function)
262 : : function_(function) {}
263 : i::CoverageFunction* function_;
264 :
265 : friend class v8::debug::Coverage::ScriptData;
266 : };
267 :
268 : class V8_EXPORT_PRIVATE ScriptData {
269 : public:
270 : Local<debug::Script> GetScript() const;
271 : size_t FunctionCount() const;
272 : FunctionData GetFunctionData(size_t i) const;
273 :
274 : private:
275 : explicit ScriptData(i::CoverageScript* script) : script_(script) {}
276 : i::CoverageScript* script_;
277 :
278 : friend class v8::debug::Coverage;
279 : };
280 :
281 : static Coverage CollectPrecise(Isolate* isolate);
282 : static Coverage CollectBestEffort(Isolate* isolate);
283 :
284 : static void SelectMode(Isolate* isolate, Mode mode);
285 :
286 : size_t ScriptCount() const;
287 : ScriptData GetScriptData(size_t i) const;
288 : bool IsEmpty() const { return coverage_ == nullptr; }
289 :
290 : ~Coverage();
291 :
292 : private:
293 102 : explicit Coverage(i::Coverage* coverage) : coverage_(coverage) {}
294 : i::Coverage* coverage_;
295 : };
296 : } // namespace debug
297 : } // namespace v8
298 :
299 : #endif // V8_DEBUG_DEBUG_INTERFACE_H_
|
