/src/node/deps/v8/include/v8-debug.h

Source
// Copyright 2021 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 INCLUDE_V8_DEBUG_H_
#define INCLUDE_V8_DEBUG_H_

#include <stdint.h>

#include "v8-script.h"  // NOLINT(build/include_directory)
#include "v8config.h"   // NOLINT(build/include_directory)

namespace v8 {

class Isolate;
class String;

/**
 * A single JavaScript stack frame.
 */
class V8_EXPORT StackFrame {
 public:
  /**
   * Returns the source location, 0-based, for the associated function call.
   */
  Location GetLocation() const;

  /**
   * Returns the number, 1-based, of the line for the associate function call.
   * This method will return Message::kNoLineNumberInfo if it is unable to
   * retrieve the line number, or if kLineNumber was not passed as an option
   * when capturing the StackTrace.
   */
  int GetLineNumber() const { return GetLocation().GetLineNumber() + 1; }

  /**
   * Returns the 1-based column offset on the line for the associated function
   * call.
   * This method will return Message::kNoColumnInfo if it is unable to retrieve
   * the column number, or if kColumnOffset was not passed as an option when
   * capturing the StackTrace.
   */
  int GetColumn() const { return GetLocation().GetColumnNumber() + 1; }

  /**
   * Returns zero based source position (character offset) for the associated
   * function.
   */
  int GetSourcePosition() const;

  /**
   * Returns the id of the script for the function for this StackFrame.
   * This method will return Message::kNoScriptIdInfo if it is unable to
   * retrieve the script id, or if kScriptId was not passed as an option when
   * capturing the StackTrace.
   */
  int GetScriptId() const;

  /**
   * Returns the name of the resource that contains the script for the
   * function for this StackFrame.
   */
  Local<String> GetScriptName() const;

  /**
   * Returns the name of the resource that contains the script for the
   * function for this StackFrame or sourceURL value if the script name
   * is undefined and its source ends with //# sourceURL=... string or
   * deprecated //@ sourceURL=... string.
   */
  Local<String> GetScriptNameOrSourceURL() const;

  /**
   * Returns the source of the script for the function for this StackFrame.
   */
  Local<String> GetScriptSource() const;

  /**
   * Returns the source mapping URL (if one is present) of the script for
   * the function for this StackFrame.
   */
  Local<String> GetScriptSourceMappingURL() const;

  /**
   * Returns the name of the function associated with this stack frame.
   */
  Local<String> GetFunctionName() const;

  /**
   * Returns whether or not the associated function is compiled via a call to
   * eval().
   */
  bool IsEval() const;

  /**
   * Returns whether or not the associated function is called as a
   * constructor via "new".
   */
  bool IsConstructor() const;

  /**
   * Returns whether or not the associated functions is defined in wasm.
   */
  bool IsWasm() const;

  /**
   * Returns whether or not the associated function is defined by the user.
   */
  bool IsUserJavaScript() const;
};

/**
 * Representation of a JavaScript stack trace. The information collected is a
 * snapshot of the execution stack and the information remains valid after
 * execution continues.
 */
class V8_EXPORT StackTrace {
 public:
  /**
   * Flags that determine what information is placed captured for each
   * StackFrame when grabbing the current stack trace.
   * Note: these options are deprecated and we always collect all available
   * information (kDetailed).
   */
  enum StackTraceOptions {
    kLineNumber = 1,
    kColumnOffset = 1 << 1 | kLineNumber,
    kScriptName = 1 << 2,
    kFunctionName = 1 << 3,
    kIsEval = 1 << 4,
    kIsConstructor = 1 << 5,
    kScriptNameOrSourceURL = 1 << 6,
    kScriptId = 1 << 7,
    kExposeFramesAcrossSecurityOrigins = 1 << 8,
    kOverview = kLineNumber | kColumnOffset | kScriptName | kFunctionName,
    kDetailed = kOverview | kIsEval | kIsConstructor | kScriptNameOrSourceURL
  };

  /**
   * Returns the (unique) ID of this stack trace.
   */
  int GetID() const;

  /**
   * Returns a StackFrame at a particular index.
   */
  Local<StackFrame> GetFrame(Isolate* isolate, uint32_t index) const;

  /**
   * Returns the number of StackFrames.
   */
  int GetFrameCount() const;

  /**
   * Grab a snapshot of the current JavaScript execution stack.
   *
   * \param frame_limit The maximum number of stack frames we want to capture.
   * \param options Enumerates the set of things we will capture for each
   *   StackFrame.
   */
  static Local<StackTrace> CurrentStackTrace(
      Isolate* isolate, int frame_limit, StackTraceOptions options = kDetailed);

  /**
   * Returns the first valid script name or source URL starting at the top of
   * the JS stack. The returned string is either an empty handle if no script
   * name/url was found or a non-zero-length string.
   *
   * This method is equivalent to calling StackTrace::CurrentStackTrace and
   * walking the resulting frames from the beginning until a non-empty script
   * name/url is found. The difference is that this method won't allocate
   * a stack trace.
   */
  static Local<String> CurrentScriptNameOrSourceURL(Isolate* isolate);

  /**
   * Returns the first valid script id at the top of
   * the JS stack. The returned value is Message::kNoScriptIdInfo if no id
   * was found.
   *
   * This method is equivalent to calling StackTrace::CurrentStackTrace and
   * walking the resulting frames from the beginning until a non-empty id is
   * found. The difference is that this method won't allocate a stack trace.
   */
  static int CurrentScriptId(Isolate* isolate);
};

}  // namespace v8

#endif  // INCLUDE_V8_DEBUG_H_

Line	Count	Source
1		// Copyright 2021 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 INCLUDE_V8_DEBUG_H_
6		#define INCLUDE_V8_DEBUG_H_
7
8		#include <stdint.h>
9
10		#include "v8-script.h" // NOLINT(build/include_directory)
11		#include "v8config.h" // NOLINT(build/include_directory)
12
13		namespace v8 {
14
15		class Isolate;
16		class String;
17
18		/**
19		* A single JavaScript stack frame.
20		*/
21		class V8_EXPORT StackFrame {
22		public:
23		/**
24		* Returns the source location, 0-based, for the associated function call.
25		*/
26		Location GetLocation() const;
27
28		/**
29		* Returns the number, 1-based, of the line for the associate function call.
30		* This method will return Message::kNoLineNumberInfo if it is unable to
31		* retrieve the line number, or if kLineNumber was not passed as an option
32		* when capturing the StackTrace.
33		*/
34	0	int GetLineNumber() const { return GetLocation().GetLineNumber() + 1; }
35
36		/**
37		* Returns the 1-based column offset on the line for the associated function
38		* call.
39		* This method will return Message::kNoColumnInfo if it is unable to retrieve
40		* the column number, or if kColumnOffset was not passed as an option when
41		* capturing the StackTrace.
42		*/
43	0	int GetColumn() const { return GetLocation().GetColumnNumber() + 1; }
44
45		/**
46		* Returns zero based source position (character offset) for the associated
47		* function.
48		*/
49		int GetSourcePosition() const;
50
51		/**
52		* Returns the id of the script for the function for this StackFrame.
53		* This method will return Message::kNoScriptIdInfo if it is unable to
54		* retrieve the script id, or if kScriptId was not passed as an option when
55		* capturing the StackTrace.
56		*/
57		int GetScriptId() const;
58
59		/**
60		* Returns the name of the resource that contains the script for the
61		* function for this StackFrame.
62		*/
63		Local<String> GetScriptName() const;
64
65		/**
66		* Returns the name of the resource that contains the script for the
67		* function for this StackFrame or sourceURL value if the script name
68		* is undefined and its source ends with //# sourceURL=... string or
69		* deprecated //@ sourceURL=... string.
70		*/
71		Local<String> GetScriptNameOrSourceURL() const;
72
73		/**
74		* Returns the source of the script for the function for this StackFrame.
75		*/
76		Local<String> GetScriptSource() const;
77
78		/**
79		* Returns the source mapping URL (if one is present) of the script for
80		* the function for this StackFrame.
81		*/
82		Local<String> GetScriptSourceMappingURL() const;
83
84		/**
85		* Returns the name of the function associated with this stack frame.
86		*/
87		Local<String> GetFunctionName() const;
88
89		/**
90		* Returns whether or not the associated function is compiled via a call to
91		* eval().
92		*/
93		bool IsEval() const;
94
95		/**
96		* Returns whether or not the associated function is called as a
97		* constructor via "new".
98		*/
99		bool IsConstructor() const;
100
101		/**
102		* Returns whether or not the associated functions is defined in wasm.
103		*/
104		bool IsWasm() const;
105
106		/**
107		* Returns whether or not the associated function is defined by the user.
108		*/
109		bool IsUserJavaScript() const;
110		};
111
112		/**
113		* Representation of a JavaScript stack trace. The information collected is a
114		* snapshot of the execution stack and the information remains valid after
115		* execution continues.
116		*/
117		class V8_EXPORT StackTrace {
118		public:
119		/**
120		* Flags that determine what information is placed captured for each
121		* StackFrame when grabbing the current stack trace.
122		* Note: these options are deprecated and we always collect all available
123		* information (kDetailed).
124		*/
125		enum StackTraceOptions {
126		kLineNumber = 1,
127		kColumnOffset = 1 << 1 \| kLineNumber,
128		kScriptName = 1 << 2,
129		kFunctionName = 1 << 3,
130		kIsEval = 1 << 4,
131		kIsConstructor = 1 << 5,
132		kScriptNameOrSourceURL = 1 << 6,
133		kScriptId = 1 << 7,
134		kExposeFramesAcrossSecurityOrigins = 1 << 8,
135		kOverview = kLineNumber \| kColumnOffset \| kScriptName \| kFunctionName,
136		kDetailed = kOverview \| kIsEval \| kIsConstructor \| kScriptNameOrSourceURL
137		};
138
139		/**
140		* Returns the (unique) ID of this stack trace.
141		*/
142		int GetID() const;
143
144		/**
145		* Returns a StackFrame at a particular index.
146		*/
147		Local<StackFrame> GetFrame(Isolate* isolate, uint32_t index) const;
148
149		/**
150		* Returns the number of StackFrames.
151		*/
152		int GetFrameCount() const;
153
154		/**
155		* Grab a snapshot of the current JavaScript execution stack.
156		*
157		* \param frame_limit The maximum number of stack frames we want to capture.
158		* \param options Enumerates the set of things we will capture for each
159		* StackFrame.
160		*/
161		static Local<StackTrace> CurrentStackTrace(
162		Isolate* isolate, int frame_limit, StackTraceOptions options = kDetailed);
163
164		/**
165		* Returns the first valid script name or source URL starting at the top of
166		* the JS stack. The returned string is either an empty handle if no script
167		* name/url was found or a non-zero-length string.
168		*
169		* This method is equivalent to calling StackTrace::CurrentStackTrace and
170		* walking the resulting frames from the beginning until a non-empty script
171		* name/url is found. The difference is that this method won't allocate
172		* a stack trace.
173		*/
174		static Local<String> CurrentScriptNameOrSourceURL(Isolate* isolate);
175
176		/**
177		* Returns the first valid script id at the top of
178		* the JS stack. The returned value is Message::kNoScriptIdInfo if no id
179		* was found.
180		*
181		* This method is equivalent to calling StackTrace::CurrentStackTrace and
182		* walking the resulting frames from the beginning until a non-empty id is
183		* found. The difference is that this method won't allocate a stack trace.
184		*/
185		static int CurrentScriptId(Isolate* isolate);
186		};
187
188		} // namespace v8
189
190		#endif // INCLUDE_V8_DEBUG_H_

Coverage Report

Created: 2025-12-30 08:42