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.
4
5#ifndef V8_V8_DEBUG_H_
6#define V8_V8_DEBUG_H_
7
8#include "v8.h"
9
10/**
11 * Debugger support for the V8 JavaScript engine.
12 */
13namespace v8 {
14
15// Debug events which can occur in the V8 JavaScript engine.
16enum DebugEvent {
17  Break = 1,
18  Exception = 2,
19  NewFunction = 3,
20  BeforeCompile = 4,
21  AfterCompile  = 5,
22  CompileError = 6,
23  PromiseEvent = 7,
24  AsyncTaskEvent = 8,
25  BreakForCommand = 9
26};
27
28
29class V8_EXPORT Debug {
30 public:
31  /**
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.
34   */
35  class ClientData {
36   public:
37    virtual ~ClientData() {}
38  };
39
40
41  /**
42   * A message object passed to the debug message handler.
43   */
44  class Message {
45   public:
46    /**
47     * Check type of message.
48     */
49    virtual bool IsEvent() const = 0;
50    virtual bool IsResponse() const = 0;
51    virtual DebugEvent GetEvent() const = 0;
52
53    /**
54     * Indicate whether this is a response to a continue command which will
55     * start the VM running after this is processed.
56     */
57    virtual bool WillStartRunning() const = 0;
58
59    /**
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.
63     */
64    virtual Handle<Object> GetExecutionState() const = 0;
65    virtual Handle<Object> GetEventData() const = 0;
66
67    /**
68     * Get the debugger protocol JSON.
69     */
70    virtual Handle<String> GetJSON() const = 0;
71
72    /**
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.
76     */
77    virtual Handle<Context> GetEventContext() const = 0;
78
79    /**
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
84     * no message handler.
85     */
86    virtual ClientData* GetClientData() const = 0;
87
88    virtual Isolate* GetIsolate() const = 0;
89
90    virtual ~Message() {}
91  };
92
93
94  /**
95   * An event details object passed to the debug event listener.
96   */
97  class EventDetails {
98   public:
99    /**
100     * Event type.
101     */
102    virtual DebugEvent GetEvent() const = 0;
103
104    /**
105     * Access to execution state and event data of the debug event. Don't store
106     * these cross callbacks as their content becomes invalid.
107     */
108    virtual Handle<Object> GetExecutionState() const = 0;
109    virtual Handle<Object> GetEventData() const = 0;
110
111    /**
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.
115     */
116    virtual Handle<Context> GetEventContext() const = 0;
117
118    /**
119     * Client data passed with the corresponding callback when it was
120     * registered.
121     */
122    virtual Handle<Value> GetCallbackData() const = 0;
123
124    /**
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.
128     */
129    virtual ClientData* GetClientData() const = 0;
130
131    virtual ~EventDetails() {}
132  };
133
134  /**
135   * Debug event callback function.
136   *
137   * \param event_details object providing information about the debug event
138   *
139   * A EventCallback2 does not take possession of the event data,
140   * and must not rely on the data persisting after the handler returns.
141   */
142  typedef void (*EventCallback)(const EventDetails& event_details);
143
144  /**
145   * Debug message callback function.
146   *
147   * \param message the debug message handler message object
148   *
149   * A MessageHandler2 does not take possession of the message data,
150   * and must not rely on the data persisting after the handler returns.
151   */
152  typedef void (*MessageHandler)(const Message& message);
153
154  /**
155   * Callback function for the host to ensure debug messages are processed.
156   */
157  typedef void (*DebugMessageDispatchHandler)();
158
159  static bool SetDebugEventListener(EventCallback that,
160                                    Handle<Value> data = Handle<Value>());
161
162  // Schedule a debugger break to happen when JavaScript code is run
163  // in the given isolate.
164  static void DebugBreak(Isolate* isolate);
165
166  // Remove scheduled debugger break in given isolate if it has not
167  // happened yet.
168  static void CancelDebugBreak(Isolate* isolate);
169
170  // Check if a debugger break is scheduled in the given isolate.
171  static bool CheckDebugBreak(Isolate* isolate);
172
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
177  // stops.
178  static void DebugBreakForCommand(Isolate* isolate, ClientData* data);
179
180  // Message based interface. The message protocol is JSON.
181  static void SetMessageHandler(MessageHandler handler);
182
183  static void SendCommand(Isolate* isolate,
184                          const uint16_t* command, int length,
185                          ClientData* client_data = NULL);
186
187 /**
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.
198  *
199  * \code
200  *   function frame_source_line(exec_state) {
201  *     return exec_state.frame(0).sourceLine();
202  *   }
203  * \endcode
204  */
205  static Local<Value> Call(v8::Handle<v8::Function> fun,
206                           Handle<Value> data = Handle<Value>());
207
208  /**
209   * Returns a mirror object for the given object.
210   */
211  static Local<Value> GetMirror(v8::Handle<v8::Value> obj);
212
213  /**
214   * Makes V8 process all pending debug messages.
215   *
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
219   * for a while.
220   *
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
223   * pending messages;
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.
230   *
231   * Technically this method in many senses is equivalent to executing empty
232   * script:
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).
240   *
241   * "Evaluate" debug command behavior currently is not specified in scope
242   * of this method.
243   */
244  static void ProcessDebugMessages();
245
246  /**
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
250   * to change.
251   */
252  static Local<Context> GetDebugContext();
253
254
255  /**
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.
259   */
260  static void SetLiveEditEnabled(Isolate* isolate, bool enable);
261};
262
263
264}  // namespace v8
265
266
267#undef EXPORT
268
269
270#endif  // V8_V8_DEBUG_H_
271