v8-exception.h 7.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217
  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_EXCEPTION_H_
  5. #define INCLUDE_V8_EXCEPTION_H_
  6. #include <stddef.h>
  7. #include "v8-local-handle.h" // NOLINT(build/include_directory)
  8. #include "v8config.h" // NOLINT(build/include_directory)
  9. namespace v8 {
  10. class Context;
  11. class Isolate;
  12. class Message;
  13. class StackTrace;
  14. class String;
  15. class Value;
  16. namespace internal {
  17. class Isolate;
  18. class ThreadLocalTop;
  19. } // namespace internal
  20. /**
  21. * Create new error objects by calling the corresponding error object
  22. * constructor with the message.
  23. */
  24. class V8_EXPORT Exception {
  25. public:
  26. static Local<Value> RangeError(Local<String> message);
  27. static Local<Value> ReferenceError(Local<String> message);
  28. static Local<Value> SyntaxError(Local<String> message);
  29. static Local<Value> TypeError(Local<String> message);
  30. static Local<Value> WasmCompileError(Local<String> message);
  31. static Local<Value> WasmLinkError(Local<String> message);
  32. static Local<Value> WasmRuntimeError(Local<String> message);
  33. static Local<Value> Error(Local<String> message);
  34. /**
  35. * Creates an error message for the given exception.
  36. * Will try to reconstruct the original stack trace from the exception value,
  37. * or capture the current stack trace if not available.
  38. */
  39. static Local<Message> CreateMessage(Isolate* isolate, Local<Value> exception);
  40. /**
  41. * Returns the original stack trace that was captured at the creation time
  42. * of a given exception, or an empty handle if not available.
  43. */
  44. static Local<StackTrace> GetStackTrace(Local<Value> exception);
  45. };
  46. /**
  47. * An external exception handler.
  48. */
  49. class V8_EXPORT TryCatch {
  50. public:
  51. /**
  52. * Creates a new try/catch block and registers it with v8. Note that
  53. * all TryCatch blocks should be stack allocated because the memory
  54. * location itself is compared against JavaScript try/catch blocks.
  55. */
  56. explicit TryCatch(Isolate* isolate);
  57. /**
  58. * Unregisters and deletes this try/catch block.
  59. */
  60. ~TryCatch();
  61. /**
  62. * Returns true if an exception has been caught by this try/catch block.
  63. */
  64. bool HasCaught() const;
  65. /**
  66. * For certain types of exceptions, it makes no sense to continue execution.
  67. *
  68. * If CanContinue returns false, the correct action is to perform any C++
  69. * cleanup needed and then return. If CanContinue returns false and
  70. * HasTerminated returns true, it is possible to call
  71. * CancelTerminateExecution in order to continue calling into the engine.
  72. */
  73. bool CanContinue() const;
  74. /**
  75. * Returns true if an exception has been caught due to script execution
  76. * being terminated.
  77. *
  78. * There is no JavaScript representation of an execution termination
  79. * exception. Such exceptions are thrown when the TerminateExecution
  80. * methods are called to terminate a long-running script.
  81. *
  82. * If such an exception has been thrown, HasTerminated will return true,
  83. * indicating that it is possible to call CancelTerminateExecution in order
  84. * to continue calling into the engine.
  85. */
  86. bool HasTerminated() const;
  87. /**
  88. * Throws the exception caught by this TryCatch in a way that avoids
  89. * it being caught again by this same TryCatch. As with ThrowException
  90. * it is illegal to execute any JavaScript operations after calling
  91. * ReThrow; the caller must return immediately to where the exception
  92. * is caught.
  93. */
  94. Local<Value> ReThrow();
  95. /**
  96. * Returns the exception caught by this try/catch block. If no exception has
  97. * been caught an empty handle is returned.
  98. */
  99. Local<Value> Exception() const;
  100. /**
  101. * Returns the .stack property of an object. If no .stack
  102. * property is present an empty handle is returned.
  103. */
  104. V8_WARN_UNUSED_RESULT static MaybeLocal<Value> StackTrace(
  105. Local<Context> context, Local<Value> exception);
  106. /**
  107. * Returns the .stack property of the thrown object. If no .stack property is
  108. * present or if this try/catch block has not caught an exception, an empty
  109. * handle is returned.
  110. */
  111. V8_WARN_UNUSED_RESULT MaybeLocal<Value> StackTrace(
  112. Local<Context> context) const;
  113. /**
  114. * Returns the message associated with this exception. If there is
  115. * no message associated an empty handle is returned.
  116. */
  117. Local<v8::Message> Message() const;
  118. /**
  119. * Clears any exceptions that may have been caught by this try/catch block.
  120. * After this method has been called, HasCaught() will return false. Cancels
  121. * the scheduled exception if it is caught and ReThrow() is not called before.
  122. *
  123. * It is not necessary to clear a try/catch block before using it again; if
  124. * another exception is thrown the previously caught exception will just be
  125. * overwritten. However, it is often a good idea since it makes it easier
  126. * to determine which operation threw a given exception.
  127. */
  128. void Reset();
  129. /**
  130. * Set verbosity of the external exception handler.
  131. *
  132. * By default, exceptions that are caught by an external exception
  133. * handler are not reported. Call SetVerbose with true on an
  134. * external exception handler to have exceptions caught by the
  135. * handler reported as if they were not caught.
  136. */
  137. void SetVerbose(bool value);
  138. /**
  139. * Returns true if verbosity is enabled.
  140. */
  141. bool IsVerbose() const;
  142. /**
  143. * Set whether or not this TryCatch should capture a Message object
  144. * which holds source information about where the exception
  145. * occurred. True by default.
  146. */
  147. void SetCaptureMessage(bool value);
  148. TryCatch(const TryCatch&) = delete;
  149. void operator=(const TryCatch&) = delete;
  150. private:
  151. // Declaring operator new and delete as deleted is not spec compliant.
  152. // Therefore declare them private instead to disable dynamic alloc
  153. void* operator new(size_t size);
  154. void* operator new[](size_t size);
  155. void operator delete(void*, size_t);
  156. void operator delete[](void*, size_t);
  157. /**
  158. * There are cases when the raw address of C++ TryCatch object cannot be
  159. * used for comparisons with addresses into the JS stack. The cases are:
  160. * 1) ARM, ARM64 and MIPS simulators which have separate JS stack.
  161. * 2) Address sanitizer allocates local C++ object in the heap when
  162. * UseAfterReturn mode is enabled.
  163. * This method returns address that can be used for comparisons with
  164. * addresses into the JS stack. When neither simulator nor ASAN's
  165. * UseAfterReturn is enabled, then the address returned will be the address
  166. * of the C++ try catch handler itself.
  167. */
  168. internal::Address JSStackComparableAddressPrivate() {
  169. return js_stack_comparable_address_;
  170. }
  171. void ResetInternal();
  172. internal::Isolate* isolate_;
  173. TryCatch* next_;
  174. void* exception_;
  175. void* message_obj_;
  176. internal::Address js_stack_comparable_address_;
  177. bool is_verbose_ : 1;
  178. bool can_continue_ : 1;
  179. bool capture_message_ : 1;
  180. bool rethrow_ : 1;
  181. bool has_terminated_ : 1;
  182. friend class internal::Isolate;
  183. friend class internal::ThreadLocalTop;
  184. };
  185. } // namespace v8
  186. #endif // INCLUDE_V8_EXCEPTION_H_