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