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 * An event details object passed to the debug event listener. | 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. |
28 */ | 29 */ |
29 class EventDetails { | 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 { |
30 public: | 40 public: |
31 /** | 41 /** |
32 * Event type. | 42 * Check type of message. |
33 */ | 43 */ |
| 44 virtual bool IsEvent() const = 0; |
| 45 virtual bool IsResponse() const = 0; |
34 virtual DebugEvent GetEvent() const = 0; | 46 virtual DebugEvent GetEvent() const = 0; |
35 | 47 |
36 /** | 48 /** |
37 * Access to execution state and event data of the debug event. Don't store | 49 * Indicate whether this is a response to a continue command which will |
38 * these cross callbacks as their content becomes invalid. | 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. |
39 */ | 58 */ |
40 virtual Local<Object> GetExecutionState() const = 0; | 59 virtual Local<Object> GetExecutionState() const = 0; |
41 virtual Local<Object> GetEventData() const = 0; | 60 virtual Local<Object> GetEventData() const = 0; |
42 | 61 |
43 /** | 62 /** |
| 63 * Get the debugger protocol JSON. |
| 64 */ |
| 65 virtual Local<String> GetJSON() const = 0; |
| 66 |
| 67 /** |
44 * Get the context active when the debug event happened. Note this is not | 68 * Get the context active when the debug event happened. Note this is not |
45 * the current active context as the JavaScript part of the debugger is | 69 * the current active context as the JavaScript part of the debugger is |
46 * running in its own context which is entered at this point. | 70 * running in its own context which is entered at this point. |
47 */ | 71 */ |
48 virtual Local<Context> GetEventContext() const = 0; | 72 virtual Local<Context> GetEventContext() const = 0; |
49 | 73 |
50 /** | 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. |
| 90 */ |
| 91 class EventDetails { |
| 92 public: |
| 93 /** |
| 94 * Event type. |
| 95 */ |
| 96 virtual DebugEvent GetEvent() const = 0; |
| 97 |
| 98 /** |
| 99 * Access to execution state and event data of the debug event. Don't store |
| 100 * these cross callbacks as their content becomes invalid. |
| 101 */ |
| 102 virtual Local<Object> GetExecutionState() const = 0; |
| 103 virtual Local<Object> GetEventData() const = 0; |
| 104 |
| 105 /** |
| 106 * 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 |
| 108 * running in its own context which is entered at this point. |
| 109 */ |
| 110 virtual Local<Context> GetEventContext() const = 0; |
| 111 |
| 112 /** |
51 * Client data passed with the corresponding callback when it was | 113 * Client data passed with the corresponding callback when it was |
52 * registered. | 114 * registered. |
53 */ | 115 */ |
54 virtual Local<Value> GetCallbackData() const = 0; | 116 virtual Local<Value> GetCallbackData() const = 0; |
55 | 117 |
| 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 |
56 virtual Isolate* GetIsolate() const = 0; | 125 virtual Isolate* GetIsolate() const = 0; |
57 | 126 |
58 virtual ~EventDetails() {} | 127 virtual ~EventDetails() {} |
59 }; | 128 }; |
60 | 129 |
61 /** | 130 /** |
62 * Debug event callback function. | 131 * Debug event callback function. |
63 * | 132 * |
64 * \param event_details object providing information about the debug event | 133 * \param event_details object providing information about the debug event |
65 * | 134 * |
66 * A EventCallback does not take possession of the event data, | 135 * A EventCallback2 does not take possession of the event data, |
67 * and must not rely on the data persisting after the handler returns. | 136 * and must not rely on the data persisting after the handler returns. |
68 */ | 137 */ |
69 typedef void (*EventCallback)(const EventDetails& event_details); | 138 typedef void (*EventCallback)(const EventDetails& event_details); |
70 | 139 |
| 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 |
71 static bool SetDebugEventListener(Isolate* isolate, EventCallback that, | 155 static bool SetDebugEventListener(Isolate* isolate, EventCallback that, |
72 Local<Value> data = Local<Value>()); | 156 Local<Value> data = Local<Value>()); |
73 | 157 |
74 // Schedule a debugger break to happen when JavaScript code is run | 158 // Schedule a debugger break to happen when JavaScript code is run |
75 // in the given isolate. | 159 // in the given isolate. |
76 static void DebugBreak(Isolate* isolate); | 160 static void DebugBreak(Isolate* isolate); |
77 | 161 |
78 // Remove scheduled debugger break in given isolate if it has not | 162 // Remove scheduled debugger break in given isolate if it has not |
79 // happened yet. | 163 // happened yet. |
80 static void CancelDebugBreak(Isolate* isolate); | 164 static void CancelDebugBreak(Isolate* isolate); |
81 | 165 |
82 // Check if a debugger break is scheduled in the given isolate. | 166 // Check if a debugger break is scheduled in the given isolate. |
83 V8_DEPRECATED("No longer supported", | 167 V8_DEPRECATED("No longer supported", |
84 static bool CheckDebugBreak(Isolate* isolate)); | 168 static bool CheckDebugBreak(Isolate* isolate)); |
85 | 169 |
| 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 |
86 /** | 180 /** |
87 * Run a JavaScript function in the debugger. | 181 * Run a JavaScript function in the debugger. |
88 * \param fun the function to call | 182 * \param fun the function to call |
89 * \param data passed as second argument to the function | 183 * \param data passed as second argument to the function |
90 * With this call the debugger is entered and the function specified is called | 184 * With this call the debugger is entered and the function specified is called |
91 * with the execution state as the first argument. This makes it possible to | 185 * with the execution state as the first argument. This makes it possible to |
92 * get access to information otherwise not available during normal JavaScript | 186 * get access to information otherwise not available during normal JavaScript |
93 * execution e.g. details on stack frames. Receiver of the function call will | 187 * execution e.g. details on stack frames. Receiver of the function call will |
94 * be the debugger context global object, however this is a subject to change. | 188 * be the debugger context global object, however this is a subject to change. |
95 * The following example shows a JavaScript function which when passed to | 189 * The following example shows a JavaScript function which when passed to |
(...skipping 11 matching lines...) Expand all Loading... |
107 Local<Value> data = Local<Value>()); | 201 Local<Value> data = Local<Value>()); |
108 | 202 |
109 /** | 203 /** |
110 * Returns a mirror object for the given object. | 204 * Returns a mirror object for the given object. |
111 */ | 205 */ |
112 V8_DEPRECATED("No longer supported", | 206 V8_DEPRECATED("No longer supported", |
113 static MaybeLocal<Value> GetMirror(Local<Context> context, | 207 static MaybeLocal<Value> GetMirror(Local<Context> context, |
114 v8::Local<v8::Value> obj)); | 208 v8::Local<v8::Value> obj)); |
115 | 209 |
116 /** | 210 /** |
| 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 /** |
117 * Debugger is running in its own context which is entered while debugger | 245 * Debugger is running in its own context which is entered while debugger |
118 * messages are being dispatched. This is an explicit getter for this | 246 * messages are being dispatched. This is an explicit getter for this |
119 * debugger context. Note that the content of the debugger context is subject | 247 * debugger context. Note that the content of the debugger context is subject |
120 * to change. The Context exists only when the debugger is active, i.e. at | 248 * to change. The Context exists only when the debugger is active, i.e. at |
121 * least one DebugEventListener or MessageHandler is set. | 249 * least one DebugEventListener or MessageHandler is set. |
122 */ | 250 */ |
123 V8_DEPRECATED("Use v8-inspector", | 251 V8_DEPRECATED("Use v8-inspector", |
124 static Local<Context> GetDebugContext(Isolate* isolate)); | 252 static Local<Context> GetDebugContext(Isolate* isolate)); |
125 | 253 |
126 /** | 254 /** |
(...skipping 29 matching lines...) Expand all Loading... |
156 }; | 284 }; |
157 | 285 |
158 | 286 |
159 } // namespace v8 | 287 } // namespace v8 |
160 | 288 |
161 | 289 |
162 #undef EXPORT | 290 #undef EXPORT |
163 | 291 |
164 | 292 |
165 #endif // V8_V8_DEBUG_H_ | 293 #endif // V8_V8_DEBUG_H_ |
OLD | NEW |