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   CompileError = 6,
  23   PromiseEvent = 7,
  24   AsyncTaskEvent = 8,
  25   BreakForCommand = 9
  26 };
  27
  28
  29 class 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_