include/node/v8-exception.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_EXCEPTION_H_
0006 #define INCLUDE_V8_EXCEPTION_H_
0007
0008 #include <stddef.h>
0009
0010 #include "v8-local-handle.h"  // NOLINT(build/include_directory)
0011 #include "v8config.h"         // NOLINT(build/include_directory)
0012
0013 namespace v8 {
0014
0015 class Context;
0016 class Isolate;
0017 class Message;
0018 class StackTrace;
0019 class String;
0020 class Value;
0021
0022 namespace internal {
0023 class Isolate;
0024 class ThreadLocalTop;
0025 }  // namespace internal
0026
0027 /**
0028  * Create new error objects by calling the corresponding error object
0029  * constructor with the message.
0030  */
0031 class V8_EXPORT Exception {
0032  public:
0033   static Local<Value> RangeError(Local<String> message,
0034                                  Local<Value> options = {});
0035   static Local<Value> ReferenceError(Local<String> message,
0036                                      Local<Value> options = {});
0037   static Local<Value> SyntaxError(Local<String> message,
0038                                   Local<Value> options = {});
0039   static Local<Value> TypeError(Local<String> message,
0040                                 Local<Value> options = {});
0041   static Local<Value> WasmCompileError(Local<String> message,
0042                                        Local<Value> options = {});
0043   static Local<Value> WasmLinkError(Local<String> message,
0044                                     Local<Value> options = {});
0045   static Local<Value> WasmRuntimeError(Local<String> message,
0046                                        Local<Value> options = {});
0047   static Local<Value> Error(Local<String> message, Local<Value> options = {});
0048
0049   /**
0050    * Creates an error message for the given exception.
0051    * Will try to reconstruct the original stack trace from the exception value,
0052    * or capture the current stack trace if not available.
0053    */
0054   static Local<Message> CreateMessage(Isolate* isolate, Local<Value> exception);
0055
0056   /**
0057    * Returns the original stack trace that was captured at the creation time
0058    * of a given exception, or an empty handle if not available.
0059    */
0060   static Local<StackTrace> GetStackTrace(Local<Value> exception);
0061 };
0062
0063 /**
0064  * An external exception handler.
0065  */
0066 class V8_EXPORT TryCatch {
0067  public:
0068   /**
0069    * Creates a new try/catch block and registers it with v8.  Note that
0070    * all TryCatch blocks should be stack allocated because the memory
0071    * location itself is compared against JavaScript try/catch blocks.
0072    */
0073   explicit TryCatch(Isolate* isolate);
0074
0075   /**
0076    * Unregisters and deletes this try/catch block.
0077    */
0078   ~TryCatch();
0079
0080   /**
0081    * Returns true if an exception has been caught by this try/catch block.
0082    */
0083   bool HasCaught() const;
0084
0085   /**
0086    * For certain types of exceptions, it makes no sense to continue execution.
0087    *
0088    * If CanContinue returns false, the correct action is to perform any C++
0089    * cleanup needed and then return.  If CanContinue returns false and
0090    * HasTerminated returns true, it is possible to call
0091    * CancelTerminateExecution in order to continue calling into the engine.
0092    */
0093   bool CanContinue() const;
0094
0095   /**
0096    * Returns true if an exception has been caught due to script execution
0097    * being terminated.
0098    *
0099    * There is no JavaScript representation of an execution termination
0100    * exception.  Such exceptions are thrown when the TerminateExecution
0101    * methods are called to terminate a long-running script.
0102    *
0103    * If such an exception has been thrown, HasTerminated will return true,
0104    * indicating that it is possible to call CancelTerminateExecution in order
0105    * to continue calling into the engine.
0106    */
0107   bool HasTerminated() const;
0108
0109   /**
0110    * Throws the exception caught by this TryCatch in a way that avoids
0111    * it being caught again by this same TryCatch.  As with ThrowException
0112    * it is illegal to execute any JavaScript operations after calling
0113    * ReThrow; the caller must return immediately to where the exception
0114    * is caught.
0115    */
0116   Local<Value> ReThrow();
0117
0118   /**
0119    * Returns the exception caught by this try/catch block.  If no exception has
0120    * been caught an empty handle is returned.
0121    */
0122   Local<Value> Exception() const;
0123
0124   /**
0125    * Returns the .stack property of an object.  If no .stack
0126    * property is present an empty handle is returned.
0127    */
0128   V8_WARN_UNUSED_RESULT static MaybeLocal<Value> StackTrace(
0129       Local<Context> context, Local<Value> exception);
0130
0131   /**
0132    * Returns the .stack property of the thrown object.  If no .stack property is
0133    * present or if this try/catch block has not caught an exception, an empty
0134    * handle is returned.
0135    */
0136   V8_WARN_UNUSED_RESULT MaybeLocal<Value> StackTrace(
0137       Local<Context> context) const;
0138
0139   /**
0140    * Returns the message associated with this exception.  If there is
0141    * no message associated an empty handle is returned.
0142    */
0143   Local<v8::Message> Message() const;
0144
0145   /**
0146    * Clears any exceptions that may have been caught by this try/catch block.
0147    * After this method has been called, HasCaught() will return false. Cancels
0148    * the scheduled exception if it is caught and ReThrow() is not called before.
0149    *
0150    * It is not necessary to clear a try/catch block before using it again; if
0151    * another exception is thrown the previously caught exception will just be
0152    * overwritten.  However, it is often a good idea since it makes it easier
0153    * to determine which operation threw a given exception.
0154    */
0155   void Reset();
0156
0157   /**
0158    * Set verbosity of the external exception handler.
0159    *
0160    * By default, exceptions that are caught by an external exception
0161    * handler are not reported.  Call SetVerbose with true on an
0162    * external exception handler to have exceptions caught by the
0163    * handler reported as if they were not caught.
0164    */
0165   void SetVerbose(bool value);
0166
0167   /**
0168    * Returns true if verbosity is enabled.
0169    */
0170   bool IsVerbose() const;
0171
0172   /**
0173    * Set whether or not this TryCatch should capture a Message object
0174    * which holds source information about where the exception
0175    * occurred.  True by default.
0176    */
0177   void SetCaptureMessage(bool value);
0178
0179   TryCatch(const TryCatch&) = delete;
0180   void operator=(const TryCatch&) = delete;
0181
0182  private:
0183   // Declaring operator new and delete as deleted is not spec compliant.
0184   // Therefore declare them private instead to disable dynamic alloc
0185   void* operator new(size_t size);
0186   void* operator new[](size_t size);
0187   void operator delete(void*, size_t);
0188   void operator delete[](void*, size_t);
0189
0190   /**
0191    * There are cases when the raw address of C++ TryCatch object cannot be
0192    * used for comparisons with addresses into the JS stack. The cases are:
0193    * 1) ARM, ARM64 and MIPS simulators which have separate JS stack.
0194    * 2) Address sanitizer allocates local C++ object in the heap when
0195    *    UseAfterReturn mode is enabled.
0196    * This method returns address that can be used for comparisons with
0197    * addresses into the JS stack. When neither simulator nor ASAN's
0198    * UseAfterReturn is enabled, then the address returned will be the address
0199    * of the C++ try catch handler itself.
0200    */
0201   internal::Address JSStackComparableAddressPrivate() {
0202     return js_stack_comparable_address_;
0203   }
0204
0205   void ResetInternal();
0206
0207   internal::Isolate* i_isolate_;
0208   TryCatch* next_;
0209   void* exception_;
0210   void* message_obj_;
0211   internal::Address js_stack_comparable_address_;
0212   bool is_verbose_ : 1;
0213   bool can_continue_ : 1;
0214   bool capture_message_ : 1;
0215   bool rethrow_ : 1;
0216
0217   friend class internal::Isolate;
0218   friend class internal::ThreadLocalTop;
0219 };
0220
0221 }  // namespace v8
0222
0223 #endif  // INCLUDE_V8_EXCEPTION_H_