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.
11 * Debugger support for the V8 JavaScript engine.
15 // Debug events which can occur in the V8 JavaScript engine.
29 class V8_EXPORT Debug {
32 * A client object passed to the v8 debugger whose ownership will be taken by
33 * it. v8 is always responsible for deleting the object.
37 virtual ~ClientData() {}
42 * A message object passed to the debug message handler.
47 * Check type of message.
49 virtual bool IsEvent() const = 0;
50 virtual bool IsResponse() const = 0;
51 virtual DebugEvent GetEvent() const = 0;
54 * Indicate whether this is a response to a continue command which will
55 * start the VM running after this is processed.
57 virtual bool WillStartRunning() const = 0;
60 * Access to execution state and event data. Don't store these cross
61 * callbacks as their content becomes invalid. These objects are from the
62 * debugger event that started the debug message loop.
64 virtual Handle<Object> GetExecutionState() const = 0;
65 virtual Handle<Object> GetEventData() const = 0;
68 * Get the debugger protocol JSON.
70 virtual Handle<String> GetJSON() const = 0;
73 * Get the context active when the debug event happened. Note this is not
74 * the current active context as the JavaScript part of the debugger is
75 * running in its own context which is entered at this point.
77 virtual Handle<Context> GetEventContext() const = 0;
80 * Client data passed with the corresponding request if any. This is the
81 * client_data data value passed into Debug::SendCommand along with the
82 * request that led to the message or NULL if the message is an event. The
83 * debugger takes ownership of the data and will delete it even if there is
86 virtual ClientData* GetClientData() const = 0;
88 virtual Isolate* GetIsolate() const = 0;
95 * An event details object passed to the debug event listener.
102 virtual DebugEvent GetEvent() const = 0;
105 * Access to execution state and event data of the debug event. Don't store
106 * these cross callbacks as their content becomes invalid.
108 virtual Handle<Object> GetExecutionState() const = 0;
109 virtual Handle<Object> GetEventData() const = 0;
112 * Get the context active when the debug event happened. Note this is not
113 * the current active context as the JavaScript part of the debugger is
114 * running in its own context which is entered at this point.
116 virtual Handle<Context> GetEventContext() const = 0;
119 * Client data passed with the corresponding callback when it was
122 virtual Handle<Value> GetCallbackData() const = 0;
125 * Client data passed to DebugBreakForCommand function. The
126 * debugger takes ownership of the data and will delete it even if
127 * there is no message handler.
129 virtual ClientData* GetClientData() const = 0;
131 virtual ~EventDetails() {}
135 * Debug event callback function.
137 * \param event_details object providing information about the debug event
139 * A EventCallback2 does not take possession of the event data,
140 * and must not rely on the data persisting after the handler returns.
142 typedef void (*EventCallback)(const EventDetails& event_details);
145 * Debug message callback function.
147 * \param message the debug message handler message object
149 * A MessageHandler2 does not take possession of the message data,
150 * and must not rely on the data persisting after the handler returns.
152 typedef void (*MessageHandler)(const Message& message);
155 * Callback function for the host to ensure debug messages are processed.
157 typedef void (*DebugMessageDispatchHandler)();
159 static bool SetDebugEventListener(EventCallback that,
160 Handle<Value> data = Handle<Value>());
162 // Schedule a debugger break to happen when JavaScript code is run
163 // in the given isolate.
164 static void DebugBreak(Isolate* isolate);
166 // Remove scheduled debugger break in given isolate if it has not
168 static void CancelDebugBreak(Isolate* isolate);
170 // Check if a debugger break is scheduled in the given isolate.
171 static bool CheckDebugBreak(Isolate* isolate);
173 // Break execution of JavaScript in the given isolate (this method
174 // can be invoked from a non-VM thread) for further client command
175 // execution on a VM thread. Client data is then passed in
176 // EventDetails to EventCallback2 at the moment when the VM actually
178 static void DebugBreakForCommand(Isolate* isolate, ClientData* data);
180 // Message based interface. The message protocol is JSON.
181 static void SetMessageHandler(MessageHandler handler);
183 static void SendCommand(Isolate* isolate,
184 const uint16_t* command, int length,
185 ClientData* client_data = NULL);
188 * Run a JavaScript function in the debugger.
189 * \param fun the function to call
190 * \param data passed as second argument to the function
191 * With this call the debugger is entered and the function specified is called
192 * with the execution state as the first argument. This makes it possible to
193 * get access to information otherwise not available during normal JavaScript
194 * execution e.g. details on stack frames. Receiver of the function call will
195 * be the debugger context global object, however this is a subject to change.
196 * The following example shows a JavaScript function which when passed to
197 * v8::Debug::Call will return the current line of JavaScript execution.
200 * function frame_source_line(exec_state) {
201 * return exec_state.frame(0).sourceLine();
205 static Local<Value> Call(v8::Handle<v8::Function> fun,
206 Handle<Value> data = Handle<Value>());
209 * Returns a mirror object for the given object.
211 static Local<Value> GetMirror(v8::Handle<v8::Value> obj);
214 * Makes V8 process all pending debug messages.
216 * From V8 point of view all debug messages come asynchronously (e.g. from
217 * remote debugger) but they all must be handled synchronously: V8 cannot
218 * do 2 things at one time so normal script execution must be interrupted
221 * Generally when message arrives V8 may be in one of 3 states:
222 * 1. V8 is running script; V8 will automatically interrupt and process all
224 * 2. V8 is suspended on debug breakpoint; in this state V8 is dedicated
225 * to reading and processing debug messages;
226 * 3. V8 is not running at all or has called some long-working C++ function;
227 * by default it means that processing of all debug messages will be deferred
228 * until V8 gets control again; however, embedding application may improve
229 * this by manually calling this method.
231 * Technically this method in many senses is equivalent to executing empty
233 * 1. It does nothing except for processing all pending debug messages.
234 * 2. It should be invoked with the same precautions and from the same context
235 * as V8 script would be invoked from, because:
236 * a. with "evaluate" command it can do whatever normal script can do,
237 * including all native calls;
238 * b. no other thread should call V8 while this method is running
239 * (v8::Locker may be used here).
241 * "Evaluate" debug command behavior currently is not specified in scope
244 static void ProcessDebugMessages();
247 * Debugger is running in its own context which is entered while debugger
248 * messages are being dispatched. This is an explicit getter for this
249 * debugger context. Note that the content of the debugger context is subject
252 static Local<Context> GetDebugContext();
256 * Enable/disable LiveEdit functionality for the given Isolate
257 * (default Isolate if not provided). V8 will abort if LiveEdit is
258 * unexpectedly used. LiveEdit is enabled by default.
260 static void SetLiveEditEnabled(Isolate* isolate, bool enable);
270 #endif // V8_V8_DEBUG_H_