v8-debug.h

Go to the documentation of this file.

// Copyright 2008 the V8 project authors. All rights reserved.
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
//     * Redistributions of source code must retain the above copyright
//       notice, this list of conditions and the following disclaimer.
//     * Redistributions in binary form must reproduce the above
//       copyright notice, this list of conditions and the following
//       disclaimer in the documentation and/or other materials provided
//       with the distribution.
//     * Neither the name of Google Inc. nor the names of its
//       contributors may be used to endorse or promote products derived
//       from this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

#ifndef V8_V8_DEBUG_H_
#define V8_V8_DEBUG_H_

#include "v8.h"

namespace v8 {

// Debug events which can occur in the V8 JavaScript engine.
enum DebugEvent {
  Break = 1,
  Exception = 2,
  NewFunction = 3,
  BeforeCompile = 4,
  AfterCompile  = 5,
  ScriptCollected = 6,
  BreakForCommand = 7
};


class V8_EXPORT Debug {
 public:
  class ClientData {
   public:
    virtual ~ClientData() {}
  };


  class Message {
   public:
    virtual bool IsEvent() const = 0;
    virtual bool IsResponse() const = 0;
    virtual DebugEvent GetEvent() const = 0;

    virtual bool WillStartRunning() const = 0;

    virtual Handle<Object> GetExecutionState() const = 0;
    virtual Handle<Object> GetEventData() const = 0;

    virtual Handle<String> GetJSON() const = 0;

    virtual Handle<Context> GetEventContext() const = 0;

    virtual ClientData* GetClientData() const = 0;

    virtual Isolate* GetIsolate() const = 0;

    virtual ~Message() {}
  };


  class EventDetails {
   public:
    virtual DebugEvent GetEvent() const = 0;

    virtual Handle<Object> GetExecutionState() const = 0;
    virtual Handle<Object> GetEventData() const = 0;

    virtual Handle<Context> GetEventContext() const = 0;

    virtual Handle<Value> GetCallbackData() const = 0;

    virtual ClientData* GetClientData() const = 0;

    virtual ~EventDetails() {}
  };

  typedef void (*EventCallback2)(const EventDetails& event_details);

  typedef void (*MessageHandler2)(const Message& message);

  typedef void (*HostDispatchHandler)();

  typedef void (*DebugMessageDispatchHandler)();

  static bool SetDebugEventListener2(EventCallback2 that,
                                     Handle<Value> data = Handle<Value>());

  // Set a JavaScript debug event listener.
  static bool SetDebugEventListener(v8::Handle<v8::Object> that,
                                    Handle<Value> data = Handle<Value>());

  // Schedule a debugger break to happen when JavaScript code is run
  // in the given isolate. If no isolate is provided the default
  // isolate is used.
  static void DebugBreak(Isolate* isolate = NULL);

  // Remove scheduled debugger break in given isolate if it has not
  // happened yet. If no isolate is provided the default isolate is
  // used.
  static void CancelDebugBreak(Isolate* isolate = NULL);

  // Break execution of JavaScript in the given isolate (this method
  // can be invoked from a non-VM thread) for further client command
  // execution on a VM thread. Client data is then passed in
  // EventDetails to EventCallback2 at the moment when the VM actually
  // stops. If no isolate is provided the default isolate is used.
  static void DebugBreakForCommand(ClientData* data = NULL,
                                   Isolate* isolate = NULL);

  // Message based interface. The message protocol is JSON.
  static void SetMessageHandler2(MessageHandler2 handler);

  // If no isolate is provided the default isolate is
  // used.
  // TODO(dcarney): remove
  static void SendCommand(const uint16_t* command, int length,
                          ClientData* client_data = NULL,
                          Isolate* isolate = NULL);
  static void SendCommand(Isolate* isolate,
                          const uint16_t* command, int length,
                          ClientData* client_data = NULL);

  // Dispatch interface.
  static void SetHostDispatchHandler(HostDispatchHandler handler,
                                     int period = 100);

  static void SetDebugMessageDispatchHandler(
      DebugMessageDispatchHandler handler, bool provide_locker = false);

  static Local<Value> Call(v8::Handle<v8::Function> fun,
                           Handle<Value> data = Handle<Value>());

  static Local<Value> GetMirror(v8::Handle<v8::Value> obj);

  static bool EnableAgent(const char* name, int port,
                          bool wait_for_connection = false);

  static void DisableAgent();

  static void ProcessDebugMessages();

  static Local<Context> GetDebugContext();


  static void SetLiveEditEnabled(bool enable, Isolate* isolate = NULL);
};


}  // namespace v8


#undef EXPORT


#endif  // V8_V8_DEBUG_H_