include/v8-debug.h - v8/v8 - Git at Google

 // Copyright 2008 the V8 project authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

 #ifndef V8_V8_DEBUG_H_
 #define V8_V8_DEBUG_H_

 #include "v8.h"

 /**
  * Debugger support for the V8 JavaScript engine.
  */
 namespace v8 {

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


 class V8_EXPORT Debug {
  public:
   /**
    * A client object passed to the v8 debugger whose ownership will be taken by
    * it. v8 is always responsible for deleting the object.
    */
   class ClientData {
    public:
     virtual ~ClientData() {}
   };


   /**
    * A message object passed to the debug message handler.
    */
   class Message {
    public:
     /**
      * Check type of message.
      */
     virtual bool IsEvent() const = 0;
     virtual bool IsResponse() const = 0;
     virtual DebugEvent GetEvent() const = 0;

     /**
      * Indicate whether this is a response to a continue command which will
      * start the VM running after this is processed.
      */
     virtual bool WillStartRunning() const = 0;

     /**
      * Access to execution state and event data. Don't store these cross
      * callbacks as their content becomes invalid. These objects are from the
      * debugger event that started the debug message loop.
      */
     virtual Local<Object> GetExecutionState() const = 0;
     virtual Local<Object> GetEventData() const = 0;

     /**
      * Get the debugger protocol JSON.
      */
     virtual Local<String> GetJSON() const = 0;

     /**
      * Get the context active when the debug event happened. Note this is not
      * the current active context as the JavaScript part of the debugger is
      * running in its own context which is entered at this point.
      */
     virtual Local<Context> GetEventContext() const = 0;

     /**
      * Client data passed with the corresponding request if any. This is the
      * client_data data value passed into Debug::SendCommand along with the
      * request that led to the message or NULL if the message is an event. The
      * debugger takes ownership of the data and will delete it even if there is
      * no message handler.
      */
     virtual ClientData* GetClientData() const = 0;

     virtual Isolate* GetIsolate() const = 0;

     virtual ~Message() {}
   };


   /**
    * An event details object passed to the debug event listener.
    */
   class EventDetails {
    public:
     /**
      * Event type.
      */
     virtual DebugEvent GetEvent() const = 0;

     /**
      * Access to execution state and event data of the debug event. Don't store
      * these cross callbacks as their content becomes invalid.
      */
     virtual Local<Object> GetExecutionState() const = 0;
     virtual Local<Object> GetEventData() const = 0;

     /**
      * Get the context active when the debug event happened. Note this is not
      * the current active context as the JavaScript part of the debugger is
      * running in its own context which is entered at this point.
      */
     virtual Local<Context> GetEventContext() const = 0;

     /**
      * Client data passed with the corresponding callback when it was
      * registered.
      */
     virtual Local<Value> GetCallbackData() const = 0;

     /**
      * Client data passed to DebugBreakForCommand function. The
      * debugger takes ownership of the data and will delete it even if
      * there is no message handler.
      */
     virtual ClientData* GetClientData() const = 0;

     virtual ~EventDetails() {}
   };

   /**
    * Debug event callback function.
    *
    * \param event_details object providing information about the debug event
    *
    * A EventCallback2 does not take possession of the event data,
    * and must not rely on the data persisting after the handler returns.
    */
   typedef void (*EventCallback)(const EventDetails& event_details);

   /**
    * Debug message callback function.
    *
    * \param message the debug message handler message object
    *
    * A MessageHandler2 does not take possession of the message data,
    * and must not rely on the data persisting after the handler returns.
    */
   typedef void (*MessageHandler)(const Message& message);

   /**
    * Callback function for the host to ensure debug messages are processed.
    */
   typedef void (*DebugMessageDispatchHandler)();

   static bool SetDebugEventListener(EventCallback that,
                                     Local<Value> data = Local<Value>());

   // Schedule a debugger break to happen when JavaScript code is run
   // in the given isolate.
   static void DebugBreak(Isolate* isolate);

   // Remove scheduled debugger break in given isolate if it has not
   // happened yet.
   static void CancelDebugBreak(Isolate* isolate);

   // Check if a debugger break is scheduled in the given isolate.
   static bool CheckDebugBreak(Isolate* isolate);

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

   static void SendCommand(Isolate* isolate,
                           const uint16_t* command, int length,
                           ClientData* client_data = NULL);

  /**
   * Run a JavaScript function in the debugger.
   * \param fun the function to call
   * \param data passed as second argument to the function
   * With this call the debugger is entered and the function specified is called
   * with the execution state as the first argument. This makes it possible to
   * get access to information otherwise not available during normal JavaScript
   * execution e.g. details on stack frames. Receiver of the function call will
   * be the debugger context global object, however this is a subject to change.
   * The following example shows a JavaScript function which when passed to
   * v8::Debug::Call will return the current line of JavaScript execution.
   *
   * \code
   *   function frame_source_line(exec_state) {
   *     return exec_state.frame(0).sourceLine();
   *   }
   * \endcode
   */
   static V8_DEPRECATE_SOON(
       "Use maybe version",
       Local<Value> Call(v8::Local<v8::Function> fun,
                         Local<Value> data = Local<Value>()));
   // TODO(dcarney): data arg should be a MaybeLocal
   static MaybeLocal<Value> Call(Local<Context> context,
                                 v8::Local<v8::Function> fun,
                                 Local<Value> data = Local<Value>());

   /**
    * Returns a mirror object for the given object.
    */
   static V8_DEPRECATE_SOON("Use maybe version",
                            Local<Value> GetMirror(v8::Local<v8::Value> obj));
   static MaybeLocal<Value> GetMirror(Local<Context> context,
                                      v8::Local<v8::Value> obj);

   /**
    * Makes V8 process all pending debug messages.
    *
    * From V8 point of view all debug messages come asynchronously (e.g. from
    * remote debugger) but they all must be handled synchronously: V8 cannot
    * do 2 things at one time so normal script execution must be interrupted
    * for a while.
    *
    * Generally when message arrives V8 may be in one of 3 states:
    * 1. V8 is running script; V8 will automatically interrupt and process all
    * pending messages;
    * 2. V8 is suspended on debug breakpoint; in this state V8 is dedicated
    * to reading and processing debug messages;
    * 3. V8 is not running at all or has called some long-working C++ function;
    * by default it means that processing of all debug messages will be deferred
    * until V8 gets control again; however, embedding application may improve
    * this by manually calling this method.
    *
    * Technically this method in many senses is equivalent to executing empty
    * script:
    * 1. It does nothing except for processing all pending debug messages.
    * 2. It should be invoked with the same precautions and from the same context
    * as V8 script would be invoked from, because:
    *   a. with "evaluate" command it can do whatever normal script can do,
    *   including all native calls;
    *   b. no other thread should call V8 while this method is running
    *   (v8::Locker may be used here).
    *
    * "Evaluate" debug command behavior currently is not specified in scope
    * of this method.
    */
   static void ProcessDebugMessages();

   /**
    * Debugger is running in its own context which is entered while debugger
    * messages are being dispatched. This is an explicit getter for this
    * debugger context. Note that the content of the debugger context is subject
    * to change. The Context exists only when the debugger is active, i.e. at
    * least one DebugEventListener or MessageHandler is set.
    */
   static Local<Context> GetDebugContext();


   /**
    * Enable/disable LiveEdit functionality for the given Isolate
    * (default Isolate if not provided). V8 will abort if LiveEdit is
    * unexpectedly used. LiveEdit is enabled by default.
    */
   static void SetLiveEditEnabled(Isolate* isolate, bool enable);

   /**
    * Returns array of internal properties specific to the value type. Result has
    * the following format: [<name>, <value>,...,<name>, <value>]. Result array
    * will be allocated in the current context.
    */
   static MaybeLocal<Array> GetInternalProperties(Isolate* isolate,
                                                  Local<Value> value);
 };


 }  // namespace v8


 #undef EXPORT


 #endif  // V8_V8_DEBUG_H_
	// Copyright 2008 the V8 project authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.

	#ifndef V8_V8_DEBUG_H_
	#define V8_V8_DEBUG_H_

	#include "v8.h"

	/**
	* Debugger support for the V8 JavaScript engine.
	*/
	namespace v8 {

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


	class V8_EXPORT Debug {
	public:
	/**
	* A client object passed to the v8 debugger whose ownership will be taken by
	* it. v8 is always responsible for deleting the object.
	*/
	class ClientData {
	public:
	virtual ~ClientData() {}
	};


	/**
	* A message object passed to the debug message handler.
	*/
	class Message {
	public:
	/**
	* Check type of message.
	*/
	virtual bool IsEvent() const = 0;
	virtual bool IsResponse() const = 0;
	virtual DebugEvent GetEvent() const = 0;

	/**
	* Indicate whether this is a response to a continue command which will
	* start the VM running after this is processed.
	*/
	virtual bool WillStartRunning() const = 0;

	/**
	* Access to execution state and event data. Don't store these cross
	* callbacks as their content becomes invalid. These objects are from the
	* debugger event that started the debug message loop.
	*/
	virtual Local<Object> GetExecutionState() const = 0;
	virtual Local<Object> GetEventData() const = 0;

	/**
	* Get the debugger protocol JSON.
	*/
	virtual Local<String> GetJSON() const = 0;

	/**
	* Get the context active when the debug event happened. Note this is not
	* the current active context as the JavaScript part of the debugger is
	* running in its own context which is entered at this point.
	*/
	virtual Local<Context> GetEventContext() const = 0;

	/**
	* Client data passed with the corresponding request if any. This is the
	* client_data data value passed into Debug::SendCommand along with the
	* request that led to the message or NULL if the message is an event. The
	* debugger takes ownership of the data and will delete it even if there is
	* no message handler.
	*/
	virtual ClientData* GetClientData() const = 0;

	virtual Isolate* GetIsolate() const = 0;

	virtual ~Message() {}
	};


	/**
	* An event details object passed to the debug event listener.
	*/
	class EventDetails {
	public:
	/**
	* Event type.
	*/
	virtual DebugEvent GetEvent() const = 0;

	/**
	* Access to execution state and event data of the debug event. Don't store
	* these cross callbacks as their content becomes invalid.
	*/
	virtual Local<Object> GetExecutionState() const = 0;
	virtual Local<Object> GetEventData() const = 0;

	/**
	* Get the context active when the debug event happened. Note this is not
	* the current active context as the JavaScript part of the debugger is
	* running in its own context which is entered at this point.
	*/
	virtual Local<Context> GetEventContext() const = 0;

	/**
	* Client data passed with the corresponding callback when it was
	* registered.
	*/
	virtual Local<Value> GetCallbackData() const = 0;

	/**
	* Client data passed to DebugBreakForCommand function. The
	* debugger takes ownership of the data and will delete it even if
	* there is no message handler.
	*/
	virtual ClientData* GetClientData() const = 0;

	virtual ~EventDetails() {}
	};

	/**
	* Debug event callback function.
	*
	* \param event_details object providing information about the debug event
	*
	* A EventCallback2 does not take possession of the event data,
	* and must not rely on the data persisting after the handler returns.
	*/
	typedef void (*EventCallback)(const EventDetails& event_details);

	/**
	* Debug message callback function.
	*
	* \param message the debug message handler message object
	*
	* A MessageHandler2 does not take possession of the message data,
	* and must not rely on the data persisting after the handler returns.
	*/
	typedef void (*MessageHandler)(const Message& message);

	/**
	* Callback function for the host to ensure debug messages are processed.
	*/
	typedef void (*DebugMessageDispatchHandler)();

	static bool SetDebugEventListener(EventCallback that,
	Local<Value> data = Local<Value>());

	// Schedule a debugger break to happen when JavaScript code is run
	// in the given isolate.
	static void DebugBreak(Isolate* isolate);

	// Remove scheduled debugger break in given isolate if it has not
	// happened yet.
	static void CancelDebugBreak(Isolate* isolate);

	// Check if a debugger break is scheduled in the given isolate.
	static bool CheckDebugBreak(Isolate* isolate);

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

	static void SendCommand(Isolate* isolate,
	const uint16_t* command, int length,
	ClientData* client_data = NULL);

	/**
	* Run a JavaScript function in the debugger.
	* \param fun the function to call
	* \param data passed as second argument to the function
	* With this call the debugger is entered and the function specified is called
	* with the execution state as the first argument. This makes it possible to
	* get access to information otherwise not available during normal JavaScript
	* execution e.g. details on stack frames. Receiver of the function call will
	* be the debugger context global object, however this is a subject to change.
	* The following example shows a JavaScript function which when passed to
	* v8::Debug::Call will return the current line of JavaScript execution.
	*
	* \code
	* function frame_source_line(exec_state) {
	* return exec_state.frame(0).sourceLine();
	* }
	* \endcode
	*/
	static V8_DEPRECATE_SOON(
	"Use maybe version",
	Local<Value> Call(v8::Local<v8::Function> fun,
	Local<Value> data = Local<Value>()));
	// TODO(dcarney): data arg should be a MaybeLocal
	static MaybeLocal<Value> Call(Local<Context> context,
	v8::Local<v8::Function> fun,
	Local<Value> data = Local<Value>());

	/**
	* Returns a mirror object for the given object.
	*/
	static V8_DEPRECATE_SOON("Use maybe version",
	Local<Value> GetMirror(v8::Local<v8::Value> obj));
	static MaybeLocal<Value> GetMirror(Local<Context> context,
	v8::Local<v8::Value> obj);

	/**
	* Makes V8 process all pending debug messages.
	*
	* From V8 point of view all debug messages come asynchronously (e.g. from
	* remote debugger) but they all must be handled synchronously: V8 cannot
	* do 2 things at one time so normal script execution must be interrupted
	* for a while.
	*
	* Generally when message arrives V8 may be in one of 3 states:
	* 1. V8 is running script; V8 will automatically interrupt and process all
	* pending messages;
	* 2. V8 is suspended on debug breakpoint; in this state V8 is dedicated
	* to reading and processing debug messages;
	* 3. V8 is not running at all or has called some long-working C++ function;
	* by default it means that processing of all debug messages will be deferred
	* until V8 gets control again; however, embedding application may improve
	* this by manually calling this method.
	*
	* Technically this method in many senses is equivalent to executing empty
	* script:
	* 1. It does nothing except for processing all pending debug messages.
	* 2. It should be invoked with the same precautions and from the same context
	* as V8 script would be invoked from, because:
	* a. with "evaluate" command it can do whatever normal script can do,
	* including all native calls;
	* b. no other thread should call V8 while this method is running
	* (v8::Locker may be used here).
	*
	* "Evaluate" debug command behavior currently is not specified in scope
	* of this method.
	*/
	static void ProcessDebugMessages();

	/**
	* Debugger is running in its own context which is entered while debugger
	* messages are being dispatched. This is an explicit getter for this
	* debugger context. Note that the content of the debugger context is subject
	* to change. The Context exists only when the debugger is active, i.e. at
	* least one DebugEventListener or MessageHandler is set.
	*/
	static Local<Context> GetDebugContext();


	/**
	* Enable/disable LiveEdit functionality for the given Isolate
	* (default Isolate if not provided). V8 will abort if LiveEdit is
	* unexpectedly used. LiveEdit is enabled by default.
	*/
	static void SetLiveEditEnabled(Isolate* isolate, bool enable);

	/**
	* Returns array of internal properties specific to the value type. Result has
	* the following format: [<name>, <value>,...,<name>, <value>]. Result array
	* will be allocated in the current context.
	*/
	static MaybeLocal<Array> GetInternalProperties(Isolate* isolate,
	Local<Value> value);
	};


	} // namespace v8


	#undef EXPORT


	#endif // V8_V8_DEBUG_H_