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 "v8-object.h"        // NOLINT(build/include_directory)
0012 #include "v8config.h"         // NOLINT(build/include_directory)
0013
0014 namespace v8 {
0015
0016 class Context;
0017 class Isolate;
0018 class Message;
0019 class StackTrace;
0020 class String;
0021 class Value;
0022
0023 namespace internal {
0024 class Isolate;
0025 class ThreadLocalTop;
0026 }  // namespace internal
0027
0028 /**
0029  * Create new error objects by calling the corresponding error object
0030  * constructor with the message.
0031  */
0032 class V8_EXPORT Exception {
0033  public:
0034   static Local<Value> RangeError(Local<String> message,
0035                                  Local<Value> options = {});
0036   static Local<Value> ReferenceError(Local<String> message,
0037                                      Local<Value> options = {});
0038   static Local<Value> SyntaxError(Local<String> message,
0039                                   Local<Value> options = {});
0040   static Local<Value> TypeError(Local<String> message,
0041                                 Local<Value> options = {});
0042   static Local<Value> WasmCompileError(Local<String> message,
0043                                        Local<Value> options = {});
0044   static Local<Value> WasmLinkError(Local<String> message,
0045                                     Local<Value> options = {});
0046   static Local<Value> WasmRuntimeError(Local<String> message,
0047                                        Local<Value> options = {});
0048   static Local<Value> WasmSuspendError(Local<String> message,
0049                                        Local<Value> options = {});
0050   static Local<Value> Error(Local<String> message, Local<Value> options = {});
0051
0052   /**
0053    * Creates an error message for the given exception.
0054    * Will try to reconstruct the original stack trace from the exception value,
0055    * or capture the current stack trace if not available.
0056    */
0057   static Local<Message> CreateMessage(Isolate* isolate, Local<Value> exception);
0058
0059   /**
0060    * Returns the original stack trace that was captured at the creation time
0061    * of a given exception, or an empty handle if not available.
0062    */
0063   static Local<StackTrace> GetStackTrace(Local<Value> exception);
0064
0065   /**
0066    * Captures the current stack trace and attaches it to the given object in the
0067    * form of `stack` property.
0068    */
0069   static Maybe<bool> CaptureStackTrace(Local<Context> context,
0070                                        Local<Object> object);
0071 };
0072
0073 /**
0074  * This is a part of experimental Api and might be changed without further
0075  * notice.
0076  * Do not use it.
0077  */
0078 enum class ExceptionContext : uint32_t {
0079   kUnknown,
0080   kConstructor,
0081   kOperation,
0082   kAttributeGet,
0083   kAttributeSet,
0084   kIndexedQuery,
0085   kIndexedGetter,
0086   kIndexedDescriptor,
0087   kIndexedSetter,
0088   kIndexedDefiner,
0089   kIndexedDeleter,
0090   kNamedQuery,
0091   kNamedGetter,
0092   kNamedDescriptor,
0093   kNamedSetter,
0094   kNamedDefiner,
0095   kNamedDeleter,
0096   kNamedEnumerator
0097 };
0098
0099 /**
0100  * This is a part of experimental Api and might be changed without further
0101  * notice.
0102  * Do not use it.
0103  */
0104 class ExceptionPropagationMessage {
0105  public:
0106   ExceptionPropagationMessage(v8::Isolate* isolate, Local<Object> exception,
0107                               Local<String> interface_name,
0108                               Local<String> property_name,
0109                               ExceptionContext exception_context)
0110       : isolate_(isolate),
0111         exception_(exception),
0112         interface_name_(interface_name),
0113         property_name_(property_name),
0114         exception_context_(exception_context) {}
0115
0116   V8_INLINE Isolate* GetIsolate() const { return isolate_; }
0117   V8_INLINE Local<Object> GetException() const { return exception_; }
0118   V8_INLINE Local<String> GetInterfaceName() const { return interface_name_; }
0119   V8_INLINE Local<String> GetPropertyName() const { return property_name_; }
0120   V8_INLINE ExceptionContext GetExceptionContext() const {
0121     return exception_context_;
0122   }
0123
0124  private:
0125   Isolate* isolate_;
0126   Local<Object> exception_;
0127   Local<String> interface_name_;
0128   Local<String> property_name_;
0129   ExceptionContext exception_context_;
0130 };
0131
0132 using ExceptionPropagationCallback =
0133     void (*)(ExceptionPropagationMessage message);
0134
0135 /**
0136  * An external exception handler.
0137  */
0138 class V8_EXPORT TryCatch {
0139  public:
0140   /**
0141    * Creates a new try/catch block and registers it with v8.  Note that
0142    * all TryCatch blocks should be stack allocated because the memory
0143    * location itself is compared against JavaScript try/catch blocks.
0144    */
0145   explicit TryCatch(Isolate* isolate);
0146
0147   /**
0148    * Unregisters and deletes this try/catch block.
0149    */
0150   ~TryCatch();
0151
0152   /**
0153    * Returns true if an exception has been caught by this try/catch block.
0154    */
0155   bool HasCaught() const;
0156
0157   /**
0158    * For certain types of exceptions, it makes no sense to continue execution.
0159    *
0160    * If CanContinue returns false, the correct action is to perform any C++
0161    * cleanup needed and then return.  If CanContinue returns false and
0162    * HasTerminated returns true, it is possible to call
0163    * CancelTerminateExecution in order to continue calling into the engine.
0164    */
0165   bool CanContinue() const;
0166
0167   /**
0168    * Returns true if an exception has been caught due to script execution
0169    * being terminated.
0170    *
0171    * There is no JavaScript representation of an execution termination
0172    * exception.  Such exceptions are thrown when the TerminateExecution
0173    * methods are called to terminate a long-running script.
0174    *
0175    * If such an exception has been thrown, HasTerminated will return true,
0176    * indicating that it is possible to call CancelTerminateExecution in order
0177    * to continue calling into the engine.
0178    */
0179   bool HasTerminated() const;
0180
0181   /**
0182    * Throws the exception caught by this TryCatch in a way that avoids
0183    * it being caught again by this same TryCatch.  As with ThrowException
0184    * it is illegal to execute any JavaScript operations after calling
0185    * ReThrow; the caller must return immediately to where the exception
0186    * is caught.
0187    */
0188   Local<Value> ReThrow();
0189
0190   /**
0191    * Returns the exception caught by this try/catch block.  If no exception has
0192    * been caught an empty handle is returned.
0193    */
0194   Local<Value> Exception() const;
0195
0196   /**
0197    * Returns the .stack property of an object.  If no .stack
0198    * property is present an empty handle is returned.
0199    */
0200   V8_WARN_UNUSED_RESULT static MaybeLocal<Value> StackTrace(
0201       Local<Context> context, Local<Value> exception);
0202
0203   /**
0204    * Returns the .stack property of the thrown object.  If no .stack property is
0205    * present or if this try/catch block has not caught an exception, an empty
0206    * handle is returned.
0207    */
0208   V8_WARN_UNUSED_RESULT MaybeLocal<Value> StackTrace(
0209       Local<Context> context) const;
0210
0211   /**
0212    * Returns the message associated with this exception.  If there is
0213    * no message associated an empty handle is returned.
0214    */
0215   Local<v8::Message> Message() const;
0216
0217   /**
0218    * Clears any exceptions that may have been caught by this try/catch block.
0219    * After this method has been called, HasCaught() will return false. Cancels
0220    * the scheduled exception if it is caught and ReThrow() is not called before.
0221    *
0222    * It is not necessary to clear a try/catch block before using it again; if
0223    * another exception is thrown the previously caught exception will just be
0224    * overwritten.  However, it is often a good idea since it makes it easier
0225    * to determine which operation threw a given exception.
0226    */
0227   void Reset();
0228
0229   /**
0230    * Set verbosity of the external exception handler.
0231    *
0232    * By default, exceptions that are caught by an external exception
0233    * handler are not reported.  Call SetVerbose with true on an
0234    * external exception handler to have exceptions caught by the
0235    * handler reported as if they were not caught.
0236    */
0237   void SetVerbose(bool value);
0238
0239   /**
0240    * Returns true if verbosity is enabled.
0241    */
0242   bool IsVerbose() const;
0243
0244   /**
0245    * Set whether or not this TryCatch should capture a Message object
0246    * which holds source information about where the exception
0247    * occurred.  True by default.
0248    */
0249   void SetCaptureMessage(bool value);
0250
0251   TryCatch(const TryCatch&) = delete;
0252   void operator=(const TryCatch&) = delete;
0253
0254  private:
0255   // Declaring operator new and delete as deleted is not spec compliant.
0256   // Therefore declare them private instead to disable dynamic alloc
0257   void* operator new(size_t size);
0258   void* operator new[](size_t size);
0259   void operator delete(void*, size_t);
0260   void operator delete[](void*, size_t);
0261
0262   /**
0263    * There are cases when the raw address of C++ TryCatch object cannot be
0264    * used for comparisons with addresses into the JS stack. The cases are:
0265    * 1) ARM, ARM64 and MIPS simulators which have separate JS stack.
0266    * 2) Address sanitizer allocates local C++ object in the heap when
0267    *    UseAfterReturn mode is enabled.
0268    * This method returns address that can be used for comparisons with
0269    * addresses into the JS stack. When neither simulator nor ASAN's
0270    * UseAfterReturn is enabled, then the address returned will be the address
0271    * of the C++ try catch handler itself.
0272    */
0273   internal::Address JSStackComparableAddressPrivate() {
0274     return js_stack_comparable_address_;
0275   }
0276
0277   void ResetInternal();
0278
0279   internal::Isolate* i_isolate_;
0280   TryCatch* next_;
0281   void* exception_;
0282   void* message_obj_;
0283   internal::Address js_stack_comparable_address_;
0284   bool is_verbose_ : 1;
0285   bool can_continue_ : 1;
0286   bool capture_message_ : 1;
0287   bool rethrow_ : 1;
0288
0289   friend class internal::Isolate;
0290   friend class internal::ThreadLocalTop;
0291 };
0292
0293 }  // namespace v8
0294
0295 #endif  // INCLUDE_V8_EXCEPTION_H_