OLD | NEW |
1 // Copyright 2008 the V8 project authors. All rights reserved. | 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 | 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_V8_DEBUG_H_ | 5 #ifndef V8_V8_DEBUG_H_ |
6 #define V8_V8_DEBUG_H_ | 6 #define V8_V8_DEBUG_H_ |
7 | 7 |
8 #include "v8.h" // NOLINT(build/include) | 8 #include "v8.h" // NOLINT(build/include) |
9 | 9 |
10 /** | 10 /** |
11 * Debugger support for the V8 JavaScript engine. | 11 * Debugger support for the V8 JavaScript engine. |
12 */ | 12 */ |
13 namespace v8 { | 13 namespace v8 { |
14 | 14 |
15 // Debug events which can occur in the V8 JavaScript engine. | 15 // Debug events which can occur in the V8 JavaScript engine. |
16 enum DebugEvent { | 16 enum DebugEvent { |
17 Break = 1, | 17 Break = 1, |
18 Exception = 2, | 18 Exception = 2, |
19 AfterCompile = 3, | 19 AfterCompile = 3, |
20 CompileError = 4, | 20 CompileError = 4, |
21 AsyncTaskEvent = 5, | 21 AsyncTaskEvent = 5, |
22 }; | 22 }; |
23 | 23 |
24 class V8_EXPORT Debug { | 24 class V8_EXPORT Debug { |
25 public: | 25 public: |
26 /** | 26 /** |
27 * A client object passed to the v8 debugger whose ownership will be taken by | |
28 * it. v8 is always responsible for deleting the object. | |
29 */ | |
30 class ClientData { | |
31 public: | |
32 virtual ~ClientData() {} | |
33 }; | |
34 | |
35 | |
36 /** | |
37 * A message object passed to the debug message handler. | |
38 */ | |
39 class Message { | |
40 public: | |
41 /** | |
42 * Check type of message. | |
43 */ | |
44 virtual bool IsEvent() const = 0; | |
45 virtual bool IsResponse() const = 0; | |
46 virtual DebugEvent GetEvent() const = 0; | |
47 | |
48 /** | |
49 * Indicate whether this is a response to a continue command which will | |
50 * start the VM running after this is processed. | |
51 */ | |
52 virtual bool WillStartRunning() const = 0; | |
53 | |
54 /** | |
55 * Access to execution state and event data. Don't store these cross | |
56 * callbacks as their content becomes invalid. These objects are from the | |
57 * debugger event that started the debug message loop. | |
58 */ | |
59 virtual Local<Object> GetExecutionState() const = 0; | |
60 virtual Local<Object> GetEventData() const = 0; | |
61 | |
62 /** | |
63 * Get the debugger protocol JSON. | |
64 */ | |
65 virtual Local<String> GetJSON() const = 0; | |
66 | |
67 /** | |
68 * Get the context active when the debug event happened. Note this is not | |
69 * the current active context as the JavaScript part of the debugger is | |
70 * running in its own context which is entered at this point. | |
71 */ | |
72 virtual Local<Context> GetEventContext() const = 0; | |
73 | |
74 /** | |
75 * Client data passed with the corresponding request if any. This is the | |
76 * client_data data value passed into Debug::SendCommand along with the | |
77 * request that led to the message or NULL if the message is an event. The | |
78 * debugger takes ownership of the data and will delete it even if there is | |
79 * no message handler. | |
80 */ | |
81 virtual ClientData* GetClientData() const = 0; | |
82 | |
83 virtual Isolate* GetIsolate() const = 0; | |
84 | |
85 virtual ~Message() {} | |
86 }; | |
87 | |
88 /** | |
89 * An event details object passed to the debug event listener. | 27 * An event details object passed to the debug event listener. |
90 */ | 28 */ |
91 class EventDetails { | 29 class EventDetails { |
92 public: | 30 public: |
93 /** | 31 /** |
94 * Event type. | 32 * Event type. |
95 */ | 33 */ |
96 virtual DebugEvent GetEvent() const = 0; | 34 virtual DebugEvent GetEvent() const = 0; |
97 | 35 |
98 /** | 36 /** |
99 * Access to execution state and event data of the debug event. Don't store | 37 * Access to execution state and event data of the debug event. Don't store |
100 * these cross callbacks as their content becomes invalid. | 38 * these cross callbacks as their content becomes invalid. |
101 */ | 39 */ |
102 virtual Local<Object> GetExecutionState() const = 0; | 40 virtual Local<Object> GetExecutionState() const = 0; |
103 virtual Local<Object> GetEventData() const = 0; | 41 virtual Local<Object> GetEventData() const = 0; |
104 | 42 |
105 /** | 43 /** |
106 * Get the context active when the debug event happened. Note this is not | 44 * Get the context active when the debug event happened. Note this is not |
107 * the current active context as the JavaScript part of the debugger is | 45 * the current active context as the JavaScript part of the debugger is |
108 * running in its own context which is entered at this point. | 46 * running in its own context which is entered at this point. |
109 */ | 47 */ |
110 virtual Local<Context> GetEventContext() const = 0; | 48 virtual Local<Context> GetEventContext() const = 0; |
111 | 49 |
112 /** | 50 /** |
113 * Client data passed with the corresponding callback when it was | 51 * Client data passed with the corresponding callback when it was |
114 * registered. | 52 * registered. |
115 */ | 53 */ |
116 virtual Local<Value> GetCallbackData() const = 0; | 54 virtual Local<Value> GetCallbackData() const = 0; |
117 | 55 |
118 /** | |
119 * Client data passed to DebugBreakForCommand function. The | |
120 * debugger takes ownership of the data and will delete it even if | |
121 * there is no message handler. | |
122 */ | |
123 virtual ClientData* GetClientData() const = 0; | |
124 | |
125 virtual Isolate* GetIsolate() const = 0; | 56 virtual Isolate* GetIsolate() const = 0; |
126 | 57 |
127 virtual ~EventDetails() {} | 58 virtual ~EventDetails() {} |
128 }; | 59 }; |
129 | 60 |
130 /** | 61 /** |
131 * Debug event callback function. | 62 * Debug event callback function. |
132 * | 63 * |
133 * \param event_details object providing information about the debug event | 64 * \param event_details object providing information about the debug event |
134 * | 65 * |
135 * A EventCallback2 does not take possession of the event data, | 66 * A EventCallback does not take possession of the event data, |
136 * and must not rely on the data persisting after the handler returns. | 67 * and must not rely on the data persisting after the handler returns. |
137 */ | 68 */ |
138 typedef void (*EventCallback)(const EventDetails& event_details); | 69 typedef void (*EventCallback)(const EventDetails& event_details); |
139 | 70 |
140 /** | |
141 * Debug message callback function. | |
142 * | |
143 * \param message the debug message handler message object | |
144 * | |
145 * A MessageHandler does not take possession of the message data, | |
146 * and must not rely on the data persisting after the handler returns. | |
147 */ | |
148 typedef void (*MessageHandler)(const Message& message); | |
149 | |
150 /** | |
151 * Callback function for the host to ensure debug messages are processed. | |
152 */ | |
153 typedef void (*DebugMessageDispatchHandler)(); | |
154 | |
155 static bool SetDebugEventListener(Isolate* isolate, EventCallback that, | 71 static bool SetDebugEventListener(Isolate* isolate, EventCallback that, |
156 Local<Value> data = Local<Value>()); | 72 Local<Value> data = Local<Value>()); |
157 | 73 |
158 // Schedule a debugger break to happen when JavaScript code is run | 74 // Schedule a debugger break to happen when JavaScript code is run |
159 // in the given isolate. | 75 // in the given isolate. |
160 static void DebugBreak(Isolate* isolate); | 76 static void DebugBreak(Isolate* isolate); |
161 | 77 |
162 // Remove scheduled debugger break in given isolate if it has not | 78 // Remove scheduled debugger break in given isolate if it has not |
163 // happened yet. | 79 // happened yet. |
164 static void CancelDebugBreak(Isolate* isolate); | 80 static void CancelDebugBreak(Isolate* isolate); |
165 | 81 |
166 // Check if a debugger break is scheduled in the given isolate. | 82 // Check if a debugger break is scheduled in the given isolate. |
167 V8_DEPRECATED("No longer supported", | 83 V8_DEPRECATED("No longer supported", |
168 static bool CheckDebugBreak(Isolate* isolate)); | 84 static bool CheckDebugBreak(Isolate* isolate)); |
169 | 85 |
170 // Message based interface. The message protocol is JSON. | |
171 V8_DEPRECATED("No longer supported", | |
172 static void SetMessageHandler(Isolate* isolate, | |
173 MessageHandler handler)); | |
174 | |
175 V8_DEPRECATED("No longer supported", | |
176 static void SendCommand(Isolate* isolate, | |
177 const uint16_t* command, int length, | |
178 ClientData* client_data = NULL)); | |
179 | |
180 /** | 86 /** |
181 * Run a JavaScript function in the debugger. | 87 * Run a JavaScript function in the debugger. |
182 * \param fun the function to call | 88 * \param fun the function to call |
183 * \param data passed as second argument to the function | 89 * \param data passed as second argument to the function |
184 * With this call the debugger is entered and the function specified is called | 90 * With this call the debugger is entered and the function specified is called |
185 * with the execution state as the first argument. This makes it possible to | 91 * with the execution state as the first argument. This makes it possible to |
186 * get access to information otherwise not available during normal JavaScript | 92 * get access to information otherwise not available during normal JavaScript |
187 * execution e.g. details on stack frames. Receiver of the function call will | 93 * execution e.g. details on stack frames. Receiver of the function call will |
188 * be the debugger context global object, however this is a subject to change. | 94 * be the debugger context global object, however this is a subject to change. |
189 * The following example shows a JavaScript function which when passed to | 95 * The following example shows a JavaScript function which when passed to |
(...skipping 11 matching lines...) Expand all Loading... |
201 Local<Value> data = Local<Value>()); | 107 Local<Value> data = Local<Value>()); |
202 | 108 |
203 /** | 109 /** |
204 * Returns a mirror object for the given object. | 110 * Returns a mirror object for the given object. |
205 */ | 111 */ |
206 V8_DEPRECATED("No longer supported", | 112 V8_DEPRECATED("No longer supported", |
207 static MaybeLocal<Value> GetMirror(Local<Context> context, | 113 static MaybeLocal<Value> GetMirror(Local<Context> context, |
208 v8::Local<v8::Value> obj)); | 114 v8::Local<v8::Value> obj)); |
209 | 115 |
210 /** | 116 /** |
211 * Makes V8 process all pending debug messages. | |
212 * | |
213 * From V8 point of view all debug messages come asynchronously (e.g. from | |
214 * remote debugger) but they all must be handled synchronously: V8 cannot | |
215 * do 2 things at one time so normal script execution must be interrupted | |
216 * for a while. | |
217 * | |
218 * Generally when message arrives V8 may be in one of 3 states: | |
219 * 1. V8 is running script; V8 will automatically interrupt and process all | |
220 * pending messages; | |
221 * 2. V8 is suspended on debug breakpoint; in this state V8 is dedicated | |
222 * to reading and processing debug messages; | |
223 * 3. V8 is not running at all or has called some long-working C++ function; | |
224 * by default it means that processing of all debug messages will be deferred | |
225 * until V8 gets control again; however, embedding application may improve | |
226 * this by manually calling this method. | |
227 * | |
228 * Technically this method in many senses is equivalent to executing empty | |
229 * script: | |
230 * 1. It does nothing except for processing all pending debug messages. | |
231 * 2. It should be invoked with the same precautions and from the same context | |
232 * as V8 script would be invoked from, because: | |
233 * a. with "evaluate" command it can do whatever normal script can do, | |
234 * including all native calls; | |
235 * b. no other thread should call V8 while this method is running | |
236 * (v8::Locker may be used here). | |
237 * | |
238 * "Evaluate" debug command behavior currently is not specified in scope | |
239 * of this method. | |
240 */ | |
241 V8_DEPRECATED("No longer supported", | |
242 static void ProcessDebugMessages(Isolate* isolate)); | |
243 | |
244 /** | |
245 * Debugger is running in its own context which is entered while debugger | 117 * Debugger is running in its own context which is entered while debugger |
246 * messages are being dispatched. This is an explicit getter for this | 118 * messages are being dispatched. This is an explicit getter for this |
247 * debugger context. Note that the content of the debugger context is subject | 119 * debugger context. Note that the content of the debugger context is subject |
248 * to change. The Context exists only when the debugger is active, i.e. at | 120 * to change. The Context exists only when the debugger is active, i.e. at |
249 * least one DebugEventListener or MessageHandler is set. | 121 * least one DebugEventListener or MessageHandler is set. |
250 */ | 122 */ |
251 V8_DEPRECATED("Use v8-inspector", | 123 V8_DEPRECATED("Use v8-inspector", |
252 static Local<Context> GetDebugContext(Isolate* isolate)); | 124 static Local<Context> GetDebugContext(Isolate* isolate)); |
253 | 125 |
254 /** | 126 /** |
(...skipping 29 matching lines...) Expand all Loading... |
284 }; | 156 }; |
285 | 157 |
286 | 158 |
287 } // namespace v8 | 159 } // namespace v8 |
288 | 160 |
289 | 161 |
290 #undef EXPORT | 162 #undef EXPORT |
291 | 163 |
292 | 164 |
293 #endif // V8_V8_DEBUG_H_ | 165 #endif // V8_V8_DEBUG_H_ |
OLD | NEW |