v8  10.1.124 (node 18.2.0)
V8 is Google's open source JavaScript engine
v8-debug.h
Go to the documentation of this file.
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  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  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_