include/v8-exception.h - v8/v8.git - Git at Google

 // Copyright 2021 the V8 project authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

 #ifndef INCLUDE_V8_EXCEPTION_H_
 #define INCLUDE_V8_EXCEPTION_H_

 #include <stddef.h>

 #include "v8-local-handle.h"  // NOLINT(build/include_directory)
 #include "v8-object.h"        // NOLINT(build/include_directory)
 #include "v8config.h"         // NOLINT(build/include_directory)

 namespace v8 {

 class Context;
 class Isolate;
 class Message;
 class StackTrace;
 class String;
 class Value;

 namespace internal {
 class Isolate;
 class ThreadLocalTop;
 }  // namespace internal

 /**
  * Create new error objects by calling the corresponding error object
  * constructor with the message.
  */
 class V8_EXPORT Exception {
  public:
   static Local<Value> RangeError(Local<String> message,
                                  Local<Value> options = {});
   static Local<Value> ReferenceError(Local<String> message,
                                      Local<Value> options = {});
   static Local<Value> SyntaxError(Local<String> message,
                                   Local<Value> options = {});
   static Local<Value> TypeError(Local<String> message,
                                 Local<Value> options = {});
   static Local<Value> WasmCompileError(Local<String> message,
                                        Local<Value> options = {});
   static Local<Value> WasmLinkError(Local<String> message,
                                     Local<Value> options = {});
   static Local<Value> WasmRuntimeError(Local<String> message,
                                        Local<Value> options = {});
   static Local<Value> WasmSuspendError(Local<String> message,
                                        Local<Value> options = {});
   static Local<Value> Error(Local<String> message, Local<Value> options = {});

   /**
    * Creates an error message for the given exception.
    * Will try to reconstruct the original stack trace from the exception value,
    * or capture the current stack trace if not available.
    */
   static Local<Message> CreateMessage(Isolate* isolate, Local<Value> exception);

   /**
    * Returns the original stack trace that was captured at the creation time
    * of a given exception, or an empty handle if not available.
    */
   static Local<StackTrace> GetStackTrace(Local<Value> exception);

   /**
    * Captures the current stack trace and attaches it to the given object in the
    * form of `stack` property.
    */
   static Maybe<bool> CaptureStackTrace(Local<Context> context,
                                        Local<Object> object);
 };

 /**
  * This is a part of experimental Api and might be changed without further
  * notice.
  * Do not use it.
  */
 enum class ExceptionContext : uint32_t {
   kUnknown,
   kConstructor,
   kOperation,
   kAttributeGet,
   kAttributeSet,
   kIndexedQuery,
   kIndexedGetter,
   kIndexedDescriptor,
   kIndexedSetter,
   kIndexedDefiner,
   kIndexedDeleter,
   kNamedQuery,
   kNamedGetter,
   kNamedDescriptor,
   kNamedSetter,
   kNamedDefiner,
   kNamedDeleter,
   kNamedEnumerator
 };

 /**
  * This is a part of experimental Api and might be changed without further
  * notice.
  * Do not use it.
  */
 class ExceptionPropagationMessage {
  public:
   ExceptionPropagationMessage(v8::Isolate* isolate, Local<Object> exception,
                               Local<String> interface_name,
                               Local<String> property_name,
                               ExceptionContext exception_context)
       : isolate_(isolate),
         exception_(exception),
         interface_name_(interface_name),
         property_name_(property_name),
         exception_context_(exception_context) {}

   V8_INLINE Isolate* GetIsolate() const { return isolate_; }
   V8_INLINE Local<Object> GetException() const { return exception_; }
   V8_INLINE Local<String> GetInterfaceName() const { return interface_name_; }
   V8_INLINE Local<String> GetPropertyName() const { return property_name_; }
   V8_INLINE ExceptionContext GetExceptionContext() const {
     return exception_context_;
   }

  private:
   Isolate* isolate_;
   Local<Object> exception_;
   Local<String> interface_name_;
   Local<String> property_name_;
   ExceptionContext exception_context_;
 };

 using ExceptionPropagationCallback =
     void (*)(ExceptionPropagationMessage message);

 /**
  * An external exception handler.
  */
 class V8_EXPORT TryCatch {
  public:
   /**
    * Creates a new try/catch block and registers it with v8.  Note that
    * all TryCatch blocks should be stack allocated because the memory
    * location itself is compared against JavaScript try/catch blocks.
    */
   explicit TryCatch(Isolate* isolate);

   /**
    * Unregisters and deletes this try/catch block.
    */
   ~TryCatch();

   /**
    * Returns true if an exception has been caught by this try/catch block.
    */
   bool HasCaught() const;

   /**
    * For certain types of exceptions, it makes no sense to continue execution.
    *
    * If CanContinue returns false, the correct action is to perform any C++
    * cleanup needed and then return.  If CanContinue returns false and
    * HasTerminated returns true, it is possible to call
    * CancelTerminateExecution in order to continue calling into the engine.
    */
   bool CanContinue() const;

   /**
    * Returns true if an exception has been caught due to script execution
    * being terminated.
    *
    * There is no JavaScript representation of an execution termination
    * exception.  Such exceptions are thrown when the TerminateExecution
    * methods are called to terminate a long-running script.
    *
    * If such an exception has been thrown, HasTerminated will return true,
    * indicating that it is possible to call CancelTerminateExecution in order
    * to continue calling into the engine.
    */
   bool HasTerminated() const;

   /**
    * Throws the exception caught by this TryCatch in a way that avoids
    * it being caught again by this same TryCatch.  As with ThrowException
    * it is illegal to execute any JavaScript operations after calling
    * ReThrow; the caller must return immediately to where the exception
    * is caught.
    */
   Local<Value> ReThrow();

   /**
    * Returns the exception caught by this try/catch block.  If no exception has
    * been caught an empty handle is returned.
    */
   Local<Value> Exception() const;

   /**
    * Returns the .stack property of an object.  If no .stack
    * property is present an empty handle is returned.
    */
   V8_WARN_UNUSED_RESULT static MaybeLocal<Value> StackTrace(
       Local<Context> context, Local<Value> exception);

   /**
    * Returns the .stack property of the thrown object.  If no .stack property is
    * present or if this try/catch block has not caught an exception, an empty
    * handle is returned.
    */
   V8_WARN_UNUSED_RESULT MaybeLocal<Value> StackTrace(
       Local<Context> context) const;

   /**
    * Returns the message associated with this exception.  If there is
    * no message associated an empty handle is returned.
    */
   Local<v8::Message> Message() const;

   /**
    * Clears any exceptions that may have been caught by this try/catch block.
    * After this method has been called, HasCaught() will return false. Cancels
    * the scheduled exception if it is caught and ReThrow() is not called before.
    *
    * It is not necessary to clear a try/catch block before using it again; if
    * another exception is thrown the previously caught exception will just be
    * overwritten.  However, it is often a good idea since it makes it easier
    * to determine which operation threw a given exception.
    */
   void Reset();

   /**
    * Set verbosity of the external exception handler.
    *
    * By default, exceptions that are caught by an external exception
    * handler are not reported.  Call SetVerbose with true on an
    * external exception handler to have exceptions caught by the
    * handler reported as if they were not caught.
    */
   void SetVerbose(bool value);

   /**
    * Returns true if verbosity is enabled.
    */
   bool IsVerbose() const;

   /**
    * Set whether or not this TryCatch should capture a Message object
    * which holds source information about where the exception
    * occurred.  True by default.
    */
   void SetCaptureMessage(bool value);

   TryCatch(const TryCatch&) = delete;
   void operator=(const TryCatch&) = delete;

  private:
   // Declaring operator new and delete as deleted is not spec compliant.
   // Therefore declare them private instead to disable dynamic alloc
   void* operator new(size_t size);
   void* operator new[](size_t size);
   void operator delete(void*, size_t);
   void operator delete[](void*, size_t);

   /**
    * There are cases when the raw address of C++ TryCatch object cannot be
    * used for comparisons with addresses into the JS stack. The cases are:
    * 1) ARM, ARM64 and MIPS simulators which have separate JS stack.
    * 2) Address sanitizer allocates local C++ object in the heap when
    *    UseAfterReturn mode is enabled.
    * This method returns address that can be used for comparisons with
    * addresses into the JS stack. When neither simulator nor ASAN's
    * UseAfterReturn is enabled, then the address returned will be the address
    * of the C++ try catch handler itself.
    */
   internal::Address JSStackComparableAddressPrivate() {
     return js_stack_comparable_address_;
   }

   void ResetInternal();

   internal::Isolate* i_isolate_;
   TryCatch* next_;
   void* exception_;
   void* message_obj_;
   internal::Address js_stack_comparable_address_;
   bool is_verbose_ : 1;
   bool can_continue_ : 1;
   bool capture_message_ : 1;
   bool rethrow_ : 1;

   friend class internal::Isolate;
   friend class internal::ThreadLocalTop;
 };

 }  // namespace v8

 #endif  // INCLUDE_V8_EXCEPTION_H_
	// Copyright 2021 the V8 project authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.

	#ifndef INCLUDE_V8_EXCEPTION_H_
	#define INCLUDE_V8_EXCEPTION_H_

	#include <stddef.h>

	#include "v8-local-handle.h" // NOLINT(build/include_directory)
	#include "v8-object.h" // NOLINT(build/include_directory)
	#include "v8config.h" // NOLINT(build/include_directory)

	namespace v8 {

	class Context;
	class Isolate;
	class Message;
	class StackTrace;
	class String;
	class Value;

	namespace internal {
	class Isolate;
	class ThreadLocalTop;
	} // namespace internal

	/**
	* Create new error objects by calling the corresponding error object
	* constructor with the message.
	*/
	class V8_EXPORT Exception {
	public:
	static Local<Value> RangeError(Local<String> message,
	Local<Value> options = {});
	static Local<Value> ReferenceError(Local<String> message,
	Local<Value> options = {});
	static Local<Value> SyntaxError(Local<String> message,
	Local<Value> options = {});
	static Local<Value> TypeError(Local<String> message,
	Local<Value> options = {});
	static Local<Value> WasmCompileError(Local<String> message,
	Local<Value> options = {});
	static Local<Value> WasmLinkError(Local<String> message,
	Local<Value> options = {});
	static Local<Value> WasmRuntimeError(Local<String> message,
	Local<Value> options = {});
	static Local<Value> WasmSuspendError(Local<String> message,
	Local<Value> options = {});
	static Local<Value> Error(Local<String> message, Local<Value> options = {});

	/**
	* Creates an error message for the given exception.
	* Will try to reconstruct the original stack trace from the exception value,
	* or capture the current stack trace if not available.
	*/
	static Local<Message> CreateMessage(Isolate* isolate, Local<Value> exception);

	/**
	* Returns the original stack trace that was captured at the creation time
	* of a given exception, or an empty handle if not available.
	*/
	static Local<StackTrace> GetStackTrace(Local<Value> exception);

	/**
	* Captures the current stack trace and attaches it to the given object in the
	* form of `stack` property.
	*/
	static Maybe<bool> CaptureStackTrace(Local<Context> context,
	Local<Object> object);
	};

	/**
	* This is a part of experimental Api and might be changed without further
	* notice.
	* Do not use it.
	*/
	enum class ExceptionContext : uint32_t {
	kUnknown,
	kConstructor,
	kOperation,
	kAttributeGet,
	kAttributeSet,
	kIndexedQuery,
	kIndexedGetter,
	kIndexedDescriptor,
	kIndexedSetter,
	kIndexedDefiner,
	kIndexedDeleter,
	kNamedQuery,
	kNamedGetter,
	kNamedDescriptor,
	kNamedSetter,
	kNamedDefiner,
	kNamedDeleter,
	kNamedEnumerator
	};

	/**
	* This is a part of experimental Api and might be changed without further
	* notice.
	* Do not use it.
	*/
	class ExceptionPropagationMessage {
	public:
	ExceptionPropagationMessage(v8::Isolate* isolate, Local<Object> exception,
	Local<String> interface_name,
	Local<String> property_name,
	ExceptionContext exception_context)
	: isolate_(isolate),
	exception_(exception),
	interface_name_(interface_name),
	property_name_(property_name),
	exception_context_(exception_context) {}

	V8_INLINE Isolate* GetIsolate() const { return isolate_; }
	V8_INLINE Local<Object> GetException() const { return exception_; }
	V8_INLINE Local<String> GetInterfaceName() const { return interface_name_; }
	V8_INLINE Local<String> GetPropertyName() const { return property_name_; }
	V8_INLINE ExceptionContext GetExceptionContext() const {
	return exception_context_;
	}

	private:
	Isolate* isolate_;
	Local<Object> exception_;
	Local<String> interface_name_;
	Local<String> property_name_;
	ExceptionContext exception_context_;
	};

	using ExceptionPropagationCallback =
	void (*)(ExceptionPropagationMessage message);

	/**
	* An external exception handler.
	*/
	class V8_EXPORT TryCatch {
	public:
	/**
	* Creates a new try/catch block and registers it with v8. Note that
	* all TryCatch blocks should be stack allocated because the memory
	* location itself is compared against JavaScript try/catch blocks.
	*/
	explicit TryCatch(Isolate* isolate);

	/**
	* Unregisters and deletes this try/catch block.
	*/
	~TryCatch();

	/**
	* Returns true if an exception has been caught by this try/catch block.
	*/
	bool HasCaught() const;

	/**
	* For certain types of exceptions, it makes no sense to continue execution.
	*
	* If CanContinue returns false, the correct action is to perform any C++
	* cleanup needed and then return. If CanContinue returns false and
	* HasTerminated returns true, it is possible to call
	* CancelTerminateExecution in order to continue calling into the engine.
	*/
	bool CanContinue() const;

	/**
	* Returns true if an exception has been caught due to script execution
	* being terminated.
	*
	* There is no JavaScript representation of an execution termination
	* exception. Such exceptions are thrown when the TerminateExecution
	* methods are called to terminate a long-running script.
	*
	* If such an exception has been thrown, HasTerminated will return true,
	* indicating that it is possible to call CancelTerminateExecution in order
	* to continue calling into the engine.
	*/
	bool HasTerminated() const;

	/**
	* Throws the exception caught by this TryCatch in a way that avoids
	* it being caught again by this same TryCatch. As with ThrowException
	* it is illegal to execute any JavaScript operations after calling
	* ReThrow; the caller must return immediately to where the exception
	* is caught.
	*/
	Local<Value> ReThrow();

	/**
	* Returns the exception caught by this try/catch block. If no exception has
	* been caught an empty handle is returned.
	*/
	Local<Value> Exception() const;

	/**
	* Returns the .stack property of an object. If no .stack
	* property is present an empty handle is returned.
	*/
	V8_WARN_UNUSED_RESULT static MaybeLocal<Value> StackTrace(
	Local<Context> context, Local<Value> exception);

	/**
	* Returns the .stack property of the thrown object. If no .stack property is
	* present or if this try/catch block has not caught an exception, an empty
	* handle is returned.
	*/
	V8_WARN_UNUSED_RESULT MaybeLocal<Value> StackTrace(
	Local<Context> context) const;

	/**
	* Returns the message associated with this exception. If there is
	* no message associated an empty handle is returned.
	*/
	Local<v8::Message> Message() const;

	/**
	* Clears any exceptions that may have been caught by this try/catch block.
	* After this method has been called, HasCaught() will return false. Cancels
	* the scheduled exception if it is caught and ReThrow() is not called before.
	*
	* It is not necessary to clear a try/catch block before using it again; if
	* another exception is thrown the previously caught exception will just be
	* overwritten. However, it is often a good idea since it makes it easier
	* to determine which operation threw a given exception.
	*/
	void Reset();

	/**
	* Set verbosity of the external exception handler.
	*
	* By default, exceptions that are caught by an external exception
	* handler are not reported. Call SetVerbose with true on an
	* external exception handler to have exceptions caught by the
	* handler reported as if they were not caught.
	*/
	void SetVerbose(bool value);

	/**
	* Returns true if verbosity is enabled.
	*/
	bool IsVerbose() const;

	/**
	* Set whether or not this TryCatch should capture a Message object
	* which holds source information about where the exception
	* occurred. True by default.
	*/
	void SetCaptureMessage(bool value);

	TryCatch(const TryCatch&) = delete;
	void operator=(const TryCatch&) = delete;

	private:
	// Declaring operator new and delete as deleted is not spec compliant.
	// Therefore declare them private instead to disable dynamic alloc
	void* operator new(size_t size);
	void* operator new[](size_t size);
	void operator delete(void*, size_t);
	void operator delete[](void*, size_t);

	/**
	* There are cases when the raw address of C++ TryCatch object cannot be
	* used for comparisons with addresses into the JS stack. The cases are:
	* 1) ARM, ARM64 and MIPS simulators which have separate JS stack.
	* 2) Address sanitizer allocates local C++ object in the heap when
	* UseAfterReturn mode is enabled.
	* This method returns address that can be used for comparisons with
	* addresses into the JS stack. When neither simulator nor ASAN's
	* UseAfterReturn is enabled, then the address returned will be the address
	* of the C++ try catch handler itself.
	*/
	internal::Address JSStackComparableAddressPrivate() {
	return js_stack_comparable_address_;
	}

	void ResetInternal();

	internal::Isolate* i_isolate_;
	TryCatch* next_;
	void* exception_;
	void* message_obj_;
	internal::Address js_stack_comparable_address_;
	bool is_verbose_ : 1;
	bool can_continue_ : 1;
	bool capture_message_ : 1;
	bool rethrow_ : 1;

	friend class internal::Isolate;
	friend class internal::ThreadLocalTop;
	};

	} // namespace v8

	#endif // INCLUDE_V8_EXCEPTION_H_