37394eb3b0
Since the generic GetCallingContext is deprecated, but there's still the use case for the debugger to get the currently debugged context while in the debug context, add a convenience API for it. Note that EventDetails already exposes this context, but the embedder might not necessarily have the EventDetails around. R=verwaest@chromium.org BUG= Review-Url: https://codereview.chromium.org/2040853003 Cr-Commit-Position: refs/heads/master@{#36751}
302 lines
10 KiB
C++
302 lines
10 KiB
C++
// 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" // NOLINT(build/include)
|
|
|
|
/**
|
|
* 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,
|
|
AsyncTaskEvent = 7,
|
|
};
|
|
|
|
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 Isolate* GetIsolate() 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(Isolate* isolate, EventCallback that,
|
|
Local<Value> data = Local<Value>());
|
|
V8_DEPRECATED("Use version with an Isolate",
|
|
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(Isolate* isolate, MessageHandler handler);
|
|
V8_DEPRECATED("Use version with an Isolate",
|
|
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_DEPRECATED("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_DEPRECATED("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(Isolate* isolate);
|
|
V8_DEPRECATED("Use version with an Isolate",
|
|
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(Isolate* isolate);
|
|
V8_DEPRECATED("Use version with an Isolate",
|
|
static Local<Context> GetDebugContext());
|
|
|
|
/**
|
|
* While in the debug context, this method returns the top-most non-debug
|
|
* context, if it exists.
|
|
*/
|
|
static MaybeLocal<Context> GetDebuggedContext(Isolate* isolate);
|
|
|
|
/**
|
|
* 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);
|
|
|
|
/**
|
|
* Defines if the ES2015 tail call elimination feature is enabled or not.
|
|
* The change of this flag triggers deoptimization of all functions that
|
|
* contain calls at tail position.
|
|
*/
|
|
static bool IsTailCallEliminationEnabled(Isolate* isolate);
|
|
static void SetTailCallEliminationEnabled(Isolate* isolate, bool enabled);
|
|
};
|
|
|
|
|
|
} // namespace v8
|
|
|
|
|
|
#undef EXPORT
|
|
|
|
|
|
#endif // V8_V8_DEBUG_H_
|