libv8-node 21.7.2.0-aarch64-linux-musl → 24.12.0.0-aarch64-linux-musl

data/vendor/v8/include/v8-isolate.h

@@ -9,6 +9,7 @@
 #include <stdint.h>
 
 #include <memory>
+#include <string>
 #include <utility>
 
 #include "cppgc/common.h"
@@ -17,6 +18,7 @@
 #include "v8-data.h"               // NOLINT(build/include_directory)
 #include "v8-debug.h"              // NOLINT(build/include_directory)
 #include "v8-embedder-heap.h"      // NOLINT(build/include_directory)
+#include "v8-exception.h"          // NOLINT(build/include_directory)
 #include "v8-function-callback.h"  // NOLINT(build/include_directory)
 #include "v8-internal.h"           // NOLINT(build/include_directory)
 #include "v8-local-handle.h"       // NOLINT(build/include_directory)
@@ -162,28 +164,6 @@ class V8_EXPORT ResourceConstraints {
   uint32_t* stack_limit_ = nullptr;
 };
 
-/**
- * Option flags passed to the SetRAILMode function.
- * See documentation https://developers.google.com/web/tools/chrome-devtools/
- * profile/evaluate-performance/rail
- */
-enum RAILMode : unsigned {
-  // Response performance mode: In this mode very low virtual machine latency
-  // is provided. V8 will try to avoid JavaScript execution interruptions.
-  // Throughput may be throttled.
-  PERFORMANCE_RESPONSE,
-  // Animation performance mode: In this mode low virtual machine latency is
-  // provided. V8 will try to avoid as many JavaScript execution interruptions
-  // as possible. Throughput may be throttled. This is the default mode.
-  PERFORMANCE_ANIMATION,
-  // Idle performance mode: The embedder is idle. V8 can complete deferred work
-  // in this mode.
-  PERFORMANCE_IDLE,
-  // Load performance mode: In this mode high throughput is provided. V8 may
-  // turn off latency optimizations.
-  PERFORMANCE_LOAD
-};
-
 /**
  * Memory pressure level for the MemoryPressureNotification.
  * kNone hints V8 that there is no memory pressure.
@@ -194,11 +174,95 @@ enum RAILMode : unsigned {
  */
 enum class MemoryPressureLevel { kNone, kModerate, kCritical };
 
+/**
+ * Signal for dependants of contexts. Useful for
+ * `ContextDisposedNotification()` to implement different strategies.
+ */
+enum class ContextDependants {
+  /** Context has no dependants. These are usually top-level contexts. */
+  kNoDependants,
+  /** Context has some dependants, i.e., it may depend on other contexts. This
+     is usually the case for inner contexts.  */
+  kSomeDependants
+};
+
 /**
  * Indicator for the stack state.
  */
 using StackState = cppgc::EmbedderStackState;
 
+/**
+ * The set of V8 isolates in a process is partitioned into groups. Each group
+ * has its own sandbox (if V8 was configured with support for the sandbox) and
+ * pointer-compression cage (if configured with pointer compression).
+ *
+ * By default, all isolates are placed in the same group. This is the most
+ * efficient configuration in terms of speed and memory use. However, with
+ * pointer compression enabled, total heap usage of isolates in a group
+ * cannot exceed 4 GB, not counting array buffers and other off-heap storage.
+ * Using multiple isolate groups can allow embedders to allocate more than 4GB
+ * of objects with pointer compression enabled, if the embedder's use case can
+ * span multiple isolates.
+ *
+ * Creating an isolate group reserves a range of virtual memory addresses. A
+ * group's memory mapping will be released when the last isolate in the group is
+ * disposed, and there are no more live IsolateGroup objects that refer to it.
+ *
+ * Note that Isolate groups are reference counted, and
+ * the IsolateGroup type is a reference to one.
+ *
+ * Note that it's not going to be possible to pass shared JS objects
+ * across IsolateGroup boundary.
+ *
+ */
+class V8_EXPORT IsolateGroup {
+ public:
+  /**
+   * Get the default isolate group. If this V8's build configuration only
+   * supports a single group, this is a reference to that single group.
+   * Otherwise this is a group like any other, distinguished only
+   * in that it is the first group.
+   */
+  static IsolateGroup GetDefault();
+
+  /**
+   * Return true if new isolate groups can be created at run-time, or false if
+   * all isolates must be in the same group.
+   */
+  static bool CanCreateNewGroups();
+
+  /**
+   * Create a new isolate group. If this V8's build configuration only supports
+   * a single group, abort.
+   */
+  static IsolateGroup Create();
+
+  IsolateGroup(IsolateGroup&& other);
+  IsolateGroup& operator=(IsolateGroup&& other);
+
+  IsolateGroup(const IsolateGroup&);
+  IsolateGroup& operator=(const IsolateGroup&);
+
+  ~IsolateGroup();
+
+  bool operator==(const IsolateGroup& other) const {
+    return isolate_group_ == other.isolate_group_;
+  }
+
+  bool operator!=(const IsolateGroup& other) const {
+    return !operator==(other);
+  }
+
+ private:
+  friend class Isolate;
+  friend class ArrayBuffer::Allocator;
+
+  // The isolate_group pointer should be already acquired.
+  explicit IsolateGroup(internal::IsolateGroup*&& isolate_group);
+
+  internal::IsolateGroup* isolate_group_;
+};
+
 /**
  * Isolate represents an isolated instance of the V8 engine.  V8 isolates have
  * completely separate states.  Objects from one isolate must not be used in
@@ -276,11 +340,6 @@ class V8_EXPORT Isolate {
      */
     bool allow_atomics_wait = true;
 
-    /**
-     * Termination is postponed when there is no active SafeForTerminationScope.
-     */
-    bool only_terminate_in_safe_scope = false;
-
     /**
      * The following parameters describe the offsets for addressing type info
      * for wrapped API objects and are used by the fast C API
@@ -294,6 +353,12 @@ class V8_EXPORT Isolate {
      */
     FatalErrorCallback fatal_error_callback = nullptr;
     OOMErrorCallback oom_error_callback = nullptr;
+
+    /**
+     * A CppHeap used to construct the Isolate. V8 takes ownership of the
+     * CppHeap passed this way.
+     */
+    CppHeap* cpp_heap = nullptr;
   };
 
   /**
@@ -383,24 +448,6 @@ class V8_EXPORT Isolate {
     friend class internal::ThreadLocalTop;
   };
 
-  /**
-   * This scope allows terminations inside direct V8 API calls and forbid them
-   * inside any recursive API calls without explicit SafeForTerminationScope.
-   */
-  class V8_EXPORT V8_NODISCARD SafeForTerminationScope {
-   public:
-    explicit SafeForTerminationScope(v8::Isolate* v8_isolate);
-    ~SafeForTerminationScope();
-
-    // Prevent copying of Scope objects.
-    SafeForTerminationScope(const SafeForTerminationScope&) = delete;
-    SafeForTerminationScope& operator=(const SafeForTerminationScope&) = delete;
-
-   private:
-    internal::Isolate* i_isolate_;
-    bool prev_value_;
-  };
-
   /**
    * Types of garbage collections that can be requested via
    * RequestGarbageCollectionForTesting.
@@ -421,36 +468,36 @@ class V8_EXPORT Isolate {
   enum UseCounterFeature {
     kUseAsm = 0,
     kBreakIterator = 1,
-    kLegacyConst V8_DEPRECATE_SOON("unused") = 2,
-    kMarkDequeOverflow V8_DEPRECATE_SOON("unused") = 3,
-    kStoreBufferOverflow V8_DEPRECATE_SOON("unused") = 4,
-    kSlotsBufferOverflow V8_DEPRECATE_SOON("unused") = 5,
-    kObjectObserve V8_DEPRECATE_SOON("unused") = 6,
+    kOBSOLETE_LegacyConst = 2,
+    kOBSOLETE_MarkDequeOverflow = 3,
+    kOBSOLETE_StoreBufferOverflow = 4,
+    kOBSOLETE_SlotsBufferOverflow = 5,
+    kOBSOLETE_ObjectObserve = 6,
     kForcedGC = 7,
     kSloppyMode = 8,
     kStrictMode = 9,
-    kStrongMode V8_DEPRECATE_SOON("unused") = 10,
+    kOBSOLETE_StrongMode = 10,
     kRegExpPrototypeStickyGetter = 11,
     kRegExpPrototypeToString = 12,
     kRegExpPrototypeUnicodeGetter = 13,
-    kIntlV8Parse V8_DEPRECATE_SOON("unused") = 14,
-    kIntlPattern V8_DEPRECATE_SOON("unused") = 15,
-    kIntlResolved V8_DEPRECATE_SOON("unused") = 16,
-    kPromiseChain V8_DEPRECATE_SOON("unused") = 17,
-    kPromiseAccept V8_DEPRECATE_SOON("unused") = 18,
-    kPromiseDefer V8_DEPRECATE_SOON("unused") = 19,
+    kOBSOLETE_IntlV8Parse = 14,
+    kOBSOLETE_IntlPattern = 15,
+    kOBSOLETE_IntlResolved = 16,
+    kOBSOLETE_PromiseChain = 17,
+    kOBSOLETE_PromiseAccept = 18,
+    kOBSOLETE_PromiseDefer = 19,
     kHtmlCommentInExternalScript = 20,
     kHtmlComment = 21,
     kSloppyModeBlockScopedFunctionRedefinition = 22,
     kForInInitializer = 23,
-    kArrayProtectorDirtied V8_DEPRECATE_SOON("unused") = 24,
+    kOBSOLETE_ArrayProtectorDirtied = 24,
     kArraySpeciesModified = 25,
     kArrayPrototypeConstructorModified = 26,
-    kArrayInstanceProtoModified V8_DEPRECATE_SOON("unused") = 27,
+    kOBSOLETE_ArrayInstanceProtoModified = 27,
     kArrayInstanceConstructorModified = 28,
-    kLegacyFunctionDeclaration V8_DEPRECATE_SOON("unused") = 29,
-    kRegExpPrototypeSourceGetter V8_DEPRECATE_SOON("unused") = 30,
-    kRegExpPrototypeOldFlagGetter V8_DEPRECATE_SOON("unused") = 31,
+    kOBSOLETE_LegacyFunctionDeclaration = 29,
+    kOBSOLETE_RegExpPrototypeSourceGetter = 30,
+    kOBSOLETE_RegExpPrototypeOldFlagGetter = 31,
     kDecimalWithLeadingZeroInStrictMode = 32,
     kLegacyDateParser = 33,
     kDefineGetterOrSetterWouldThrow = 34,
@@ -458,22 +505,21 @@ class V8_EXPORT Isolate {
     kAssigmentExpressionLHSIsCallInSloppy = 36,
     kAssigmentExpressionLHSIsCallInStrict = 37,
     kPromiseConstructorReturnedUndefined = 38,
-    kConstructorNonUndefinedPrimitiveReturn V8_DEPRECATE_SOON("unused") = 39,
-    kLabeledExpressionStatement V8_DEPRECATE_SOON("unused") = 40,
-    kLineOrParagraphSeparatorAsLineTerminator V8_DEPRECATE_SOON("unused") = 41,
+    kOBSOLETE_ConstructorNonUndefinedPrimitiveReturn = 39,
+    kOBSOLETE_LabeledExpressionStatement = 40,
+    kOBSOLETE_LineOrParagraphSeparatorAsLineTerminator = 41,
     kIndexAccessor = 42,
     kErrorCaptureStackTrace = 43,
     kErrorPrepareStackTrace = 44,
     kErrorStackTraceLimit = 45,
     kWebAssemblyInstantiation = 46,
     kDeoptimizerDisableSpeculation = 47,
-    kArrayPrototypeSortJSArrayModifiedPrototype V8_DEPRECATE_SOON("unused") =
-        48,
+    kOBSOLETE_ArrayPrototypeSortJSArrayModifiedPrototype = 48,
     kFunctionTokenOffsetTooLongForToString = 49,
     kWasmSharedMemory = 50,
     kWasmThreadOpcodes = 51,
-    kAtomicsNotify V8_DEPRECATE_SOON("unused") = 52,
-    kAtomicsWake V8_DEPRECATE_SOON("unused") = 53,
+    kOBSOLETE_AtomicsNotify = 52,
+    kOBSOLETE_AtomicsWake = 53,
     kCollator = 54,
     kNumberFormat = 55,
     kDateTimeFormat = 56,
@@ -483,7 +529,7 @@ class V8_EXPORT Isolate {
     kListFormat = 60,
     kSegmenter = 61,
     kStringLocaleCompare = 62,
-    kStringToLocaleUpperCase V8_DEPRECATE_SOON("unused") = 63,
+    kOBSOLETE_StringToLocaleUpperCase = 63,
     kStringToLocaleLowerCase = 64,
     kNumberToLocaleString = 65,
     kDateToLocaleString = 66,
@@ -491,14 +537,14 @@ class V8_EXPORT Isolate {
     kDateToLocaleTimeString = 68,
     kAttemptOverrideReadOnlyOnPrototypeSloppy = 69,
     kAttemptOverrideReadOnlyOnPrototypeStrict = 70,
-    kOptimizedFunctionWithOneShotBytecode V8_DEPRECATE_SOON("unused") = 71,
+    kOBSOLETE_OptimizedFunctionWithOneShotBytecode = 71,
     kRegExpMatchIsTrueishOnNonJSRegExp = 72,
     kRegExpMatchIsFalseishOnJSRegExp = 73,
-    kDateGetTimezoneOffset V8_DEPRECATE_SOON("unused") = 74,
+    kOBSOLETE_DateGetTimezoneOffset = 74,
     kStringNormalize = 75,
     kCallSiteAPIGetFunctionSloppyCall = 76,
     kCallSiteAPIGetThisSloppyCall = 77,
-    kRegExpMatchAllWithNonGlobalRegExp V8_DEPRECATE_SOON("unused") = 78,
+    kOBSOLETE_RegExpMatchAllWithNonGlobalRegExp = 78,
     kRegExpExecCalledOnSlowRegExp = 79,
     kRegExpReplaceCalledOnSlowRegExp = 80,
     kDisplayNames = 81,
@@ -529,10 +575,8 @@ class V8_EXPORT Isolate {
     kWasmSimdOpcodes = 106,
     kVarRedeclaredCatchBinding = 107,
     kWasmRefTypes = 108,
-    kWasmBulkMemory V8_DEPRECATE_SOON(
-        "Unused since 2021 (https://crrev.com/c/2622913)") = 109,
-    kWasmMultiValue V8_DEPRECATE_SOON(
-        "Unused since 2021 (https://crrev.com/c/2817790)") = 110,
+    kOBSOLETE_WasmBulkMemory = 109,
+    kOBSOLETE_WasmMultiValue = 110,
     kWasmExceptionHandling = 111,
     kInvalidatedMegaDOMProtector = 112,
     kFunctionPrototypeArguments = 113,
@@ -541,9 +585,8 @@ class V8_EXPORT Isolate {
     kAsyncStackTaggingCreateTaskCall = 116,
     kDurationFormat = 117,
     kInvalidatedNumberStringNotRegexpLikeProtector = 118,
-    kRegExpUnicodeSetIncompatibilitiesWithUnicodeMode V8_DEPRECATE_SOON(
-        "unused") = 119,
-    kImportAssertionDeprecatedSyntax = 120,
+    kOBSOLETE_RegExpUnicodeSetIncompatibilitiesWithUnicodeMode = 119,
+    kOBSOLETE_ImportAssertionDeprecatedSyntax = 120,
     kLocaleInfoObsoletedGetters = 121,
     kLocaleInfoFunctions = 122,
     kCompileHintsMagicAll = 123,
@@ -551,6 +594,46 @@ class V8_EXPORT Isolate {
     kWasmMemory64 = 125,
     kWasmMultiMemory = 126,
     kWasmGC = 127,
+    kWasmImportedStrings = 128,
+    kSourceMappingUrlMagicCommentAtSign = 129,
+    kTemporalObject = 130,
+    kWasmModuleCompilation = 131,
+    kInvalidatedNoUndetectableObjectsProtector = 132,
+    kWasmJavaScriptPromiseIntegration = 133,
+    kWasmReturnCall = 134,
+    kWasmExtendedConst = 135,
+    kWasmRelaxedSimd = 136,
+    kWasmTypeReflection = 137,
+    kWasmExnRef = 138,
+    kWasmTypedFuncRef = 139,
+    kInvalidatedStringWrapperToPrimitiveProtector = 140,
+    kDocumentAllLegacyCall = 141,
+    kDocumentAllLegacyConstruct = 142,
+    kConsoleContext = 143,
+    kWasmImportedStringsUtf8 = 144,
+    kResizableArrayBuffer = 145,
+    kGrowableSharedArrayBuffer = 146,
+    kArrayByCopy = 147,
+    kArrayFromAsync = 148,
+    kIteratorMethods = 149,
+    kPromiseAny = 150,
+    kSetMethods = 151,
+    kArrayFindLast = 152,
+    kArrayGroup = 153,
+    kArrayBufferTransfer = 154,
+    kPromiseWithResolvers = 155,
+    kAtomicsWaitAsync = 156,
+    kExtendingNonExtensibleWithPrivate = 157,
+    kPromiseTry = 158,
+    kStringReplaceAll = 159,
+    kStringWellFormed = 160,
+    kWeakReferences = 161,
+    kErrorIsError = 162,
+    kInvalidatedTypedArrayLengthLookupChainProtector = 163,
+    kRegExpEscape = 164,
+    kFloat16Array = 165,
+    kExplicitResourceManagement = 166,
+    kWasmBranchHinting = 167,
 
     // If you add new values here, you'll also need to update Chromium's:
     // web_feature.mojom, use_counter_callback.cc, and enums.xml. V8 changes to
@@ -568,6 +651,21 @@ class V8_EXPORT Isolate {
                   kMessageWarning,
   };
 
+  // The different priorities that an isolate can have.
+  enum class Priority {
+    // The isolate does not relate to content that is currently important
+    // to the user. Lowest priority.
+    kBestEffort,
+
+    // The isolate contributes to content that is visible to the user, like a
+    // visible iframe that's not interacted directly with. High priority.
+    kUserVisible,
+
+    // The isolate contributes to content that is of the utmost importance to
+    // the user, like visible content in the focused window. Highest priority.
+    kUserBlocking,
+  };
+
   using UseCounterCallback = void (*)(Isolate* isolate,
                                       UseCounterFeature feature);
 
@@ -576,9 +674,9 @@ class V8_EXPORT Isolate {
    * currently entered isolate.
    *
    * Only Isolate::GetData() and Isolate::SetData(), which access the
-   * embedder-controlled parts of the isolate, are allowed to be called on the
-   * uninitialized isolate. To initialize the isolate, call
-   * Isolate::Initialize().
+   * embedder-controlled parts of the isolate, as well as Isolate::GetGroup(),
+   * are allowed to be called on the uninitialized isolate. To initialize the
+   * isolate, call `Isolate::Initialize()` or initialize a `SnapshotCreator`.
    *
    * When an isolate is no longer used its resources should be freed
    * by calling Dispose().  Using the delete operator is not allowed.
@@ -586,6 +684,12 @@ class V8_EXPORT Isolate {
    * V8::Initialize() must have run prior to this.
    */
   static Isolate* Allocate();
+  static Isolate* Allocate(const IsolateGroup& group);
+
+  /**
+   * Return the group for this isolate.
+   */
+  IsolateGroup GetGroup() const;
 
   /**
    * Initialize an Isolate previously allocated by Isolate::Allocate().
@@ -602,6 +706,7 @@ class V8_EXPORT Isolate {
    * V8::Initialize() must have run prior to this.
    */
   static Isolate* New(const CreateParams& params);
+  static Isolate* New(const IsolateGroup& group, const CreateParams& params);
 
   /**
    * Returns the entered isolate for the current thread or NULL in
@@ -659,6 +764,18 @@ class V8_EXPORT Isolate {
   void SetHostImportModuleDynamicallyCallback(
       HostImportModuleDynamicallyCallback callback);
 
+  /**
+   * This specifies the callback called by the upcoming dynamic
+   * import() and import.source() language feature to load modules.
+   *
+   * This API is experimental and is expected to be changed or removed in the
+   * future. The callback is currently only called when for source-phase
+   * imports. Evaluation-phase imports use the existing
+   * HostImportModuleDynamicallyCallback callback.
+   */
+  void SetHostImportModuleWithPhaseDynamicallyCallback(
+      HostImportModuleWithPhaseDynamicallyCallback callback);
+
   /**
    * This specifies the callback called by the upcoming import.meta
    * language feature to retrieve host-defined meta data for a module.
@@ -673,17 +790,33 @@ class V8_EXPORT Isolate {
   void SetHostCreateShadowRealmContextCallback(
       HostCreateShadowRealmContextCallback callback);
 
+  /**
+   * Set the callback that checks whether a Error.isError should return true for
+   * a JSApiWrapper object, i.e. whether it represents a native JS error. For
+   * example, in an HTML embedder, DOMExceptions are considered native errors.
+   */
+  void SetIsJSApiWrapperNativeErrorCallback(
+      IsJSApiWrapperNativeErrorCallback callback);
+
   /**
    * This specifies the callback called when the stack property of Error
    * is accessed.
    */
   void SetPrepareStackTraceCallback(PrepareStackTraceCallback callback);
 
+  /**
+   * Get the stackTraceLimit property of Error.
+   */
+  int GetStackTraceLimit();
+
 #if defined(V8_OS_WIN)
   /**
    * This specifies the callback called when an ETW tracing session starts.
    */
+  V8_DEPRECATE_SOON("Use SetFilterETWSessionByURL2Callback instead")
   void SetFilterETWSessionByURLCallback(FilterETWSessionByURLCallback callback);
+  void SetFilterETWSessionByURL2Callback(
+      FilterETWSessionByURL2Callback callback);
 #endif  // V8_OS_WIN
 
   /**
@@ -694,6 +827,22 @@ class V8_EXPORT Isolate {
    */
   void MemoryPressureNotification(MemoryPressureLevel level);
 
+  /**
+   * Optional request from the embedder to tune v8 towards energy efficiency
+   * rather than speed if `battery_saver_mode_enabled` is true, because the
+   * embedder is in battery saver mode. If false, the correct tuning is left
+   * to v8 to decide.
+   */
+  void SetBatterySaverMode(bool battery_saver_mode_enabled);
+
+  /**
+   * Optional request from the embedder to tune v8 towards memory efficiency
+   * rather than speed if `memory_saver_mode_enabled` is true, because the
+   * embedder is in memory saver mode. If false, the correct tuning is left
+   * to v8 to decide.
+   */
+  void SetMemorySaverMode(bool memory_saver_mode_enabled);
+
   /**
    * Drop non-essential caches. Should only be called from testing code.
    * The method can potentially block for a long time and does not necessarily
@@ -723,11 +872,26 @@ class V8_EXPORT Isolate {
   void Exit();
 
   /**
-   * Disposes the isolate.  The isolate must not be entered by any
+   * Deinitializes and frees the isolate. The isolate must not be entered by any
    * thread to be disposable.
    */
   void Dispose();
 
+  /**
+   * Deinitializes the isolate, but does not free the address. The isolate must
+   * not be entered by any thread to be deinitializable. Embedders must call
+   * Isolate::Free() to free the isolate afterwards.
+   */
+  void Deinitialize();
+
+  /**
+   * Frees the memory allocated for the isolate. Can only be called after the
+   * Isolate has already been deinitialized with Isolate::Deinitialize(). After
+   * the isolate is freed, the next call to Isolate::New() or
+   * Isolate::Allocate() might return the same address that just get freed.
+   */
+  static void Free(Isolate* isolate);
+
   /**
    * Dumps activated low-level V8 internal stats. This can be used instead
    * of performing a full isolate disposal.
@@ -769,6 +933,18 @@ class V8_EXPORT Isolate {
   template <class T>
   V8_INLINE MaybeLocal<T> GetDataFromSnapshotOnce(size_t index);
 
+  /**
+   * Returns the value that was set or restored by
+   * SetContinuationPreservedEmbedderData(), if any.
+   */
+  Local<Value> GetContinuationPreservedEmbedderData();
+
+  /**
+   * Sets a value that will be stored on continuations and reset while the
+   * continuation runs.
+   */
+  void SetContinuationPreservedEmbedderData(Local<Value> data);
+
   /**
    * Get statistics about the heap memory usage.
    */
@@ -849,18 +1025,13 @@ class V8_EXPORT Isolate {
                       size_t frames_limit, SampleInfo* sample_info);
 
   /**
-   * Adjusts the amount of registered external memory. Used to give V8 an
-   * indication of the amount of externally allocated memory that is kept alive
-   * by JavaScript objects. V8 uses this to decide when to perform global
-   * garbage collections. Registering externally allocated memory will trigger
-   * global garbage collections more often than it would otherwise in an attempt
-   * to garbage collect the JavaScript objects that keep the externally
-   * allocated memory alive.
+   * Adjusts the amount of registered external memory.
    *
    * \param change_in_bytes the change in externally allocated memory that is
    *   kept alive by JavaScript objects.
    * \returns the adjusted value.
    */
+  V8_DEPRECATE_SOON("Use ExternalMemoryAccounter instead.")
   int64_t AdjustAmountOfExternalAllocatedMemory(int64_t change_in_bytes);
 
   /**
@@ -900,6 +1071,12 @@ class V8_EXPORT Isolate {
    */
   Local<Context> GetIncumbentContext();
 
+  /**
+   * Returns the host defined options set for currently running script or
+   * module, if available.
+   */
+  MaybeLocal<Data> GetCurrentHostDefinedOptions();
+
   /**
    * Schedules a v8::Exception::Error with the given message.
    * See ThrowException for more details. Templatized to provide compile-time
@@ -919,6 +1096,14 @@ class V8_EXPORT Isolate {
    */
   Local<Value> ThrowException(Local<Value> exception);
 
+  /**
+   * Returns true if an exception was thrown but not processed yet by an
+   * exception handler on JavaScript side or by v8::TryCatch handler.
+   *
+   * This is an experimental feature and may still change significantly.
+   */
+  bool HasPendingException();
+
   using GCCallback = void (*)(Isolate* isolate, GCType type,
                               GCCallbackFlags flags);
   using GCCallbackWithData = void (*)(Isolate* isolate, GCType type,
@@ -1002,20 +1187,14 @@ class V8_EXPORT Isolate {
    */
   void SetEmbedderRootsHandler(EmbedderRootsHandler* handler);
 
-  /**
-   * Attaches a managed C++ heap as an extension to the JavaScript heap. The
-   * embedder maintains ownership of the CppHeap. At most one C++ heap can be
-   * attached to V8.
-   *
-   * Multi-threaded use requires the use of v8::Locker/v8::Unlocker, see
-   * CppHeap.
-   */
-  void AttachCppHeap(CppHeap*);
+  using ReleaseCppHeapCallback = void (*)(std::unique_ptr<CppHeap>);
 
   /**
-   * Detaches a managed C++ heap if one was attached using `AttachCppHeap()`.
+   * Sets a callback on the isolate that gets called when the CppHeap gets
+   * detached. The callback can then either take ownership of the CppHeap, or
+   * the CppHeap gets deallocated.
    */
-  void DetachCppHeap();
+  void SetReleaseCppHeapCallbackForTesting(ReleaseCppHeapCallback callback);
 
   /**
    * \returns the C++ heap managed by V8. Only available if such a heap has been
@@ -1023,85 +1202,6 @@ class V8_EXPORT Isolate {
    */
   CppHeap* GetCppHeap() const;
 
-  /**
-   * Use for |AtomicsWaitCallback| to indicate the type of event it receives.
-   */
-  enum class AtomicsWaitEvent {
-    /** Indicates that this call is happening before waiting. */
-    kStartWait,
-    /** `Atomics.wait()` finished because of an `Atomics.wake()` call. */
-    kWokenUp,
-    /** `Atomics.wait()` finished because it timed out. */
-    kTimedOut,
-    /** `Atomics.wait()` was interrupted through |TerminateExecution()|. */
-    kTerminatedExecution,
-    /** `Atomics.wait()` was stopped through |AtomicsWaitWakeHandle|. */
-    kAPIStopped,
-    /** `Atomics.wait()` did not wait, as the initial condition was not met. */
-    kNotEqual
-  };
-
-  /**
-   * Passed to |AtomicsWaitCallback| as a means of stopping an ongoing
-   * `Atomics.wait` call.
-   */
-  class V8_EXPORT AtomicsWaitWakeHandle {
-   public:
-    /**
-     * Stop this `Atomics.wait()` call and call the |AtomicsWaitCallback|
-     * with |kAPIStopped|.
-     *
-     * This function may be called from another thread. The caller has to ensure
-     * through proper synchronization that it is not called after
-     * the finishing |AtomicsWaitCallback|.
-     *
-     * Note that the ECMAScript specification does not plan for the possibility
-     * of wakeups that are neither coming from a timeout or an `Atomics.wake()`
-     * call, so this may invalidate assumptions made by existing code.
-     * The embedder may accordingly wish to schedule an exception in the
-     * finishing |AtomicsWaitCallback|.
-     */
-    void Wake();
-  };
-
-  /**
-   * Embedder callback for `Atomics.wait()` that can be added through
-   * |SetAtomicsWaitCallback|.
-   *
-   * This will be called just before starting to wait with the |event| value
-   * |kStartWait| and after finishing waiting with one of the other
-   * values of |AtomicsWaitEvent| inside of an `Atomics.wait()` call.
-   *
-   * |array_buffer| will refer to the underlying SharedArrayBuffer,
-   * |offset_in_bytes| to the location of the waited-on memory address inside
-   * the SharedArrayBuffer.
-   *
-   * |value| and |timeout_in_ms| will be the values passed to
-   * the `Atomics.wait()` call. If no timeout was used, |timeout_in_ms|
-   * will be `INFINITY`.
-   *
-   * In the |kStartWait| callback, |stop_handle| will be an object that
-   * is only valid until the corresponding finishing callback and that
-   * can be used to stop the wait process while it is happening.
-   *
-   * This callback may schedule exceptions, *unless* |event| is equal to
-   * |kTerminatedExecution|.
-   */
-  using AtomicsWaitCallback = void (*)(AtomicsWaitEvent event,
-                                       Local<SharedArrayBuffer> array_buffer,
-                                       size_t offset_in_bytes, int64_t value,
-                                       double timeout_in_ms,
-                                       AtomicsWaitWakeHandle* stop_handle,
-                                       void* data);
-
-  /**
-   * Set a new |AtomicsWaitCallback|. This overrides an earlier
-   * |AtomicsWaitCallback|, if there was any. If |callback| is nullptr,
-   * this unsets the callback. |data| will be passed to the callback
-   * as its last parameter.
-   */
-  void SetAtomicsWaitCallback(AtomicsWaitCallback callback, void* data);
-
   using GetExternallyAllocatedMemoryInBytesCallback = size_t (*)();
 
   /**
@@ -1233,6 +1333,15 @@ class V8_EXPORT Isolate {
    */
   void SetPromiseRejectCallback(PromiseRejectCallback callback);
 
+  /**
+   * This is a part of experimental Api and might be changed without further
+   * notice.
+   * Do not use it.
+   *
+   * Set callback to notify about a new exception being thrown.
+   */
+  void SetExceptionPropagationCallback(ExceptionPropagationCallback callback);
+
   /**
    * Runs the default MicrotaskQueue until it gets empty and perform other
    * microtask checkpoint steps, such as calling ClearKeptObjects. Asserts that
@@ -1322,24 +1431,6 @@ class V8_EXPORT Isolate {
    */
   void SetAddCrashKeyCallback(AddCrashKeyCallback);
 
-  /**
-   * Optional notification that the embedder is idle.
-   * V8 uses the notification to perform garbage collection.
-   * This call can be used repeatedly if the embedder remains idle.
-   * Returns true if the embedder should stop calling IdleNotificationDeadline
-   * until real work has been done.  This indicates that V8 has done
-   * as much cleanup as it will be able to do.
-   *
-   * The deadline_in_seconds argument specifies the deadline V8 has to finish
-   * garbage collection work. deadline_in_seconds is compared with
-   * MonotonicallyIncreasingTime() and should be based on the same timebase as
-   * that function. There is no guarantee that the actual work will be done
-   * within the time limit.
-   */
-  V8_DEPRECATE_SOON(
-      "Use MemoryPressureNotification() to influence the GC schedule.")
-  bool IdleNotificationDeadline(double deadline_in_seconds);
-
   /**
    * Optional notification that the system is running low on memory.
    * V8 uses these notifications to attempt to free memory.
@@ -1355,33 +1446,59 @@ class V8_EXPORT Isolate {
    * The optional parameter |dependant_context| specifies whether the disposed
    * context was depending on state from other contexts or not.
    */
+  V8_DEPRECATE_SOON("Use version that passes ContextDependants.")
   int ContextDisposedNotification(bool dependant_context = true);
 
+  /**
+   * Optional notification that a context has been disposed. V8 uses these
+   * notifications to guide heuristics on e.g. GC or compilers.
+   *
+   * \param dependants A signal on whether this context possibly had any
+   *     dependants.
+   */
+  void ContextDisposedNotification(ContextDependants dependants);
+
   /**
    * Optional notification that the isolate switched to the foreground.
    * V8 uses these notifications to guide heuristics.
    */
+  V8_DEPRECATE_SOON("Use SetPriority(Priority::kUserBlocking) instead")
   void IsolateInForegroundNotification();
 
   /**
    * Optional notification that the isolate switched to the background.
    * V8 uses these notifications to guide heuristics.
    */
+  V8_DEPRECATE_SOON("Use SetPriority(Priority::kBestEffort) instead")
   void IsolateInBackgroundNotification();
 
   /**
-   * Optional notification to tell V8 the current performance requirements
-   * of the embedder based on RAIL.
+   * Optional notification that the isolate changed `priority`.
+   * V8 uses the priority value to guide heuristics.
+   */
+  void SetPriority(Priority priority);
+
+  /**
+   * Optional notification to tell V8 whether the embedder is currently loading
+   * resources. If the embedder uses this notification, it should call
+   * SetIsLoading(true) when loading starts and SetIsLoading(false) when it
+   * ends.
+   * It's valid to call SetIsLoading(true) again while loading, which will
+   * update the timestamp when V8 considers the load started. Calling
+   * SetIsLoading(false) while not loading does nothing.
    * V8 uses these notifications to guide heuristics.
    * This is an unfinished experimental feature. Semantics and implementation
    * may change frequently.
    */
-  void SetRAILMode(RAILMode rail_mode);
+  void SetIsLoading(bool is_loading);
 
   /**
-   * Update load start time of the RAIL mode
+   * Optional notification to tell V8 whether the embedder is currently frozen.
+   * V8 uses these notifications to guide heuristics.
+   * This is an unfinished experimental feature. Semantics and implementation
+   * may change frequently.
    */
-  void UpdateLoadStartTime();
+  void Freeze(bool is_frozen);
 
   /**
    * Optional notification to tell V8 the current isolate is used for debugging
@@ -1540,23 +1657,21 @@ class V8_EXPORT Isolate {
 
   void SetWasmLoadSourceMapCallback(WasmLoadSourceMapCallback callback);
 
-  /**
-   * Register callback to control whether Wasm GC is enabled.
-   * The callback overwrites the value of the flag.
-   * If the callback returns true, it will also enable Wasm stringrefs.
-   */
-  void SetWasmGCEnabledCallback(WasmGCEnabledCallback callback);
-
   void SetWasmImportedStringsEnabledCallback(
       WasmImportedStringsEnabledCallback callback);
 
   void SetSharedArrayBufferConstructorEnabledCallback(
       SharedArrayBufferConstructorEnabledCallback callback);
 
+  void SetWasmJSPIEnabledCallback(WasmJSPIEnabledCallback callback);
+
   /**
    * Register callback to control whether compile hints magic comments are
    * enabled.
    */
+  V8_DEPRECATED(
+      "Will be removed, use ScriptCompiler::CompileOptions for enabling the "
+      "compile hints magic comments")
   void SetJavaScriptCompileHintsMagicEnabledCallback(
       JavaScriptCompileHintsMagicEnabledCallback callback);
 
@@ -1616,14 +1731,6 @@ class V8_EXPORT Isolate {
       bool capture, int frame_limit = 10,
       StackTrace::StackTraceOptions options = StackTrace::kOverview);
 
-  /**
-   * Iterates through all external resources referenced from current isolate
-   * heap.  GC is not invoked prior to iterating, therefore there is no
-   * guarantee that visited objects are still alive.
-   */
-  V8_DEPRECATE_SOON("Will be removed without replacement. crbug.com/v8/14172")
-  void VisitExternalResources(ExternalResourceVisitor* visitor);
-
   /**
    * Check if this isolate is in use.
    * True if at least one thread Enter'ed this isolate.
@@ -1676,6 +1783,17 @@ class V8_EXPORT Isolate {
    */
   void LocaleConfigurationChangeNotification();
 
+  /**
+   * Returns the default locale in a string if Intl support is enabled.
+   * Otherwise returns an empty string.
+   */
+  std::string GetDefaultLocale();
+
+  /**
+   * Returns the hash seed for that isolate, for testing purposes.
+   */
+  uint64_t GetHashSeed();
+
   Isolate() = delete;
   ~Isolate() = delete;
   Isolate(const Isolate&) = delete;
@@ -1690,9 +1808,12 @@ class V8_EXPORT Isolate {
  private:
   template <class K, class V, class Traits>
   friend class PersistentValueMapBase;
+  friend class ExternalMemoryAccounter;
 
-  internal::Address* GetDataFromSnapshotOnce(size_t index);
-  void ReportExternalAllocationLimitReached();
+  internal::ValueHelper::InternalRepresentationType GetDataFromSnapshotOnce(
+      size_t index);
+  int64_t AdjustAmountOfExternalAllocatedMemoryImpl(int64_t change_in_bytes);
+  void HandleExternalMemoryInterrupt();
 };
 
 void Isolate::SetData(uint32_t slot, void* data) {
@@ -1712,12 +1833,12 @@ uint32_t Isolate::GetNumberOfDataSlots() {
 
 template <class T>
 MaybeLocal<T> Isolate::GetDataFromSnapshotOnce(size_t index) {
-  auto slot = GetDataFromSnapshotOnce(index);
-  if (slot) {
-    internal::PerformCastCheck(
-        internal::ValueHelper::SlotAsValue<T, false>(slot));
+  if (auto repr = GetDataFromSnapshotOnce(index);
+      repr != internal::ValueHelper::kEmpty) {
+    internal::PerformCastCheck(internal::ValueHelper::ReprAsValue<T>(repr));
+    return Local<T>::FromRepr(repr);
   }
-  return Local<T>::FromSlot(slot);
+  return {};
 }
 
 }  // namespace v8