include/node/v8-debug.h

0001 // Copyright 2021 the V8 project authors. All rights reserved.
0002 // Use of this source code is governed by a BSD-style license that can be
0003 // found in the LICENSE file.
0004
0005 #ifndef INCLUDE_V8_DEBUG_H_
0006 #define INCLUDE_V8_DEBUG_H_
0007
0008 #include <stdint.h>
0009
0010 #include "v8-script.h"  // NOLINT(build/include_directory)
0011 #include "v8config.h"   // NOLINT(build/include_directory)
0012
0013 namespace v8 {
0014
0015 class Isolate;
0016 class String;
0017
0018 /**
0019  * A single JavaScript stack frame.
0020  */
0021 class V8_EXPORT StackFrame {
0022  public:
0023   /**
0024    * Returns the source location, 0-based, for the associated function call.
0025    */
0026   Location GetLocation() const;
0027
0028   /**
0029    * Returns the number, 1-based, of the line for the associate function call.
0030    * This method will return Message::kNoLineNumberInfo if it is unable to
0031    * retrieve the line number, or if kLineNumber was not passed as an option
0032    * when capturing the StackTrace.
0033    */
0034   int GetLineNumber() const { return GetLocation().GetLineNumber() + 1; }
0035
0036   /**
0037    * Returns the 1-based column offset on the line for the associated function
0038    * call.
0039    * This method will return Message::kNoColumnInfo if it is unable to retrieve
0040    * the column number, or if kColumnOffset was not passed as an option when
0041    * capturing the StackTrace.
0042    */
0043   int GetColumn() const { return GetLocation().GetColumnNumber() + 1; }
0044
0045   /**
0046    * Returns the id of the script for the function for this StackFrame.
0047    * This method will return Message::kNoScriptIdInfo if it is unable to
0048    * retrieve the script id, or if kScriptId was not passed as an option when
0049    * capturing the StackTrace.
0050    */
0051   int GetScriptId() const;
0052
0053   /**
0054    * Returns the name of the resource that contains the script for the
0055    * function for this StackFrame.
0056    */
0057   Local<String> GetScriptName() const;
0058
0059   /**
0060    * Returns the name of the resource that contains the script for the
0061    * function for this StackFrame or sourceURL value if the script name
0062    * is undefined and its source ends with //# sourceURL=... string or
0063    * deprecated //@ sourceURL=... string.
0064    */
0065   Local<String> GetScriptNameOrSourceURL() const;
0066
0067   /**
0068    * Returns the source of the script for the function for this StackFrame.
0069    */
0070   Local<String> GetScriptSource() const;
0071
0072   /**
0073    * Returns the source mapping URL (if one is present) of the script for
0074    * the function for this StackFrame.
0075    */
0076   Local<String> GetScriptSourceMappingURL() const;
0077
0078   /**
0079    * Returns the name of the function associated with this stack frame.
0080    */
0081   Local<String> GetFunctionName() const;
0082
0083   /**
0084    * Returns whether or not the associated function is compiled via a call to
0085    * eval().
0086    */
0087   bool IsEval() const;
0088
0089   /**
0090    * Returns whether or not the associated function is called as a
0091    * constructor via "new".
0092    */
0093   bool IsConstructor() const;
0094
0095   /**
0096    * Returns whether or not the associated functions is defined in wasm.
0097    */
0098   bool IsWasm() const;
0099
0100   /**
0101    * Returns whether or not the associated function is defined by the user.
0102    */
0103   bool IsUserJavaScript() const;
0104 };
0105
0106 /**
0107  * Representation of a JavaScript stack trace. The information collected is a
0108  * snapshot of the execution stack and the information remains valid after
0109  * execution continues.
0110  */
0111 class V8_EXPORT StackTrace {
0112  public:
0113   /**
0114    * Flags that determine what information is placed captured for each
0115    * StackFrame when grabbing the current stack trace.
0116    * Note: these options are deprecated and we always collect all available
0117    * information (kDetailed).
0118    */
0119   enum StackTraceOptions {
0120     kLineNumber = 1,
0121     kColumnOffset = 1 << 1 | kLineNumber,
0122     kScriptName = 1 << 2,
0123     kFunctionName = 1 << 3,
0124     kIsEval = 1 << 4,
0125     kIsConstructor = 1 << 5,
0126     kScriptNameOrSourceURL = 1 << 6,
0127     kScriptId = 1 << 7,
0128     kExposeFramesAcrossSecurityOrigins = 1 << 8,
0129     kOverview = kLineNumber | kColumnOffset | kScriptName | kFunctionName,
0130     kDetailed = kOverview | kIsEval | kIsConstructor | kScriptNameOrSourceURL
0131   };
0132
0133   /**
0134    * Returns a StackFrame at a particular index.
0135    */
0136   Local<StackFrame> GetFrame(Isolate* isolate, uint32_t index) const;
0137
0138   /**
0139    * Returns the number of StackFrames.
0140    */
0141   int GetFrameCount() const;
0142
0143   /**
0144    * Grab a snapshot of the current JavaScript execution stack.
0145    *
0146    * \param frame_limit The maximum number of stack frames we want to capture.
0147    * \param options Enumerates the set of things we will capture for each
0148    *   StackFrame.
0149    */
0150   static Local<StackTrace> CurrentStackTrace(
0151       Isolate* isolate, int frame_limit, StackTraceOptions options = kDetailed);
0152
0153   /**
0154    * Returns the first valid script name or source URL starting at the top of
0155    * the JS stack. The returned string is either an empty handle if no script
0156    * name/url was found or a non-zero-length string.
0157    *
0158    * This method is equivalent to calling StackTrace::CurrentStackTrace and
0159    * walking the resulting frames from the beginning until a non-empty script
0160    * name/url is found. The difference is that this method won't allocate
0161    * a stack trace.
0162    */
0163   static Local<String> CurrentScriptNameOrSourceURL(Isolate* isolate);
0164 };
0165
0166 }  // namespace v8
0167
0168 #endif  // INCLUDE_V8_DEBUG_H_