The C and C++ Include Header Files

/usr/include/nodejs/deps/v8/include/v8-inspector.h


$ cat -n /usr/include/nodejs/deps/v8/include/v8-inspector.h

     1	// Copyright 2016 the V8 project authors. All rights reserved.
     2	// Use of this source code is governed by a BSD-style license that can be
     3	// found in the LICENSE file.
     4	
     5	#ifndef V8_V8_INSPECTOR_H_
     6	#define V8_V8_INSPECTOR_H_
     7	
     8	#include <stdint.h>
     9	
    10	#include <cctype>
    11	#include <memory>
    12	
    13	#include "v8-isolate.h"       // NOLINT(build/include_directory)
    14	#include "v8-local-handle.h"  // NOLINT(build/include_directory)
    15	
    16	namespace v8 {
    17	class Context;
    18	class Name;
    19	class Object;
    20	class StackTrace;
    21	class Value;
    22	}  // namespace v8
    23	
    24	namespace v8_inspector {
    25	
    26	namespace internal {
    27	class V8DebuggerId;
    28	}  // namespace internal
    29	
    30	namespace protocol {
    31	namespace Debugger {
    32	namespace API {
    33	class SearchMatch;
    34	}
    35	}
    36	namespace Runtime {
    37	namespace API {
    38	class RemoteObject;
    39	class StackTrace;
    40	class StackTraceId;
    41	}
    42	}
    43	namespace Schema {
    44	namespace API {
    45	class Domain;
    46	}
    47	}
    48	}  // namespace protocol
    49	
    50	class V8_EXPORT StringView {
    51	 public:
    52	  StringView() : m_is8Bit(true), m_length(0), m_characters8(nullptr) {}
    53	
    54	  StringView(const uint8_t* characters, size_t length)
    55	      : m_is8Bit(true), m_length(length), m_characters8(characters) {}
    56	
    57	  StringView(const uint16_t* characters, size_t length)
    58	      : m_is8Bit(false), m_length(length), m_characters16(characters) {}
    59	
    60	  bool is8Bit() const { return m_is8Bit; }
    61	  size_t length() const { return m_length; }
    62	
    63	  // TODO(dgozman): add DCHECK(m_is8Bit) to accessors once platform can be used
    64	  // here.
    65	  const uint8_t* characters8() const { return m_characters8; }
    66	  const uint16_t* characters16() const { return m_characters16; }
    67	
    68	 private:
    69	  bool m_is8Bit;
    70	  size_t m_length;
    71	  union {
    72	    const uint8_t* m_characters8;
    73	    const uint16_t* m_characters16;
    74	  };
    75	};
    76	
    77	class V8_EXPORT StringBuffer {
    78	 public:
    79	  virtual ~StringBuffer() = default;
    80	  virtual StringView string() const = 0;
    81	  // This method copies contents.
    82	  static std::unique_ptr<StringBuffer> create(StringView);
    83	};
    84	
    85	class V8_EXPORT V8ContextInfo {
    86	 public:
    87	  V8ContextInfo(v8::Local<v8::Context> context, int contextGroupId,
    88	                StringView humanReadableName)
    89	      : context(context),
    90	        contextGroupId(contextGroupId),
    91	        humanReadableName(humanReadableName),
    92	        hasMemoryOnConsole(false) {}
    93	
    94	  v8::Local<v8::Context> context;
    95	  // Each v8::Context is a part of a group. The group id must be non-zero.
    96	  int contextGroupId;
    97	  StringView humanReadableName;
    98	  StringView origin;
    99	  StringView auxData;
   100	  bool hasMemoryOnConsole;
   101	
   102	  static int executionContextId(v8::Local<v8::Context> context);
   103	
   104	  // Disallow copying and allocating this one.
   105	  enum NotNullTagEnum { NotNullLiteral };
   106	  void* operator new(size_t) = delete;
   107	  void* operator new(size_t, NotNullTagEnum, void*) = delete;
   108	  void* operator new(size_t, void*) = delete;
   109	  V8ContextInfo(const V8ContextInfo&) = delete;
   110	  V8ContextInfo& operator=(const V8ContextInfo&) = delete;
   111	};
   112	
   113	// This debugger id tries to be unique by generating two random
   114	// numbers, which should most likely avoid collisions.
   115	// Debugger id has a 1:1 mapping to context group. It is used to
   116	// attribute stack traces to a particular debugging, when doing any
   117	// cross-debugger operations (e.g. async step in).
   118	// See also Runtime.UniqueDebuggerId in the protocol.
   119	class V8_EXPORT V8DebuggerId {
   120	 public:
   121	  V8DebuggerId() = default;
   122	  V8DebuggerId(const V8DebuggerId&) = default;
   123	  V8DebuggerId& operator=(const V8DebuggerId&) = default;
   124	
   125	  std::unique_ptr<StringBuffer> toString() const;
   126	  bool isValid() const;
   127	  std::pair<int64_t, int64_t> pair() const;
   128	
   129	 private:
   130	  friend class internal::V8DebuggerId;
   131	  explicit V8DebuggerId(std::pair<int64_t, int64_t>);
   132	
   133	  int64_t m_first = 0;
   134	  int64_t m_second = 0;
   135	};
   136	
   137	class V8_EXPORT V8StackTrace {
   138	 public:
   139	  virtual StringView firstNonEmptySourceURL() const = 0;
   140	  virtual bool isEmpty() const = 0;
   141	  virtual StringView topSourceURL() const = 0;
   142	  virtual int topLineNumber() const = 0;
   143	  virtual int topColumnNumber() const = 0;
   144	  virtual int topScriptId() const = 0;
   145	  virtual StringView topFunctionName() const = 0;
   146	
   147	  virtual ~V8StackTrace() = default;
   148	  virtual std::unique_ptr<protocol::Runtime::API::StackTrace>
   149	  buildInspectorObject(int maxAsyncDepth) const = 0;
   150	  virtual std::unique_ptr<StringBuffer> toString() const = 0;
   151	
   152	  // Safe to pass between threads, drops async chain.
   153	  virtual std::unique_ptr<V8StackTrace> clone() = 0;
   154	};
   155	
   156	class V8_EXPORT V8InspectorSession {
   157	 public:
   158	  virtual ~V8InspectorSession() = default;
   159	
   160	  // Cross-context inspectable values (DOM nodes in different worlds, etc.).
   161	  class V8_EXPORT Inspectable {
   162	   public:
   163	    virtual v8::Local<v8::Value> get(v8::Local<v8::Context>) = 0;
   164	    virtual ~Inspectable() = default;
   165	  };
   166	  class V8_EXPORT CommandLineAPIScope {
   167	   public:
   168	    virtual ~CommandLineAPIScope() = default;
   169	  };
   170	  virtual void addInspectedObject(std::unique_ptr<Inspectable>) = 0;
   171	
   172	  // Dispatching protocol messages.
   173	  static bool canDispatchMethod(StringView method);
   174	  virtual void dispatchProtocolMessage(StringView message) = 0;
   175	  virtual std::vector<uint8_t> state() = 0;
   176	  virtual std::vector<std::unique_ptr<protocol::Schema::API::Domain>>
   177	  supportedDomains() = 0;
   178	
   179	  virtual std::unique_ptr<V8InspectorSession::CommandLineAPIScope>
   180	  initializeCommandLineAPIScope(int executionContextId) = 0;
   181	
   182	  // Debugger actions.
   183	  virtual void schedulePauseOnNextStatement(StringView breakReason,
   184	                                            StringView breakDetails) = 0;
   185	  virtual void cancelPauseOnNextStatement() = 0;
   186	  virtual void breakProgram(StringView breakReason,
   187	                            StringView breakDetails) = 0;
   188	  virtual void setSkipAllPauses(bool) = 0;
   189	  virtual void resume(bool setTerminateOnResume = false) = 0;
   190	  virtual void stepOver() = 0;
   191	  virtual std::vector<std::unique_ptr<protocol::Debugger::API::SearchMatch>>
   192	  searchInTextByLines(StringView text, StringView query, bool caseSensitive,
   193	                      bool isRegex) = 0;
   194	
   195	  // Remote objects.
   196	  virtual std::unique_ptr<protocol::Runtime::API::RemoteObject> wrapObject(
   197	      v8::Local<v8::Context>, v8::Local<v8::Value>, StringView groupName,
   198	      bool generatePreview) = 0;
   199	
   200	  virtual bool unwrapObject(std::unique_ptr<StringBuffer>* error,
   201	                            StringView objectId, v8::Local<v8::Value>*,
   202	                            v8::Local<v8::Context>*,
   203	                            std::unique_ptr<StringBuffer>* objectGroup) = 0;
   204	  virtual void releaseObjectGroup(StringView) = 0;
   205	  virtual void triggerPreciseCoverageDeltaUpdate(StringView occasion) = 0;
   206	};
   207	
   208	class V8_EXPORT WebDriverValue {
   209	 public:
   210	  explicit WebDriverValue(StringView type, v8::MaybeLocal<v8::Value> value = {})
   211	      : type(type), value(value) {}
   212	
   213	  StringView type;
   214	  v8::MaybeLocal<v8::Value> value;
   215	};
   216	
   217	class V8_EXPORT V8InspectorClient {
   218	 public:
   219	  virtual ~V8InspectorClient() = default;
   220	
   221	  virtual void runMessageLoopOnPause(int contextGroupId) {}
   222	  virtual void quitMessageLoopOnPause() {}
   223	  virtual void runIfWaitingForDebugger(int contextGroupId) {}
   224	
   225	  virtual void muteMetrics(int contextGroupId) {}
   226	  virtual void unmuteMetrics(int contextGroupId) {}
   227	
   228	  virtual void beginUserGesture() {}
   229	  virtual void endUserGesture() {}
   230	
   231	  virtual std::unique_ptr<WebDriverValue> serializeToWebDriverValue(
   232	      v8::Local<v8::Value> v8_value, int max_depth) {
   233	    return nullptr;
   234	  }
   235	  virtual std::unique_ptr<StringBuffer> valueSubtype(v8::Local<v8::Value>) {
   236	    return nullptr;
   237	  }
   238	  virtual std::unique_ptr<StringBuffer> descriptionForValueSubtype(
   239	      v8::Local<v8::Context>, v8::Local<v8::Value>) {
   240	    return nullptr;
   241	  }
   242	  virtual bool isInspectableHeapObject(v8::Local<v8::Object>) { return true; }
   243	
   244	  virtual v8::Local<v8::Context> ensureDefaultContextInGroup(
   245	      int contextGroupId) {
   246	    return v8::Local<v8::Context>();
   247	  }
   248	  virtual void beginEnsureAllContextsInGroup(int contextGroupId) {}
   249	  virtual void endEnsureAllContextsInGroup(int contextGroupId) {}
   250	
   251	  virtual void installAdditionalCommandLineAPI(v8::Local<v8::Context>,
   252	                                               v8::Local<v8::Object>) {}
   253	  virtual void consoleAPIMessage(int contextGroupId,
   254	                                 v8::Isolate::MessageErrorLevel level,
   255	                                 const StringView& message,
   256	                                 const StringView& url, unsigned lineNumber,
   257	                                 unsigned columnNumber, V8StackTrace*) {}
   258	  virtual v8::MaybeLocal<v8::Value> memoryInfo(v8::Isolate*,
   259	                                               v8::Local<v8::Context>) {
   260	    return v8::MaybeLocal<v8::Value>();
   261	  }
   262	
   263	  virtual void consoleTime(const StringView& title) {}
   264	  virtual void consoleTimeEnd(const StringView& title) {}
   265	  virtual void consoleTimeStamp(const StringView& title) {}
   266	  virtual void consoleClear(int contextGroupId) {}
   267	  virtual double currentTimeMS() { return 0; }
   268	  typedef void (*TimerCallback)(void*);
   269	  virtual void startRepeatingTimer(double, TimerCallback, void* data) {}
   270	  virtual void cancelTimer(void* data) {}
   271	
   272	  // TODO(dgozman): this was added to support service worker shadow page. We
   273	  // should not connect at all.
   274	  virtual bool canExecuteScripts(int contextGroupId) { return true; }
   275	
   276	  virtual void maxAsyncCallStackDepthChanged(int depth) {}
   277	
   278	  virtual std::unique_ptr<StringBuffer> resourceNameToUrl(
   279	      const StringView& resourceName) {
   280	    return nullptr;
   281	  }
   282	
   283	  // The caller would defer to generating a random 64 bit integer if
   284	  // this method returns 0.
   285	  virtual int64_t generateUniqueId() { return 0; }
   286	
   287	  virtual void dispatchError(v8::Local<v8::Context>, v8::Local<v8::Message>,
   288	                             v8::Local<v8::Value>) {}
   289	};
   290	
   291	// These stack trace ids are intended to be passed between debuggers and be
   292	// resolved later. This allows to track cross-debugger calls and step between
   293	// them if a single client connects to multiple debuggers.
   294	struct V8_EXPORT V8StackTraceId {
   295	  uintptr_t id;
   296	  std::pair<int64_t, int64_t> debugger_id;
   297	  bool should_pause = false;
   298	
   299	  V8StackTraceId();
   300	  V8StackTraceId(const V8StackTraceId&) = default;
   301	  V8StackTraceId(uintptr_t id, const std::pair<int64_t, int64_t> debugger_id);
   302	  V8StackTraceId(uintptr_t id, const std::pair<int64_t, int64_t> debugger_id,
   303	                 bool should_pause);
   304	  explicit V8StackTraceId(StringView);
   305	  V8StackTraceId& operator=(const V8StackTraceId&) = default;
   306	  V8StackTraceId& operator=(V8StackTraceId&&) noexcept = default;
   307	  ~V8StackTraceId() = default;
   308	
   309	  bool IsInvalid() const;
   310	  std::unique_ptr<StringBuffer> ToString();
   311	};
   312	
   313	class V8_EXPORT V8Inspector {
   314	 public:
   315	  static std::unique_ptr<V8Inspector> create(v8::Isolate*, V8InspectorClient*);
   316	  virtual ~V8Inspector() = default;
   317	
   318	  // Contexts instrumentation.
   319	  virtual void contextCreated(const V8ContextInfo&) = 0;
   320	  virtual void contextDestroyed(v8::Local<v8::Context>) = 0;
   321	  virtual void resetContextGroup(int contextGroupId) = 0;
   322	  virtual v8::MaybeLocal<v8::Context> contextById(int contextId) = 0;
   323	  virtual V8DebuggerId uniqueDebuggerId(int contextId) = 0;
   324	
   325	  // Various instrumentation.
   326	  virtual void idleStarted() = 0;
   327	  virtual void idleFinished() = 0;
   328	
   329	  // Async stack traces instrumentation.
   330	  virtual void asyncTaskScheduled(StringView taskName, void* task,
   331	                                  bool recurring) = 0;
   332	  virtual void asyncTaskCanceled(void* task) = 0;
   333	  virtual void asyncTaskStarted(void* task) = 0;
   334	  virtual void asyncTaskFinished(void* task) = 0;
   335	  virtual void allAsyncTasksCanceled() = 0;
   336	
   337	  virtual V8StackTraceId storeCurrentStackTrace(StringView description) = 0;
   338	  virtual void externalAsyncTaskStarted(const V8StackTraceId& parent) = 0;
   339	  virtual void externalAsyncTaskFinished(const V8StackTraceId& parent) = 0;
   340	
   341	  // Exceptions instrumentation.
   342	  virtual unsigned exceptionThrown(v8::Local<v8::Context>, StringView message,
   343	                                   v8::Local<v8::Value> exception,
   344	                                   StringView detailedMessage, StringView url,
   345	                                   unsigned lineNumber, unsigned columnNumber,
   346	                                   std::unique_ptr<V8StackTrace>,
   347	                                   int scriptId) = 0;
   348	  virtual void exceptionRevoked(v8::Local<v8::Context>, unsigned exceptionId,
   349	                                StringView message) = 0;
   350	  virtual bool associateExceptionData(v8::Local<v8::Context>,
   351	                                      v8::Local<v8::Value> exception,
   352	                                      v8::Local<v8::Name> key,
   353	                                      v8::Local<v8::Value> value) = 0;
   354	
   355	  // Connection.
   356	  class V8_EXPORT Channel {
   357	   public:
   358	    virtual ~Channel() = default;
   359	    virtual void sendResponse(int callId,
   360	                              std::unique_ptr<StringBuffer> message) = 0;
   361	    virtual void sendNotification(std::unique_ptr<StringBuffer> message) = 0;
   362	    virtual void flushProtocolNotifications() = 0;
   363	  };
   364	  virtual std::unique_ptr<V8InspectorSession> connect(int contextGroupId,
   365	                                                      Channel*,
   366	                                                      StringView state) = 0;
   367	
   368	  // API methods.
   369	  virtual std::unique_ptr<V8StackTrace> createStackTrace(
   370	      v8::Local<v8::StackTrace>) = 0;
   371	  virtual std::unique_ptr<V8StackTrace> captureStackTrace(bool fullStack) = 0;
   372	};
   373	
   374	}  // namespace v8_inspector
   375	
   376	#endif  // V8_V8_INSPECTOR_H_