1// Copyright 2008 the V8 project authors. All rights reserved.
2// Redistribution and use in source and binary forms, with or without
3// modification, are permitted provided that the following conditions are
4// met:
5//
6//     * Redistributions of source code must retain the above copyright
7//       notice, this list of conditions and the following disclaimer.
8//     * Redistributions in binary form must reproduce the above
9//       copyright notice, this list of conditions and the following
10//       disclaimer in the documentation and/or other materials provided
11//       with the distribution.
12//     * Neither the name of Google Inc. nor the names of its
13//       contributors may be used to endorse or promote products derived
14//       from this software without specific prior written permission.
15//
16// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
17// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
18// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
19// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
20// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
21// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
22// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
26// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27
28#ifndef V8_V8_DEBUG_H_
29#define V8_V8_DEBUG_H_
30
31#include "v8.h"
32
33#ifdef _WIN32
34typedef int int32_t;
35typedef unsigned int uint32_t;
36typedef unsigned short uint16_t;  // NOLINT
37typedef long long int64_t;  // NOLINT
38
39// Setup for Windows DLL export/import. See v8.h in this directory for
40// information on how to build/use V8 as a DLL.
41#if defined(BUILDING_V8_SHARED) && defined(USING_V8_SHARED)
42#error both BUILDING_V8_SHARED and USING_V8_SHARED are set - please check the\
43  build configuration to ensure that at most one of these is set
44#endif
45
46#ifdef BUILDING_V8_SHARED
47#define EXPORT __declspec(dllexport)
48#elif USING_V8_SHARED
49#define EXPORT __declspec(dllimport)
50#else
51#define EXPORT
52#endif
53
54#else  // _WIN32
55
56// Setup for Linux shared library export. See v8.h in this directory for
57// information on how to build/use V8 as shared library.
58#if defined(__GNUC__) && (__GNUC__ >= 4) && defined(V8_SHARED)
59#define EXPORT __attribute__ ((visibility("default")))
60#else  // defined(__GNUC__) && (__GNUC__ >= 4)
61#define EXPORT
62#endif  // defined(__GNUC__) && (__GNUC__ >= 4)
63
64#endif  // _WIN32
65
66
67/**
68 * Debugger support for the V8 JavaScript engine.
69 */
70namespace v8 {
71
72// Debug events which can occur in the V8 JavaScript engine.
73enum DebugEvent {
74  Break = 1,
75  Exception = 2,
76  NewFunction = 3,
77  BeforeCompile = 4,
78  AfterCompile  = 5,
79  ScriptCollected = 6
80};
81
82
83class EXPORT Debug {
84 public:
85  /**
86   * A client object passed to the v8 debugger whose ownership will be taken by
87   * it. v8 is always responsible for deleting the object.
88   */
89  class ClientData {
90   public:
91    virtual ~ClientData() {}
92  };
93
94
95  /**
96   * A message object passed to the debug message handler.
97   */
98  class Message {
99   public:
100    /**
101     * Check type of message.
102     */
103    virtual bool IsEvent() const = 0;
104    virtual bool IsResponse() const = 0;
105    virtual DebugEvent GetEvent() const = 0;
106
107    /**
108     * Indicate whether this is a response to a continue command which will
109     * start the VM running after this is processed.
110     */
111    virtual bool WillStartRunning() const = 0;
112
113    /**
114     * Access to execution state and event data. Don't store these cross
115     * callbacks as their content becomes invalid. These objects are from the
116     * debugger event that started the debug message loop.
117     */
118    virtual Handle<Object> GetExecutionState() const = 0;
119    virtual Handle<Object> GetEventData() const = 0;
120
121    /**
122     * Get the debugger protocol JSON.
123     */
124    virtual Handle<String> GetJSON() const = 0;
125
126    /**
127     * Get the context active when the debug event happened. Note this is not
128     * the current active context as the JavaScript part of the debugger is
129     * running in it's own context which is entered at this point.
130     */
131    virtual Handle<Context> GetEventContext() const = 0;
132
133    /**
134     * Client data passed with the corresponding request if any. This is the
135     * client_data data value passed into Debug::SendCommand along with the
136     * request that led to the message or NULL if the message is an event. The
137     * debugger takes ownership of the data and will delete it even if there is
138     * no message handler.
139     */
140    virtual ClientData* GetClientData() const = 0;
141
142    virtual ~Message() {}
143  };
144
145
146  /**
147   * Debug event callback function.
148   *
149   * \param event the type of the debug event that triggered the callback
150   *   (enum DebugEvent)
151   * \param exec_state execution state (JavaScript object)
152   * \param event_data event specific data (JavaScript object)
153   * \param data value passed by the user to SetDebugEventListener
154   */
155  typedef void (*EventCallback)(DebugEvent event,
156                                Handle<Object> exec_state,
157                                Handle<Object> event_data,
158                                Handle<Value> data);
159
160
161  /**
162   * Debug message callback function.
163   *
164   * \param message the debug message handler message object
165   * \param length length of the message
166   * \param client_data the data value passed when registering the message handler
167
168   * A MessageHandler does not take posession of the message string,
169   * and must not rely on the data persisting after the handler returns.
170   *
171   * This message handler is deprecated. Use MessageHandler2 instead.
172   */
173  typedef void (*MessageHandler)(const uint16_t* message, int length,
174                                 ClientData* client_data);
175
176  /**
177   * Debug message callback function.
178   *
179   * \param message the debug message handler message object
180
181   * A MessageHandler does not take posession of the message data,
182   * and must not rely on the data persisting after the handler returns.
183   */
184  typedef void (*MessageHandler2)(const Message& message);
185
186  /**
187   * Debug host dispatch callback function.
188   */
189  typedef void (*HostDispatchHandler)();
190
191  /**
192   * Callback function for the host to ensure debug messages are processed.
193   */
194  typedef void (*DebugMessageDispatchHandler)();
195
196  // Set a C debug event listener.
197  static bool SetDebugEventListener(EventCallback that,
198                                    Handle<Value> data = Handle<Value>());
199
200  // Set a JavaScript debug event listener.
201  static bool SetDebugEventListener(v8::Handle<v8::Object> that,
202                                    Handle<Value> data = Handle<Value>());
203
204  // Break execution of JavaScript.
205  static void DebugBreak();
206
207  // Message based interface. The message protocol is JSON. NOTE the message
208  // handler thread is not supported any more parameter must be false.
209  static void SetMessageHandler(MessageHandler handler,
210                                bool message_handler_thread = false);
211  static void SetMessageHandler2(MessageHandler2 handler);
212  static void SendCommand(const uint16_t* command, int length,
213                          ClientData* client_data = NULL);
214
215  // Dispatch interface.
216  static void SetHostDispatchHandler(HostDispatchHandler handler,
217                                     int period = 100);
218
219  /**
220   * Register a callback function to be called when a debug message has been
221   * received and is ready to be processed. For the debug messages to be
222   * processed V8 needs to be entered, and in certain embedding scenarios this
223   * callback can be used to make sure V8 is entered for the debug message to
224   * be processed. Note that debug messages will only be processed if there is
225   * a V8 break. This can happen automatically by using the option
226   * --debugger-auto-break.
227   * \param provide_locker requires that V8 acquires v8::Locker for you before
228   *        calling handler
229   */
230  static void SetDebugMessageDispatchHandler(
231      DebugMessageDispatchHandler handler, bool provide_locker = false);
232
233 /**
234  * Run a JavaScript function in the debugger.
235  * \param fun the function to call
236  * \param data passed as second argument to the function
237  * With this call the debugger is entered and the function specified is called
238  * with the execution state as the first argument. This makes it possible to
239  * get access to information otherwise not available during normal JavaScript
240  * execution e.g. details on stack frames. The following example show a
241  * JavaScript function which when passed to v8::Debug::Call will return the
242  * current line of JavaScript execution.
243  *
244  * \code
245  *   function frame_source_line(exec_state) {
246  *     return exec_state.frame(0).sourceLine();
247  *   }
248  * \endcode
249  */
250  static Local<Value> Call(v8::Handle<v8::Function> fun,
251                            Handle<Value> data = Handle<Value>());
252
253  /**
254   * Returns a mirror object for the given object.
255   */
256  static Local<Value> GetMirror(v8::Handle<v8::Value> obj);
257
258 /**
259  * Enable the V8 builtin debug agent. The debugger agent will listen on the
260  * supplied TCP/IP port for remote debugger connection.
261  * \param name the name of the embedding application
262  * \param port the TCP/IP port to listen on
263  * \param wait_for_connection whether V8 should pause on a first statement
264  *   allowing remote debugger to connect before anything interesting happened
265  */
266  static bool EnableAgent(const char* name, int port,
267                          bool wait_for_connection = false);
268
269  /**
270   * Makes V8 process all pending debug messages.
271   *
272   * From V8 point of view all debug messages come asynchronously (e.g. from
273   * remote debugger) but they all must be handled synchronously: V8 cannot
274   * do 2 things at one time so normal script execution must be interrupted
275   * for a while.
276   *
277   * Generally when message arrives V8 may be in one of 3 states:
278   * 1. V8 is running script; V8 will automatically interrupt and process all
279   * pending messages (however auto_break flag should be enabled);
280   * 2. V8 is suspended on debug breakpoint; in this state V8 is dedicated
281   * to reading and processing debug messages;
282   * 3. V8 is not running at all or has called some long-working C++ function;
283   * by default it means that processing of all debug message will be deferred
284   * until V8 gets control again; however, embedding application may improve
285   * this by manually calling this method.
286   *
287   * It makes sense to call this method whenever a new debug message arrived and
288   * V8 is not already running. Method v8::Debug::SetDebugMessageDispatchHandler
289   * should help with the former condition.
290   *
291   * Technically this method in many senses is equivalent to executing empty
292   * script:
293   * 1. It does nothing except for processing all pending debug messages.
294   * 2. It should be invoked with the same precautions and from the same context
295   * as V8 script would be invoked from, because:
296   *   a. with "evaluate" command it can do whatever normal script can do,
297   *   including all native calls;
298   *   b. no other thread should call V8 while this method is running
299   *   (v8::Locker may be used here).
300   *
301   * "Evaluate" debug command behavior currently is not specified in scope
302   * of this method.
303   */
304  static void ProcessDebugMessages();
305};
306
307
308}  // namespace v8
309
310
311#undef EXPORT
312
313
314#endif  // V8_V8_DEBUG_H_
315