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-local-handle.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 number, 1-based, of the line for the associate function call.
25    * This method will return Message::kNoLineNumberInfo if it is unable to
26    * retrieve the line number, or if kLineNumber was not passed as an option
27    * when capturing the StackTrace.
28    */
29   int GetLineNumber() const;
30 
31   /**
32    * Returns the 1-based column offset on the line for the associated function
33    * call.
34    * This method will return Message::kNoColumnInfo if it is unable to retrieve
35    * the column number, or if kColumnOffset was not passed as an option when
36    * capturing the StackTrace.
37    */
38   int GetColumn() const;
39 
40   /**
41    * Returns the id of the script for the function for this StackFrame.
42    * This method will return Message::kNoScriptIdInfo if it is unable to
43    * retrieve the script id, or if kScriptId was not passed as an option when
44    * capturing the StackTrace.
45    */
46   int GetScriptId() const;
47 
48   /**
49    * Returns the name of the resource that contains the script for the
50    * function for this StackFrame.
51    */
52   Local<String> GetScriptName() const;
53 
54   /**
55    * Returns the name of the resource that contains the script for the
56    * function for this StackFrame or sourceURL value if the script name
57    * is undefined and its source ends with //# sourceURL=... string or
58    * deprecated //@ sourceURL=... string.
59    */
60   Local<String> GetScriptNameOrSourceURL() const;
61 
62   /**
63    * Returns the source of the script for the function for this StackFrame.
64    */
65   Local<String> GetScriptSource() const;
66 
67   /**
68    * Returns the source mapping URL (if one is present) of the script for
69    * the function for this StackFrame.
70    */
71   Local<String> GetScriptSourceMappingURL() const;
72 
73   /**
74    * Returns the name of the function associated with this stack frame.
75    */
76   Local<String> GetFunctionName() const;
77 
78   /**
79    * Returns whether or not the associated function is compiled via a call to
80    * eval().
81    */
82   bool IsEval() const;
83 
84   /**
85    * Returns whether or not the associated function is called as a
86    * constructor via "new".
87    */
88   bool IsConstructor() const;
89 
90   /**
91    * Returns whether or not the associated functions is defined in wasm.
92    */
93   bool IsWasm() const;
94 
95   /**
96    * Returns whether or not the associated function is defined by the user.
97    */
98   bool IsUserJavaScript() const;
99 };
100 
101 /**
102  * Representation of a JavaScript stack trace. The information collected is a
103  * snapshot of the execution stack and the information remains valid after
104  * execution continues.
105  */
106 class V8_EXPORT StackTrace {
107  public:
108   /**
109    * Flags that determine what information is placed captured for each
110    * StackFrame when grabbing the current stack trace.
111    * Note: these options are deprecated and we always collect all available
112    * information (kDetailed).
113    */
114   enum StackTraceOptions {
115     kLineNumber = 1,
116     kColumnOffset = 1 << 1 | kLineNumber,
117     kScriptName = 1 << 2,
118     kFunctionName = 1 << 3,
119     kIsEval = 1 << 4,
120     kIsConstructor = 1 << 5,
121     kScriptNameOrSourceURL = 1 << 6,
122     kScriptId = 1 << 7,
123     kExposeFramesAcrossSecurityOrigins = 1 << 8,
124     kOverview = kLineNumber | kColumnOffset | kScriptName | kFunctionName,
125     kDetailed = kOverview | kIsEval | kIsConstructor | kScriptNameOrSourceURL
126   };
127 
128   /**
129    * Returns a StackFrame at a particular index.
130    */
131   Local<StackFrame> GetFrame(Isolate* isolate, uint32_t index) const;
132 
133   /**
134    * Returns the number of StackFrames.
135    */
136   int GetFrameCount() const;
137 
138   /**
139    * Grab a snapshot of the current JavaScript execution stack.
140    *
141    * \param frame_limit The maximum number of stack frames we want to capture.
142    * \param options Enumerates the set of things we will capture for each
143    *   StackFrame.
144    */
145   static Local<StackTrace> CurrentStackTrace(
146       Isolate* isolate, int frame_limit, StackTraceOptions options = kDetailed);
147 };
148 
149 }  // namespace v8
150 
151 #endif  // INCLUDE_V8_DEBUG_H_
152