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 zero based source position (character offset) for the associated
0047    * function.
0048    */
0049   int GetSourcePosition() const;
0050
0051   /**
0052    * Returns the id of the script for the function for this StackFrame.
0053    * This method will return Message::kNoScriptIdInfo if it is unable to
0054    * retrieve the script id, or if kScriptId was not passed as an option when
0055    * capturing the StackTrace.
0056    */
0057   int GetScriptId() const;
0058
0059   /**
0060    * Returns the name of the resource that contains the script for the
0061    * function for this StackFrame.
0062    */
0063   Local<String> GetScriptName() const;
0064
0065   /**
0066    * Returns the name of the resource that contains the script for the
0067    * function for this StackFrame or sourceURL value if the script name
0068    * is undefined and its source ends with //# sourceURL=... string or
0069    * deprecated //@ sourceURL=... string.
0070    */
0071   Local<String> GetScriptNameOrSourceURL() const;
0072
0073   /**
0074    * Returns the source of the script for the function for this StackFrame.
0075    */
0076   Local<String> GetScriptSource() const;
0077
0078   /**
0079    * Returns the source mapping URL (if one is present) of the script for
0080    * the function for this StackFrame.
0081    */
0082   Local<String> GetScriptSourceMappingURL() const;
0083
0084   /**
0085    * Returns the name of the function associated with this stack frame.
0086    */
0087   Local<String> GetFunctionName() const;
0088
0089   /**
0090    * Returns whether or not the associated function is compiled via a call to
0091    * eval().
0092    */
0093   bool IsEval() const;
0094
0095   /**
0096    * Returns whether or not the associated function is called as a
0097    * constructor via "new".
0098    */
0099   bool IsConstructor() const;
0100
0101   /**
0102    * Returns whether or not the associated functions is defined in wasm.
0103    */
0104   bool IsWasm() const;
0105
0106   /**
0107    * Returns whether or not the associated function is defined by the user.
0108    */
0109   bool IsUserJavaScript() const;
0110 };
0111
0112 /**
0113  * Representation of a JavaScript stack trace. The information collected is a
0114  * snapshot of the execution stack and the information remains valid after
0115  * execution continues.
0116  */
0117 class V8_EXPORT StackTrace {
0118  public:
0119   /**
0120    * Flags that determine what information is placed captured for each
0121    * StackFrame when grabbing the current stack trace.
0122    * Note: these options are deprecated and we always collect all available
0123    * information (kDetailed).
0124    */
0125   enum StackTraceOptions {
0126     kLineNumber = 1,
0127     kColumnOffset = 1 << 1 | kLineNumber,
0128     kScriptName = 1 << 2,
0129     kFunctionName = 1 << 3,
0130     kIsEval = 1 << 4,
0131     kIsConstructor = 1 << 5,
0132     kScriptNameOrSourceURL = 1 << 6,
0133     kScriptId = 1 << 7,
0134     kExposeFramesAcrossSecurityOrigins = 1 << 8,
0135     kOverview = kLineNumber | kColumnOffset | kScriptName | kFunctionName,
0136     kDetailed = kOverview | kIsEval | kIsConstructor | kScriptNameOrSourceURL
0137   };
0138
0139   struct ScriptIdAndContext {
0140     int id;
0141     v8::Local<v8::Context> context;
0142   };
0143
0144   /**
0145    * Returns the (unique) ID of this stack trace.
0146    */
0147   int GetID() const;
0148
0149   /**
0150    * Returns a StackFrame at a particular index.
0151    */
0152   Local<StackFrame> GetFrame(Isolate* isolate, uint32_t index) const;
0153
0154   /**
0155    * Returns the number of StackFrames.
0156    */
0157   int GetFrameCount() const;
0158
0159   /**
0160    * Grab a snapshot of the current JavaScript execution stack.
0161    *
0162    * \param frame_limit The maximum number of stack frames we want to capture.
0163    * \param options Enumerates the set of things we will capture for each
0164    *   StackFrame.
0165    */
0166   static Local<StackTrace> CurrentStackTrace(
0167       Isolate* isolate, int frame_limit, StackTraceOptions options = kDetailed);
0168
0169   /**
0170    * Returns the first valid script name or source URL starting at the top of
0171    * the JS stack. The returned string is either an empty handle if no script
0172    * name/url was found or a non-zero-length string.
0173    *
0174    * This method is equivalent to calling StackTrace::CurrentStackTrace and
0175    * walking the resulting frames from the beginning until a non-empty script
0176    * name/url is found. The difference is that this method won't allocate
0177    * a stack trace.
0178    */
0179   static Local<String> CurrentScriptNameOrSourceURL(Isolate* isolate);
0180
0181   /**
0182    * Returns the first valid script id at the top of the JS stack. The returned
0183    * value is Message::kNoScriptIdInfo if no id was found.
0184    *
0185    * This method is equivalent to calling StackTrace::CurrentStackTrace and
0186    * walking the resulting frames from the beginning until a non-empty id is
0187    * found. The difference is that this method won't allocate a stack trace.
0188    */
0189   static int CurrentScriptId(Isolate* isolate);
0190
0191   /**
0192    * Writes up to the first `frame_data.size()` valid script ids and function
0193    * contexts at the top of the JS stack into the given span. Returns a span
0194    * sized to the number of frames worth of data written. It's similar to the
0195    * CurrentStackTrace method but doesn't allocate a stack trace. Further, it
0196    * skips frames that don't have valid script ids or function contexts. The
0197    * final difference is that the script id written for evals or regexp is that
0198    * of the script that ran eval() or regexp, not the current context.
0199    *
0200    * WARNING: This is an unfinished experimental feature. Semantics and
0201    * implementation may change frequently.
0202    */
0203   static v8::MemorySpan<v8::StackTrace::ScriptIdAndContext>
0204   CurrentScriptIdsAndContexts(Isolate* isolate,
0205                               v8::MemorySpan<ScriptIdAndContext> frame_data);
0206 };
0207
0208 }  // namespace v8
0209
0210 #endif  // INCLUDE_V8_DEBUG_H_