v8-debug.h 8.42 KB
Newer Older
1
// Copyright 2008 the V8 project authors. All rights reserved.
2 3
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
4

5 6
#ifndef V8_V8_DEBUG_H_
#define V8_V8_DEBUG_H_
7

8
#include "v8.h"  // NOLINT(build/include)
9 10

/**
11 12 13
 * ATTENTION: The debugger API exposed by this file is deprecated and will be
 *            removed by the end of 2017. Please use the V8 inspector declared
 *            in include/v8-inspector.h instead.
14 15 16
 */
namespace v8 {

17
// Debug events which can occur in the V8 JavaScript engine.
18 19 20
enum DebugEvent {
  Break = 1,
  Exception = 2,
21 22 23
  AfterCompile = 3,
  CompileError = 4,
  AsyncTaskEvent = 5,
24 25
};

26
class V8_EXPORT Debug {
27
 public:
28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89
  /**
   * 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() {}
  };

90 91 92 93 94 95 96 97 98 99 100 101 102 103
  /**
   * 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.
     */
104 105
    virtual Local<Object> GetExecutionState() const = 0;
    virtual Local<Object> GetEventData() const = 0;
106 107 108 109

    /**
     * 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
110
     * running in its own context which is entered at this point.
111
     */
112
    virtual Local<Context> GetEventContext() const = 0;
113 114

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

120
    /**
121
     * This is now a dummy that returns nullptr.
122 123 124
     */
    virtual ClientData* GetClientData() const = 0;

125 126
    virtual Isolate* GetIsolate() const = 0;

127 128 129 130 131 132 133 134
    virtual ~EventDetails() {}
  };

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

140
  /**
141
   * This is now a no-op.
142 143 144
   */
  typedef void (*MessageHandler)(const Message& message);

145 146 147
  V8_DEPRECATED("No longer supported", static bool SetDebugEventListener(
                                           Isolate* isolate, EventCallback that,
                                           Local<Value> data = Local<Value>()));
148

149
  // Schedule a debugger break to happen when JavaScript code is run
150
  // in the given isolate.
151 152
  V8_DEPRECATED("No longer supported",
                static void DebugBreak(Isolate* isolate));
153 154

  // Remove scheduled debugger break in given isolate if it has not
155
  // happened yet.
156 157
  V8_DEPRECATED("No longer supported",
                static void CancelDebugBreak(Isolate* isolate));
158

159
  // Check if a debugger break is scheduled in the given isolate.
160 161
  V8_DEPRECATED("No longer supported",
                static bool CheckDebugBreak(Isolate* isolate));
162

163
  // This is now a no-op.
164 165 166 167
  V8_DEPRECATED("No longer supported",
                static void SetMessageHandler(Isolate* isolate,
                                              MessageHandler handler));

168
  // This is now a no-op.
169 170 171 172 173
  V8_DEPRECATED("No longer supported",
                static void SendCommand(Isolate* isolate,
                                        const uint16_t* command, int length,
                                        ClientData* client_data = NULL));

174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191
  /**
   * 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
   */
192 193 194 195
  V8_DEPRECATED("No longer supported",
                static MaybeLocal<Value> Call(
                    Local<Context> context, v8::Local<v8::Function> fun,
                    Local<Value> data = Local<Value>()));
196

197
  // This is now a no-op.
198 199 200
  V8_DEPRECATED("No longer supported",
                static void ProcessDebugMessages(Isolate* isolate));

201
  /**
202
   * Debugger is running in its own context which is entered while debugger
203 204
   * messages are being dispatched. This is an explicit getter for this
   * debugger context. Note that the content of the debugger context is subject
205 206
   * to change. The Context exists only when the debugger is active, i.e. at
   * least one DebugEventListener or MessageHandler is set.
207
   */
208 209
  V8_DEPRECATED("Use v8-inspector",
                static Local<Context> GetDebugContext(Isolate* isolate));
210

211 212 213 214
  /**
   * While in the debug context, this method returns the top-most non-debug
   * context, if it exists.
   */
215 216 217
  V8_DEPRECATED(
      "No longer supported",
      static MaybeLocal<Context> GetDebuggedContext(Isolate* isolate));
218 219 220 221 222 223

  /**
   * 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.
   */
224 225
  V8_DEPRECATED("No longer supported",
                static void SetLiveEditEnabled(Isolate* isolate, bool enable));
226 227 228 229 230 231

  /**
   * 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.
   */
232 233 234
  V8_DEPRECATED("No longer supported",
                static MaybeLocal<Array> GetInternalProperties(
                    Isolate* isolate, Local<Value> value));
235 236 237 238 239 240

  /**
   * 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.
   */
241 242 243 244 245
  V8_DEPRECATED("No longer supported",
                static bool IsTailCallEliminationEnabled(Isolate* isolate));
  V8_DEPRECATED("No longer supported",
                static void SetTailCallEliminationEnabled(Isolate* isolate,
                                                          bool enabled));
246 247 248 249 250 251 252 253 254
};


}  // namespace v8


#undef EXPORT


255
#endif  // V8_V8_DEBUG_H_