src/3rdparty/v8/include/v8-debug.h

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