Coverage Report

Created: 2025-07-04 09:33

/src/node/deps/v8/include/v8-debug.h
Line
Count
Source (jump to first uncovered line)
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 the id of the script for the function for this StackFrame.
47
   * This method will return Message::kNoScriptIdInfo if it is unable to
48
   * retrieve the script id, or if kScriptId was not passed as an option when
49
   * capturing the StackTrace.
50
   */
51
  int GetScriptId() const;
52
53
  /**
54
   * Returns the name of the resource that contains the script for the
55
   * function for this StackFrame.
56
   */
57
  Local<String> GetScriptName() const;
58
59
  /**
60
   * Returns the name of the resource that contains the script for the
61
   * function for this StackFrame or sourceURL value if the script name
62
   * is undefined and its source ends with //# sourceURL=... string or
63
   * deprecated //@ sourceURL=... string.
64
   */
65
  Local<String> GetScriptNameOrSourceURL() const;
66
67
  /**
68
   * Returns the source of the script for the function for this StackFrame.
69
   */
70
  Local<String> GetScriptSource() const;
71
72
  /**
73
   * Returns the source mapping URL (if one is present) of the script for
74
   * the function for this StackFrame.
75
   */
76
  Local<String> GetScriptSourceMappingURL() const;
77
78
  /**
79
   * Returns the name of the function associated with this stack frame.
80
   */
81
  Local<String> GetFunctionName() const;
82
83
  /**
84
   * Returns whether or not the associated function is compiled via a call to
85
   * eval().
86
   */
87
  bool IsEval() const;
88
89
  /**
90
   * Returns whether or not the associated function is called as a
91
   * constructor via "new".
92
   */
93
  bool IsConstructor() const;
94
95
  /**
96
   * Returns whether or not the associated functions is defined in wasm.
97
   */
98
  bool IsWasm() const;
99
100
  /**
101
   * Returns whether or not the associated function is defined by the user.
102
   */
103
  bool IsUserJavaScript() const;
104
};
105
106
/**
107
 * Representation of a JavaScript stack trace. The information collected is a
108
 * snapshot of the execution stack and the information remains valid after
109
 * execution continues.
110
 */
111
class V8_EXPORT StackTrace {
112
 public:
113
  /**
114
   * Flags that determine what information is placed captured for each
115
   * StackFrame when grabbing the current stack trace.
116
   * Note: these options are deprecated and we always collect all available
117
   * information (kDetailed).
118
   */
119
  enum StackTraceOptions {
120
    kLineNumber = 1,
121
    kColumnOffset = 1 << 1 | kLineNumber,
122
    kScriptName = 1 << 2,
123
    kFunctionName = 1 << 3,
124
    kIsEval = 1 << 4,
125
    kIsConstructor = 1 << 5,
126
    kScriptNameOrSourceURL = 1 << 6,
127
    kScriptId = 1 << 7,
128
    kExposeFramesAcrossSecurityOrigins = 1 << 8,
129
    kOverview = kLineNumber | kColumnOffset | kScriptName | kFunctionName,
130
    kDetailed = kOverview | kIsEval | kIsConstructor | kScriptNameOrSourceURL
131
  };
132
133
  /**
134
   * Returns a StackFrame at a particular index.
135
   */
136
  Local<StackFrame> GetFrame(Isolate* isolate, uint32_t index) const;
137
138
  /**
139
   * Returns the number of StackFrames.
140
   */
141
  int GetFrameCount() const;
142
143
  /**
144
   * Grab a snapshot of the current JavaScript execution stack.
145
   *
146
   * \param frame_limit The maximum number of stack frames we want to capture.
147
   * \param options Enumerates the set of things we will capture for each
148
   *   StackFrame.
149
   */
150
  static Local<StackTrace> CurrentStackTrace(
151
      Isolate* isolate, int frame_limit, StackTraceOptions options = kDetailed);
152
153
  /**
154
   * Returns the first valid script name or source URL starting at the top of
155
   * the JS stack. The returned string is either an empty handle if no script
156
   * name/url was found or a non-zero-length string.
157
   *
158
   * This method is equivalent to calling StackTrace::CurrentStackTrace and
159
   * walking the resulting frames from the beginning until a non-empty script
160
   * name/url is found. The difference is that this method won't allocate
161
   * a stack trace.
162
   */
163
  static Local<String> CurrentScriptNameOrSourceURL(Isolate* isolate);
164
};
165
166
}  // namespace v8
167
168
#endif  // INCLUDE_V8_DEBUG_H_