OLD | NEW |
1 // Copyright 2016 the V8 project authors. All rights reserved. | 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 | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 #ifndef V8_DEBUG_DEBUG_INTERFACE_H_ | 5 #ifndef V8_DEBUG_DEBUG_INTERFACE_H_ |
6 #define V8_DEBUG_DEBUG_INTERFACE_H_ | 6 #define V8_DEBUG_DEBUG_INTERFACE_H_ |
7 | 7 |
8 #include "include/v8-debug.h" | 8 #include "include/v8-debug.h" |
9 #include "include/v8-util.h" | 9 #include "include/v8-util.h" |
10 #include "include/v8.h" | 10 #include "include/v8.h" |
11 | 11 |
12 #include "src/debug/interface-types.h" | 12 #include "src/debug/interface-types.h" |
13 | 13 |
14 namespace v8 { | 14 namespace v8 { |
| 15 namespace debug { |
15 | 16 |
16 class DebugInterface { | 17 /** |
| 18 * An event details object passed to the debug event listener. |
| 19 */ |
| 20 class EventDetails : public v8::Debug::EventDetails { |
17 public: | 21 public: |
18 /** | 22 /** |
19 * An event details object passed to the debug event listener. | 23 * Event type. |
20 */ | 24 */ |
21 class EventDetails : public v8::Debug::EventDetails { | 25 virtual v8::DebugEvent GetEvent() const = 0; |
22 public: | |
23 /** | |
24 * Event type. | |
25 */ | |
26 virtual v8::DebugEvent GetEvent() const = 0; | |
27 | |
28 /** | |
29 * Access to execution state and event data of the debug event. Don't store | |
30 * these cross callbacks as their content becomes invalid. | |
31 */ | |
32 virtual Local<Object> GetExecutionState() const = 0; | |
33 virtual Local<Object> GetEventData() const = 0; | |
34 | |
35 /** | |
36 * Get the context active when the debug event happened. Note this is not | |
37 * the current active context as the JavaScript part of the debugger is | |
38 * running in its own context which is entered at this point. | |
39 */ | |
40 virtual Local<Context> GetEventContext() const = 0; | |
41 | |
42 /** | |
43 * Client data passed with the corresponding callback when it was | |
44 * registered. | |
45 */ | |
46 virtual Local<Value> GetCallbackData() const = 0; | |
47 | |
48 virtual ~EventDetails() {} | |
49 }; | |
50 | 26 |
51 /** | 27 /** |
52 * Debug event callback function. | 28 * Access to execution state and event data of the debug event. Don't store |
53 * | 29 * these cross callbacks as their content becomes invalid. |
54 * \param event_details object providing information about the debug event | |
55 * | |
56 * A EventCallback does not take possession of the event data, | |
57 * and must not rely on the data persisting after the handler returns. | |
58 */ | 30 */ |
59 typedef void (*EventCallback)(const EventDetails& event_details); | 31 virtual Local<Object> GetExecutionState() const = 0; |
60 | 32 virtual Local<Object> GetEventData() const = 0; |
61 static bool SetDebugEventListener(Isolate* isolate, EventCallback that, | |
62 Local<Value> data = Local<Value>()); | |
63 | 33 |
64 /** | 34 /** |
65 * Debugger is running in its own context which is entered while debugger | 35 * Get the context active when the debug event happened. Note this is not |
66 * messages are being dispatched. This is an explicit getter for this | 36 * the current active context as the JavaScript part of the debugger is |
67 * debugger context. Note that the content of the debugger context is subject | 37 * running in its own context which is entered at this point. |
68 * to change. The Context exists only when the debugger is active, i.e. at | |
69 * least one DebugEventListener or MessageHandler is set. | |
70 */ | 38 */ |
71 static Local<Context> GetDebugContext(Isolate* isolate); | 39 virtual Local<Context> GetEventContext() const = 0; |
72 | 40 |
73 /** | 41 /** |
74 * Run a JavaScript function in the debugger. | 42 * Client data passed with the corresponding callback when it was |
75 * \param fun the function to call | 43 * registered. |
76 * \param data passed as second argument to the function | |
77 * With this call the debugger is entered and the function specified is called | |
78 * with the execution state as the first argument. This makes it possible to | |
79 * get access to information otherwise not available during normal JavaScript | |
80 * execution e.g. details on stack frames. Receiver of the function call will | |
81 * be the debugger context global object, however this is a subject to change. | |
82 * The following example shows a JavaScript function which when passed to | |
83 * v8::Debug::Call will return the current line of JavaScript execution. | |
84 * | |
85 * \code | |
86 * function frame_source_line(exec_state) { | |
87 * return exec_state.frame(0).sourceLine(); | |
88 * } | |
89 * \endcode | |
90 */ | 44 */ |
91 // TODO(dcarney): data arg should be a MaybeLocal | 45 virtual Local<Value> GetCallbackData() const = 0; |
92 static MaybeLocal<Value> Call(Local<Context> context, | 46 |
93 v8::Local<v8::Function> fun, | 47 virtual ~EventDetails() {} |
94 Local<Value> data = Local<Value>()); | 48 }; |
| 49 |
| 50 /** |
| 51 * Debug event callback function. |
| 52 * |
| 53 * \param event_details object providing information about the debug event |
| 54 * |
| 55 * A EventCallback does not take possession of the event data, |
| 56 * and must not rely on the data persisting after the handler returns. |
| 57 */ |
| 58 typedef void (*EventCallback)(const EventDetails& event_details); |
| 59 |
| 60 bool SetDebugEventListener(Isolate* isolate, EventCallback that, |
| 61 Local<Value> data = Local<Value>()); |
| 62 |
| 63 /** |
| 64 * Debugger is running in its own context which is entered while debugger |
| 65 * messages are being dispatched. This is an explicit getter for this |
| 66 * debugger context. Note that the content of the debugger context is subject |
| 67 * to change. The Context exists only when the debugger is active, i.e. at |
| 68 * least one DebugEventListener or MessageHandler is set. |
| 69 */ |
| 70 Local<Context> GetDebugContext(Isolate* isolate); |
| 71 |
| 72 /** |
| 73 * Run a JavaScript function in the debugger. |
| 74 * \param fun the function to call |
| 75 * \param data passed as second argument to the function |
| 76 * With this call the debugger is entered and the function specified is called |
| 77 * with the execution state as the first argument. This makes it possible to |
| 78 * get access to information otherwise not available during normal JavaScript |
| 79 * execution e.g. details on stack frames. Receiver of the function call will |
| 80 * be the debugger context global object, however this is a subject to change. |
| 81 * The following example shows a JavaScript function which when passed to |
| 82 * v8::Debug::Call will return the current line of JavaScript execution. |
| 83 * |
| 84 * \code |
| 85 * function frame_source_line(exec_state) { |
| 86 * return exec_state.frame(0).sourceLine(); |
| 87 * } |
| 88 * \endcode |
| 89 */ |
| 90 // TODO(dcarney): data arg should be a MaybeLocal |
| 91 MaybeLocal<Value> Call(Local<Context> context, v8::Local<v8::Function> fun, |
| 92 Local<Value> data = Local<Value>()); |
| 93 |
| 94 /** |
| 95 * Enable/disable LiveEdit functionality for the given Isolate |
| 96 * (default Isolate if not provided). V8 will abort if LiveEdit is |
| 97 * unexpectedly used. LiveEdit is enabled by default. |
| 98 */ |
| 99 void SetLiveEditEnabled(Isolate* isolate, bool enable); |
| 100 |
| 101 // Schedule a debugger break to happen when JavaScript code is run |
| 102 // in the given isolate. |
| 103 void DebugBreak(Isolate* isolate); |
| 104 |
| 105 // Remove scheduled debugger break in given isolate if it has not |
| 106 // happened yet. |
| 107 void CancelDebugBreak(Isolate* isolate); |
| 108 |
| 109 /** |
| 110 * Returns array of internal properties specific to the value type. Result has |
| 111 * the following format: [<name>, <value>,...,<name>, <value>]. Result array |
| 112 * will be allocated in the current context. |
| 113 */ |
| 114 MaybeLocal<Array> GetInternalProperties(Isolate* isolate, Local<Value> value); |
| 115 |
| 116 enum ExceptionBreakState { |
| 117 NoBreakOnException = 0, |
| 118 BreakOnUncaughtException = 1, |
| 119 BreakOnAnyException = 2 |
| 120 }; |
| 121 |
| 122 /** |
| 123 * Defines if VM will pause on exceptions or not. |
| 124 * If BreakOnAnyExceptions is set then VM will pause on caught and uncaught |
| 125 * exception, if BreakOnUncaughtException is set then VM will pause only on |
| 126 * uncaught exception, otherwise VM won't stop on any exception. |
| 127 */ |
| 128 void ChangeBreakOnException(Isolate* isolate, ExceptionBreakState state); |
| 129 |
| 130 enum StepAction { |
| 131 StepOut = 0, // Step out of the current function. |
| 132 StepNext = 1, // Step to the next statement in the current function. |
| 133 StepIn = 2, // Step into new functions invoked or the next statement |
| 134 // in the current function. |
| 135 StepFrame = 3 // Step into a new frame or return to previous frame. |
| 136 }; |
| 137 |
| 138 void PrepareStep(Isolate* isolate, StepAction action); |
| 139 void ClearStepping(Isolate* isolate); |
| 140 |
| 141 /** |
| 142 * Native wrapper around v8::internal::Script object. |
| 143 */ |
| 144 class Script { |
| 145 public: |
| 146 v8::Isolate* GetIsolate() const; |
| 147 |
| 148 ScriptOriginOptions OriginOptions() const; |
| 149 bool WasCompiled() const; |
| 150 int Id() const; |
| 151 int LineOffset() const; |
| 152 int ColumnOffset() const; |
| 153 std::vector<int> LineEnds() const; |
| 154 MaybeLocal<String> Name() const; |
| 155 MaybeLocal<String> SourceURL() const; |
| 156 MaybeLocal<String> SourceMappingURL() const; |
| 157 MaybeLocal<String> ContextData() const; |
| 158 MaybeLocal<String> Source() const; |
| 159 bool IsWasm() const; |
| 160 bool GetPossibleBreakpoints(const debug::Location& start, |
| 161 const debug::Location& end, |
| 162 std::vector<debug::Location>* locations) const; |
95 | 163 |
96 /** | 164 /** |
97 * Enable/disable LiveEdit functionality for the given Isolate | 165 * script parameter is a wrapper v8::internal::JSObject for |
98 * (default Isolate if not provided). V8 will abort if LiveEdit is | 166 * v8::internal::Script. |
99 * unexpectedly used. LiveEdit is enabled by default. | 167 * This function gets v8::internal::Script from v8::internal::JSObject and |
| 168 * wraps it with DebugInterface::Script. |
| 169 * Returns empty local if not called with a valid wrapper of |
| 170 * v8::internal::Script. |
100 */ | 171 */ |
101 static void SetLiveEditEnabled(Isolate* isolate, bool enable); | 172 static MaybeLocal<Script> Wrap(Isolate* isolate, |
| 173 v8::Local<v8::Object> script); |
102 | 174 |
103 // Schedule a debugger break to happen when JavaScript code is run | 175 private: |
104 // in the given isolate. | 176 int GetSourcePosition(const debug::Location& location) const; |
105 static void DebugBreak(Isolate* isolate); | |
106 | |
107 // Remove scheduled debugger break in given isolate if it has not | |
108 // happened yet. | |
109 static void CancelDebugBreak(Isolate* isolate); | |
110 | |
111 /** | |
112 * Returns array of internal properties specific to the value type. Result has | |
113 * the following format: [<name>, <value>,...,<name>, <value>]. Result array | |
114 * will be allocated in the current context. | |
115 */ | |
116 static MaybeLocal<Array> GetInternalProperties(Isolate* isolate, | |
117 Local<Value> value); | |
118 | |
119 enum ExceptionBreakState { | |
120 NoBreakOnException = 0, | |
121 BreakOnUncaughtException = 1, | |
122 BreakOnAnyException = 2 | |
123 }; | |
124 | |
125 /** | |
126 * Defines if VM will pause on exceptions or not. | |
127 * If BreakOnAnyExceptions is set then VM will pause on caught and uncaught | |
128 * exception, if BreakOnUncaughtException is set then VM will pause only on | |
129 * uncaught exception, otherwise VM won't stop on any exception. | |
130 */ | |
131 static void ChangeBreakOnException(Isolate* isolate, | |
132 ExceptionBreakState state); | |
133 | |
134 enum StepAction { | |
135 StepOut = 0, // Step out of the current function. | |
136 StepNext = 1, // Step to the next statement in the current function. | |
137 StepIn = 2, // Step into new functions invoked or the next statement | |
138 // in the current function. | |
139 StepFrame = 3 // Step into a new frame or return to previous frame. | |
140 }; | |
141 | |
142 static void PrepareStep(Isolate* isolate, StepAction action); | |
143 static void ClearStepping(Isolate* isolate); | |
144 | |
145 /** | |
146 * Native wrapper around v8::internal::Script object. | |
147 */ | |
148 class Script { | |
149 public: | |
150 v8::Isolate* GetIsolate() const; | |
151 | |
152 ScriptOriginOptions OriginOptions() const; | |
153 bool WasCompiled() const; | |
154 int Id() const; | |
155 int LineOffset() const; | |
156 int ColumnOffset() const; | |
157 std::vector<int> LineEnds() const; | |
158 MaybeLocal<String> Name() const; | |
159 MaybeLocal<String> SourceURL() const; | |
160 MaybeLocal<String> SourceMappingURL() const; | |
161 MaybeLocal<String> ContextData() const; | |
162 MaybeLocal<String> Source() const; | |
163 bool IsWasm() const; | |
164 bool GetPossibleBreakpoints(const debug::Location& start, | |
165 const debug::Location& end, | |
166 std::vector<debug::Location>* locations) const; | |
167 | |
168 /** | |
169 * script parameter is a wrapper v8::internal::JSObject for | |
170 * v8::internal::Script. | |
171 * This function gets v8::internal::Script from v8::internal::JSObject and | |
172 * wraps it with DebugInterface::Script. | |
173 * Returns empty local if not called with a valid wrapper of | |
174 * v8::internal::Script. | |
175 */ | |
176 static MaybeLocal<Script> Wrap(Isolate* isolate, | |
177 v8::Local<v8::Object> script); | |
178 | |
179 private: | |
180 int GetSourcePosition(const debug::Location& location) const; | |
181 }; | |
182 | |
183 static void GetLoadedScripts(Isolate* isolate, | |
184 PersistentValueVector<Script>& scripts); | |
185 | |
186 /** | |
187 * Compute the disassembly of a wasm function. | |
188 */ | |
189 static debug::WasmDisassembly DisassembleWasmFunction( | |
190 Isolate* isolate, v8::Local<v8::Object> script, int function_index); | |
191 | |
192 static MaybeLocal<UnboundScript> CompileInspectorScript(Isolate* isolate, | |
193 Local<String> source); | |
194 }; | 177 }; |
195 | 178 |
| 179 void GetLoadedScripts(Isolate* isolate, PersistentValueVector<Script>& scripts); |
| 180 |
| 181 /** |
| 182 * Compute the disassembly of a wasm function. |
| 183 */ |
| 184 debug::WasmDisassembly DisassembleWasmFunction(Isolate* isolate, |
| 185 v8::Local<v8::Object> script, |
| 186 int function_index); |
| 187 |
| 188 MaybeLocal<UnboundScript> CompileInspectorScript(Isolate* isolate, |
| 189 Local<String> source); |
| 190 |
| 191 } // namespace debug |
196 } // namespace v8 | 192 } // namespace v8 |
197 | 193 |
198 #endif // V8_DEBUG_DEBUG_INTERFACE_H_ | 194 #endif // V8_DEBUG_DEBUG_INTERFACE_H_ |
OLD | NEW |