Home | History | Annotate | Download | only in include
      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_
    401