src/v8/include/v8-debug.h

   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  */
  13 namespace v8 {
  14
  15 // Debug events which can occur in the V8 JavaScript engine.
  16 enum DebugEvent {
  17   Break = 1,
  18   Exception = 2,
  19   NewFunction = 3,
  20   BeforeCompile = 4,
  21   AfterCompile  = 5,
  22   ScriptCollected = 6,
  23   BreakForCommand = 7
  24 };
  25
  26
  27 class V8_EXPORT Debug {
  28  public:
  29   /**
  30    * A client object passed to the v8 debugger whose ownership will be taken by
  31    * it. v8 is always responsible for deleting the object.
  32    */
  33   class ClientData {
  34    public:
  35     virtual ~ClientData() {}
  36   };
  37
  38
  39   /**
  40    * A message object passed to the debug message handler.
  41    */
  42   class Message {
  43    public:
  44     /**
  45      * Check type of message.
  46      */
  47     virtual bool IsEvent() const = 0;
  48     virtual bool IsResponse() const = 0;
  49     virtual DebugEvent GetEvent() const = 0;
  50
  51     /**
  52      * Indicate whether this is a response to a continue command which will
  53      * start the VM running after this is processed.
  54      */
  55     virtual bool WillStartRunning() const = 0;
  56
  57     /**
  58      * Access to execution state and event data. Don't store these cross
  59      * callbacks as their content becomes invalid. These objects are from the
  60      * debugger event that started the debug message loop.
  61      */
  62     virtual Handle<Object> GetExecutionState() const = 0;
  63     virtual Handle<Object> GetEventData() const = 0;
  64
  65     /**
  66      * Get the debugger protocol JSON.
  67      */
  68     virtual Handle<String> GetJSON() const = 0;
  69
  70     /**
  71      * Get the context active when the debug event happened. Note this is not
  72      * the current active context as the JavaScript part of the debugger is
  73      * running in its own context which is entered at this point.
  74      */
  75     virtual Handle<Context> GetEventContext() const = 0;
  76
  77     /**
  78      * Client data passed with the corresponding request if any. This is the
  79      * client_data data value passed into Debug::SendCommand along with the
  80      * request that led to the message or NULL if the message is an event. The
  81      * debugger takes ownership of the data and will delete it even if there is
  82      * no message handler.
  83      */
  84     virtual ClientData* GetClientData() const = 0;
  85
  86     virtual Isolate* GetIsolate() const = 0;
  87
  88     virtual ~Message() {}
  89   };
  90
  91
  92   /**
  93    * An event details object passed to the debug event listener.
  94    */
  95   class EventDetails {
  96    public:
  97     /**
  98      * Event type.
  99      */
 100     virtual DebugEvent GetEvent() const = 0;
 101
 102     /**
 103      * Access to execution state and event data of the debug event. Don't store
 104      * these cross callbacks as their content becomes invalid.
 105      */
 106     virtual Handle<Object> GetExecutionState() const = 0;
 107     virtual Handle<Object> GetEventData() const = 0;
 108
 109     /**
 110      * Get the context active when the debug event happened. Note this is not
 111      * the current active context as the JavaScript part of the debugger is
 112      * running in its own context which is entered at this point.
 113      */
 114     virtual Handle<Context> GetEventContext() const = 0;
 115
 116     /**
 117      * Client data passed with the corresponding callback when it was
 118      * registered.
 119      */
 120     virtual Handle<Value> GetCallbackData() const = 0;
 121
 122     /**
 123      * Client data passed to DebugBreakForCommand function. The
 124      * debugger takes ownership of the data and will delete it even if
 125      * there is no message handler.
 126      */
 127     virtual ClientData* GetClientData() const = 0;
 128
 129     virtual ~EventDetails() {}
 130   };
 131
 132   /**
 133    * Debug event callback function.
 134    *
 135    * \param event_details object providing information about the debug event
 136    *
 137    * A EventCallback2 does not take possession of the event data,
 138    * and must not rely on the data persisting after the handler returns.
 139    */
 140   typedef void (*EventCallback2)(const EventDetails& event_details);
 141
 142   /**
 143    * Debug message callback function.
 144    *
 145    * \param message the debug message handler message object
 146    *
 147    * A MessageHandler2 does not take possession of the message data,
 148    * and must not rely on the data persisting after the handler returns.
 149    */
 150   typedef void (*MessageHandler2)(const Message& message);
 151
 152   /**
 153    * Debug host dispatch callback function.
 154    */
 155   typedef void (*HostDispatchHandler)();
 156
 157   /**
 158    * Callback function for the host to ensure debug messages are processed.
 159    */
 160   typedef void (*DebugMessageDispatchHandler)();
 161
 162   static bool SetDebugEventListener2(EventCallback2 that,
 163                                      Handle<Value> data = Handle<Value>());
 164
 165   // Set a JavaScript debug event listener.
 166   static bool SetDebugEventListener(v8::Handle<v8::Object> that,
 167                                     Handle<Value> data = Handle<Value>());
 168
 169   // Schedule a debugger break to happen when JavaScript code is run
 170   // in the given isolate.
 171   static void DebugBreak(Isolate* isolate);
 172
 173   // Remove scheduled debugger break in given isolate if it has not
 174   // happened yet.
 175   static void CancelDebugBreak(Isolate* isolate);
 176
 177   // Break execution of JavaScript in the given isolate (this method
 178   // can be invoked from a non-VM thread) for further client command
 179   // execution on a VM thread. Client data is then passed in
 180   // EventDetails to EventCallback2 at the moment when the VM actually
 181   // stops.
 182   static void DebugBreakForCommand(Isolate* isolate, ClientData* data);
 183
 184   // TODO(svenpanne) Remove this when Chrome is updated.
 185   static void DebugBreakForCommand(ClientData* data, Isolate* isolate) {
 186     DebugBreakForCommand(isolate, data);
 187   }
 188
 189   // Message based interface. The message protocol is JSON.
 190   static void SetMessageHandler2(MessageHandler2 handler);
 191
 192   static void SendCommand(Isolate* isolate,
 193                           const uint16_t* command, int length,
 194                           ClientData* client_data = NULL);
 195
 196   // Dispatch interface.
 197   static void SetHostDispatchHandler(HostDispatchHandler handler,
 198                                      int period = 100);
 199
 200   /**
 201    * Register a callback function to be called when a debug message has been
 202    * received and is ready to be processed. For the debug messages to be
 203    * processed V8 needs to be entered, and in certain embedding scenarios this
 204    * callback can be used to make sure V8 is entered for the debug message to
 205    * be processed. Note that debug messages will only be processed if there is
 206    * a V8 break. This can happen automatically by using the option
 207    * --debugger-auto-break.
 208    * \param provide_locker requires that V8 acquires v8::Locker for you before
 209    *        calling handler
 210    */
 211   static void SetDebugMessageDispatchHandler(
 212       DebugMessageDispatchHandler handler, bool provide_locker = false);
 213
 214  /**
 215   * Run a JavaScript function in the debugger.
 216   * \param fun the function to call
 217   * \param data passed as second argument to the function
 218   * With this call the debugger is entered and the function specified is called
 219   * with the execution state as the first argument. This makes it possible to
 220   * get access to information otherwise not available during normal JavaScript
 221   * execution e.g. details on stack frames. Receiver of the function call will
 222   * be the debugger context global object, however this is a subject to change.
 223   * The following example shows a JavaScript function which when passed to
 224   * v8::Debug::Call will return the current line of JavaScript execution.
 225   *
 226   * \code
 227   *   function frame_source_line(exec_state) {
 228   *     return exec_state.frame(0).sourceLine();
 229   *   }
 230   * \endcode
 231   */
 232   static Local<Value> Call(v8::Handle<v8::Function> fun,
 233                            Handle<Value> data = Handle<Value>());
 234
 235   /**
 236    * Returns a mirror object for the given object.
 237    */
 238   static Local<Value> GetMirror(v8::Handle<v8::Value> obj);
 239
 240  /**
 241   * Enable the V8 builtin debug agent. The debugger agent will listen on the
 242   * supplied TCP/IP port for remote debugger connection.
 243   * \param name the name of the embedding application
 244   * \param port the TCP/IP port to listen on
 245   * \param wait_for_connection whether V8 should pause on a first statement
 246   *   allowing remote debugger to connect before anything interesting happened
 247   */
 248   static bool EnableAgent(const char* name, int port,
 249                           bool wait_for_connection = false);
 250
 251   /**
 252     * Disable the V8 builtin debug agent. The TCP/IP connection will be closed.
 253     */
 254   static void DisableAgent();
 255
 256   /**
 257    * Makes V8 process all pending debug messages.
 258    *
 259    * From V8 point of view all debug messages come asynchronously (e.g. from
 260    * remote debugger) but they all must be handled synchronously: V8 cannot
 261    * do 2 things at one time so normal script execution must be interrupted
 262    * for a while.
 263    *
 264    * Generally when message arrives V8 may be in one of 3 states:
 265    * 1. V8 is running script; V8 will automatically interrupt and process all
 266    * pending messages;
 267    * 2. V8 is suspended on debug breakpoint; in this state V8 is dedicated
 268    * to reading and processing debug messages;
 269    * 3. V8 is not running at all or has called some long-working C++ function;
 270    * by default it means that processing of all debug messages will be deferred
 271    * until V8 gets control again; however, embedding application may improve
 272    * this by manually calling this method.
 273    *
 274    * It makes sense to call this method whenever a new debug message arrived and
 275    * V8 is not already running. Method v8::Debug::SetDebugMessageDispatchHandler
 276    * should help with the former condition.
 277    *
 278    * Technically this method in many senses is equivalent to executing empty
 279    * script:
 280    * 1. It does nothing except for processing all pending debug messages.
 281    * 2. It should be invoked with the same precautions and from the same context
 282    * as V8 script would be invoked from, because:
 283    *   a. with "evaluate" command it can do whatever normal script can do,
 284    *   including all native calls;
 285    *   b. no other thread should call V8 while this method is running
 286    *   (v8::Locker may be used here).
 287    *
 288    * "Evaluate" debug command behavior currently is not specified in scope
 289    * of this method.
 290    */
 291   static void ProcessDebugMessages();
 292
 293   /**
 294    * Debugger is running in its own context which is entered while debugger
 295    * messages are being dispatched. This is an explicit getter for this
 296    * debugger context. Note that the content of the debugger context is subject
 297    * to change.
 298    */
 299   static Local<Context> GetDebugContext();
 300
 301
 302   /**
 303    * Enable/disable LiveEdit functionality for the given Isolate
 304    * (default Isolate if not provided). V8 will abort if LiveEdit is
 305    * unexpectedly used. LiveEdit is enabled by default.
 306    */
 307   static void SetLiveEditEnabled(Isolate* isolate, bool enable);
 308
 309   // TODO(svenpanne) Remove this when Chrome is updated.
 310   static void SetLiveEditEnabled(bool enable, Isolate* isolate) {
 311     SetLiveEditEnabled(isolate, enable);
 312   }
 313 };
 314
 315
 316 }  // namespace v8
 317
 318
 319 #undef EXPORT
 320
 321
 322 #endif  // V8_V8_DEBUG_H_