v8-debug.h 5.0 KB

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