v8  10.1.124 (node 18.2.0)
V8 is Google's open source JavaScript engine
v8-isolate.h
Go to the documentation of this file.
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 
5 #ifndef INCLUDE_V8_ISOLATE_H_
6 #define INCLUDE_V8_ISOLATE_H_
7 
8 #include <stddef.h>
9 #include <stdint.h>
10 
11 #include <memory>
12 #include <utility>
13 
14 #include "cppgc/common.h"
15 #include "v8-array-buffer.h" // NOLINT(build/include_directory)
16 #include "v8-callbacks.h" // NOLINT(build/include_directory)
17 #include "v8-data.h" // NOLINT(build/include_directory)
18 #include "v8-debug.h" // NOLINT(build/include_directory)
19 #include "v8-embedder-heap.h" // NOLINT(build/include_directory)
20 #include "v8-function-callback.h" // NOLINT(build/include_directory)
21 #include "v8-internal.h" // NOLINT(build/include_directory)
22 #include "v8-local-handle.h" // NOLINT(build/include_directory)
23 #include "v8-microtask.h" // NOLINT(build/include_directory)
24 #include "v8-persistent-handle.h" // NOLINT(build/include_directory)
25 #include "v8-primitive.h" // NOLINT(build/include_directory)
26 #include "v8-statistics.h" // NOLINT(build/include_directory)
27 #include "v8-unwinder.h" // NOLINT(build/include_directory)
28 #include "v8config.h" // NOLINT(build/include_directory)
29 
30 namespace v8 {
31 
32 class CppHeap;
33 class HeapProfiler;
34 class MicrotaskQueue;
35 class StartupData;
36 class ScriptOrModule;
37 class SharedArrayBuffer;
38 
39 namespace internal {
40 class MicrotaskQueue;
41 class ThreadLocalTop;
42 } // namespace internal
43 
44 namespace metrics {
45 class Recorder;
46 } // namespace metrics
47 
48 /**
49  * A set of constraints that specifies the limits of the runtime's memory use.
50  * You must set the heap size before initializing the VM - the size cannot be
51  * adjusted after the VM is initialized.
52  *
53  * If you are using threads then you should hold the V8::Locker lock while
54  * setting the stack limit and you must set a non-default stack limit separately
55  * for each thread.
56  *
57  * The arguments for set_max_semi_space_size, set_max_old_space_size,
58  * set_max_executable_size, set_code_range_size specify limits in MB.
59  *
60  * The argument for set_max_semi_space_size_in_kb is in KB.
61  */
63  public:
64  /**
65  * Configures the constraints with reasonable default values based on the
66  * provided heap size limit. The heap size includes both the young and
67  * the old generation.
68  *
69  * \param initial_heap_size_in_bytes The initial heap size or zero.
70  * By default V8 starts with a small heap and dynamically grows it to
71  * match the set of live objects. This may lead to ineffective
72  * garbage collections at startup if the live set is large.
73  * Setting the initial heap size avoids such garbage collections.
74  * Note that this does not affect young generation garbage collections.
75  *
76  * \param maximum_heap_size_in_bytes The hard limit for the heap size.
77  * When the heap size approaches this limit, V8 will perform series of
78  * garbage collections and invoke the NearHeapLimitCallback. If the garbage
79  * collections do not help and the callback does not increase the limit,
80  * then V8 will crash with V8::FatalProcessOutOfMemory.
81  */
82  void ConfigureDefaultsFromHeapSize(size_t initial_heap_size_in_bytes,
83  size_t maximum_heap_size_in_bytes);
84 
85  /**
86  * Configures the constraints with reasonable default values based on the
87  * capabilities of the current device the VM is running on.
88  *
89  * \param physical_memory The total amount of physical memory on the current
90  * device, in bytes.
91  * \param virtual_memory_limit The amount of virtual memory on the current
92  * device, in bytes, or zero, if there is no limit.
93  */
94  void ConfigureDefaults(uint64_t physical_memory,
95  uint64_t virtual_memory_limit);
96 
97  /**
98  * The address beyond which the VM's stack may not grow.
99  */
100  uint32_t* stack_limit() const { return stack_limit_; }
101  void set_stack_limit(uint32_t* value) { stack_limit_ = value; }
102 
103  /**
104  * The amount of virtual memory reserved for generated code. This is relevant
105  * for 64-bit architectures that rely on code range for calls in code.
106  *
107  * When V8_COMPRESS_POINTERS_IN_SHARED_CAGE is defined, there is a shared
108  * process-wide code range that is lazily initialized. This value is used to
109  * configure that shared code range when the first Isolate is
110  * created. Subsequent Isolates ignore this value.
111  */
112  size_t code_range_size_in_bytes() const { return code_range_size_; }
113  void set_code_range_size_in_bytes(size_t limit) { code_range_size_ = limit; }
114 
115  /**
116  * The maximum size of the old generation.
117  * When the old generation approaches this limit, V8 will perform series of
118  * garbage collections and invoke the NearHeapLimitCallback.
119  * If the garbage collections do not help and the callback does not
120  * increase the limit, then V8 will crash with V8::FatalProcessOutOfMemory.
121  */
123  return max_old_generation_size_;
124  }
126  max_old_generation_size_ = limit;
127  }
128 
129  /**
130  * The maximum size of the young generation, which consists of two semi-spaces
131  * and a large object space. This affects frequency of Scavenge garbage
132  * collections and should be typically much smaller that the old generation.
133  */
135  return max_young_generation_size_;
136  }
138  max_young_generation_size_ = limit;
139  }
140 
142  return initial_old_generation_size_;
143  }
144  void set_initial_old_generation_size_in_bytes(size_t initial_size) {
145  initial_old_generation_size_ = initial_size;
146  }
147 
149  return initial_young_generation_size_;
150  }
151  void set_initial_young_generation_size_in_bytes(size_t initial_size) {
152  initial_young_generation_size_ = initial_size;
153  }
154 
155  private:
156  static constexpr size_t kMB = 1048576u;
157  size_t code_range_size_ = 0;
158  size_t max_old_generation_size_ = 0;
159  size_t max_young_generation_size_ = 0;
160  size_t initial_old_generation_size_ = 0;
161  size_t initial_young_generation_size_ = 0;
162  uint32_t* stack_limit_ = nullptr;
163 };
164 
165 /**
166  * Option flags passed to the SetRAILMode function.
167  * See documentation https://developers.google.com/web/tools/chrome-devtools/
168  * profile/evaluate-performance/rail
169  */
170 enum RAILMode : unsigned {
171  // Response performance mode: In this mode very low virtual machine latency
172  // is provided. V8 will try to avoid JavaScript execution interruptions.
173  // Throughput may be throttled.
175  // Animation performance mode: In this mode low virtual machine latency is
176  // provided. V8 will try to avoid as many JavaScript execution interruptions
177  // as possible. Throughput may be throttled. This is the default mode.
179  // Idle performance mode: The embedder is idle. V8 can complete deferred work
180  // in this mode.
182  // Load performance mode: In this mode high throughput is provided. V8 may
183  // turn off latency optimizations.
185 };
186 
187 /**
188  * Memory pressure level for the MemoryPressureNotification.
189  * kNone hints V8 that there is no memory pressure.
190  * kModerate hints V8 to speed up incremental garbage collection at the cost of
191  * of higher latency due to garbage collection pauses.
192  * kCritical hints V8 to free memory as soon as possible. Garbage collection
193  * pauses at this level will be large.
194  */
196 
197 /**
198  * Isolate represents an isolated instance of the V8 engine. V8 isolates have
199  * completely separate states. Objects from one isolate must not be used in
200  * other isolates. The embedder can create multiple isolates and use them in
201  * parallel in multiple threads. An isolate can be entered by at most one
202  * thread at any given time. The Locker/Unlocker API must be used to
203  * synchronize.
204  */
206  public:
207  /**
208  * Initial configuration parameters for a new Isolate.
209  */
213 
214  /**
215  * Allows the host application to provide the address of a function that is
216  * notified each time code is added, moved or removed.
217  */
218  JitCodeEventHandler code_event_handler = nullptr;
219 
220  /**
221  * ResourceConstraints to use for the new Isolate.
222  */
224 
225  /**
226  * Explicitly specify a startup snapshot blob. The embedder owns the blob.
227  * The embedder *must* ensure that the snapshot is from a trusted source.
228  */
230 
231  /**
232  * Enables the host application to provide a mechanism for recording
233  * statistics counters.
234  */
235  CounterLookupCallback counter_lookup_callback = nullptr;
236 
237  /**
238  * Enables the host application to provide a mechanism for recording
239  * histograms. The CreateHistogram function returns a
240  * histogram which will later be passed to the AddHistogramSample
241  * function.
242  */
243  CreateHistogramCallback create_histogram_callback = nullptr;
244  AddHistogramSampleCallback add_histogram_sample_callback = nullptr;
245 
246  /**
247  * The ArrayBuffer::Allocator to use for allocating and freeing the backing
248  * store of ArrayBuffers.
249  *
250  * If the shared_ptr version is used, the Isolate instance and every
251  * |BackingStore| allocated using this allocator hold a std::shared_ptr
252  * to the allocator, in order to facilitate lifetime
253  * management for the allocator instance.
254  */
257 
258  /**
259  * Specifies an optional nullptr-terminated array of raw addresses in the
260  * embedder that V8 can match against during serialization and use for
261  * deserialization. This array and its content must stay valid for the
262  * entire lifetime of the isolate.
263  */
264  const intptr_t* external_references = nullptr;
265 
266  /**
267  * Whether calling Atomics.wait (a function that may block) is allowed in
268  * this isolate. This can also be configured via SetAllowAtomicsWait.
269  */
270  bool allow_atomics_wait = true;
271 
272  /**
273  * Termination is postponed when there is no active SafeForTerminationScope.
274  */
276 
277  /**
278  * The following parameters describe the offsets for addressing type info
279  * for wrapped API objects and are used by the fast C API
280  * (for details see v8-fast-api-calls.h).
281  */
284 
285  /**
286  * Callbacks to invoke in case of fatal or OOM errors.
287  */
288  FatalErrorCallback fatal_error_callback = nullptr;
289  OOMErrorCallback oom_error_callback = nullptr;
290 
291  /**
292  * The following parameter is experimental and may change significantly.
293  * This is currently for internal testing.
294  */
296  };
297 
298  /**
299  * Stack-allocated class which sets the isolate for all operations
300  * executed within a local scope.
301  */
303  public:
304  explicit Scope(Isolate* isolate) : isolate_(isolate) { isolate->Enter(); }
305 
306  ~Scope() { isolate_->Exit(); }
307 
308  // Prevent copying of Scope objects.
309  Scope(const Scope&) = delete;
310  Scope& operator=(const Scope&) = delete;
311 
312  private:
313  Isolate* const isolate_;
314  };
315 
316  /**
317  * Assert that no Javascript code is invoked.
318  */
320  public:
322 
325 
326  // Prevent copying of Scope objects.
328  delete;
330  const DisallowJavascriptExecutionScope&) = delete;
331 
332  private:
333  OnFailure on_failure_;
334  Isolate* isolate_;
335 
336  bool was_execution_allowed_assert_;
337  bool was_execution_allowed_throws_;
338  bool was_execution_allowed_dump_;
339  };
340 
341  /**
342  * Introduce exception to DisallowJavascriptExecutionScope.
343  */
345  public:
348 
349  // Prevent copying of Scope objects.
351  delete;
353  const AllowJavascriptExecutionScope&) = delete;
354 
355  private:
356  Isolate* isolate_;
357  bool was_execution_allowed_assert_;
358  bool was_execution_allowed_throws_;
359  bool was_execution_allowed_dump_;
360  };
361 
362  /**
363  * Do not run microtasks while this scope is active, even if microtasks are
364  * automatically executed otherwise.
365  */
367  public:
369  Isolate* isolate, MicrotaskQueue* microtask_queue = nullptr);
371 
372  // Prevent copying of Scope objects.
374  delete;
376  const SuppressMicrotaskExecutionScope&) = delete;
377 
378  private:
379  internal::Isolate* const isolate_;
380  internal::MicrotaskQueue* const microtask_queue_;
381  internal::Address previous_stack_height_;
382 
383  friend class internal::ThreadLocalTop;
384  };
385 
386  /**
387  * This scope allows terminations inside direct V8 API calls and forbid them
388  * inside any recursive API calls without explicit SafeForTerminationScope.
389  */
391  public:
392  explicit SafeForTerminationScope(v8::Isolate* isolate);
394 
395  // Prevent copying of Scope objects.
398 
399  private:
400  internal::Isolate* isolate_;
401  bool prev_value_;
402  };
403 
404  /**
405  * Types of garbage collections that can be requested via
406  * RequestGarbageCollectionForTesting.
407  */
411  };
412 
413  /**
414  * Features reported via the SetUseCounterCallback callback. Do not change
415  * assigned numbers of existing items; add new features to the end of this
416  * list.
417  */
419  kUseAsm = 0,
471  kAtomicsNotify = 52, // Unused.
472  kAtomicsWake = 53, // Unused.
473  kCollator = 54,
478  kLocale = 59,
493  kDateGetTimezoneOffset = 74, // Unused.
528  kWasmBulkMemory = 109, // Unused.
534 
535  // If you add new values here, you'll also need to update Chromium's:
536  // web_feature.mojom, use_counter_callback.cc, and enums.xml. V8 changes to
537  // this list need to be landed first, then changes on the Chromium side.
538  kUseCounterFeatureCount // This enum value must be last.
539  };
540 
542  kMessageLog = (1 << 0),
543  kMessageDebug = (1 << 1),
544  kMessageInfo = (1 << 2),
545  kMessageError = (1 << 3),
546  kMessageWarning = (1 << 4),
549  };
550 
551  using UseCounterCallback = void (*)(Isolate* isolate,
552  UseCounterFeature feature);
553 
554  /**
555  * Allocates a new isolate but does not initialize it. Does not change the
556  * currently entered isolate.
557  *
558  * Only Isolate::GetData() and Isolate::SetData(), which access the
559  * embedder-controlled parts of the isolate, are allowed to be called on the
560  * uninitialized isolate. To initialize the isolate, call
561  * Isolate::Initialize().
562  *
563  * When an isolate is no longer used its resources should be freed
564  * by calling Dispose(). Using the delete operator is not allowed.
565  *
566  * V8::Initialize() must have run prior to this.
567  */
568  static Isolate* Allocate();
569 
570  /**
571  * Initialize an Isolate previously allocated by Isolate::Allocate().
572  */
573  static void Initialize(Isolate* isolate, const CreateParams& params);
574 
575  /**
576  * Creates a new isolate. Does not change the currently entered
577  * isolate.
578  *
579  * When an isolate is no longer used its resources should be freed
580  * by calling Dispose(). Using the delete operator is not allowed.
581  *
582  * V8::Initialize() must have run prior to this.
583  */
584  static Isolate* New(const CreateParams& params);
585 
586  /**
587  * Returns the entered isolate for the current thread or NULL in
588  * case there is no current isolate.
589  *
590  * This method must not be invoked before V8::Initialize() was invoked.
591  */
592  static Isolate* GetCurrent();
593 
594  /**
595  * Returns the entered isolate for the current thread or NULL in
596  * case there is no current isolate.
597  *
598  * No checks are performed by this method.
599  */
601 
602  /**
603  * Return true if this isolate is currently active.
604  **/
605  bool IsCurrent() const;
606 
607  /**
608  * Clears the set of objects held strongly by the heap. This set of
609  * objects are originally built when a WeakRef is created or
610  * successfully dereferenced.
611  *
612  * This is invoked automatically after microtasks are run. See
613  * MicrotasksPolicy for when microtasks are run.
614  *
615  * This needs to be manually invoked only if the embedder is manually running
616  * microtasks via a custom MicrotaskQueue class's PerformCheckpoint. In that
617  * case, it is the embedder's responsibility to make this call at a time which
618  * does not interrupt synchronous ECMAScript code execution.
619  */
621 
622  /**
623  * Custom callback used by embedders to help V8 determine if it should abort
624  * when it throws and no internal handler is predicted to catch the
625  * exception. If --abort-on-uncaught-exception is used on the command line,
626  * then V8 will abort if either:
627  * - no custom callback is set.
628  * - the custom callback set returns true.
629  * Otherwise, the custom callback will not be called and V8 will not abort.
630  */
631  using AbortOnUncaughtExceptionCallback = bool (*)(Isolate*);
633  AbortOnUncaughtExceptionCallback callback);
634 
635  /**
636  * This specifies the callback called by the upcoming dynamic
637  * import() language feature to load modules.
638  */
639  V8_DEPRECATED("Use HostImportModuleDynamicallyCallback")
641  HostImportModuleDynamicallyWithImportAssertionsCallback callback);
643  HostImportModuleDynamicallyCallback callback);
644 
645  /**
646  * This specifies the callback called by the upcoming import.meta
647  * language feature to retrieve host-defined meta data for a module.
648  */
650  HostInitializeImportMetaObjectCallback callback);
651 
652  /**
653  * This specifies the callback called by the upcoming ShadowRealm
654  * construction language feature to retrieve host created globals.
655  */
657  HostCreateShadowRealmContextCallback callback);
658 
659  /**
660  * This specifies the callback called when the stack property of Error
661  * is accessed.
662  */
663  void SetPrepareStackTraceCallback(PrepareStackTraceCallback callback);
664 
665  /**
666  * Optional notification that the system is running low on memory.
667  * V8 uses these notifications to guide heuristics.
668  * It is allowed to call this function from another thread while
669  * the isolate is executing long running JavaScript code.
670  */
672 
673  /**
674  * Drop non-essential caches. Should only be called from testing code.
675  * The method can potentially block for a long time and does not necessarily
676  * trigger GC.
677  */
679 
680  /**
681  * Methods below this point require holding a lock (using Locker) in
682  * a multi-threaded environment.
683  */
684 
685  /**
686  * Sets this isolate as the entered one for the current thread.
687  * Saves the previously entered one (if any), so that it can be
688  * restored when exiting. Re-entering an isolate is allowed.
689  */
690  void Enter();
691 
692  /**
693  * Exits this isolate by restoring the previously entered one in the
694  * current thread. The isolate may still stay the same, if it was
695  * entered more than once.
696  *
697  * Requires: this == Isolate::GetCurrent().
698  */
699  void Exit();
700 
701  /**
702  * Disposes the isolate. The isolate must not be entered by any
703  * thread to be disposable.
704  */
705  void Dispose();
706 
707  /**
708  * Dumps activated low-level V8 internal stats. This can be used instead
709  * of performing a full isolate disposal.
710  */
712 
713  /**
714  * Discards all V8 thread-specific data for the Isolate. Should be used
715  * if a thread is terminating and it has used an Isolate that will outlive
716  * the thread -- all thread-specific data for an Isolate is discarded when
717  * an Isolate is disposed so this call is pointless if an Isolate is about
718  * to be Disposed.
719  */
721 
722  /**
723  * Associate embedder-specific data with the isolate. |slot| has to be
724  * between 0 and GetNumberOfDataSlots() - 1.
725  */
726  V8_INLINE void SetData(uint32_t slot, void* data);
727 
728  /**
729  * Retrieve embedder-specific data from the isolate.
730  * Returns NULL if SetData has never been called for the given |slot|.
731  */
732  V8_INLINE void* GetData(uint32_t slot);
733 
734  /**
735  * Returns the maximum number of available embedder data slots. Valid slots
736  * are in the range of 0 - GetNumberOfDataSlots() - 1.
737  */
738  V8_INLINE static uint32_t GetNumberOfDataSlots();
739 
740  /**
741  * Return data that was previously attached to the isolate snapshot via
742  * SnapshotCreator, and removes the reference to it.
743  * Repeated call with the same index returns an empty MaybeLocal.
744  */
745  template <class T>
747 
748  /**
749  * Get statistics about the heap memory usage.
750  */
751  void GetHeapStatistics(HeapStatistics* heap_statistics);
752 
753  /**
754  * Returns the number of spaces in the heap.
755  */
757 
758  /**
759  * Get the memory usage of a space in the heap.
760  *
761  * \param space_statistics The HeapSpaceStatistics object to fill in
762  * statistics.
763  * \param index The index of the space to get statistics from, which ranges
764  * from 0 to NumberOfHeapSpaces() - 1.
765  * \returns true on success.
766  */
768  size_t index);
769 
770  /**
771  * Returns the number of types of objects tracked in the heap at GC.
772  */
774 
775  /**
776  * Get statistics about objects in the heap.
777  *
778  * \param object_statistics The HeapObjectStatistics object to fill in
779  * statistics of objects of given type, which were live in the previous GC.
780  * \param type_index The index of the type of object to fill details about,
781  * which ranges from 0 to NumberOfTrackedHeapObjectTypes() - 1.
782  * \returns true on success.
783  */
785  size_t type_index);
786 
787  /**
788  * Get statistics about code and its metadata in the heap.
789  *
790  * \param object_statistics The HeapCodeStatistics object to fill in
791  * statistics of code, bytecode and their metadata.
792  * \returns true on success.
793  */
795 
796  /**
797  * This API is experimental and may change significantly.
798  *
799  * Enqueues a memory measurement request and invokes the delegate with the
800  * results.
801  *
802  * \param delegate the delegate that defines which contexts to measure and
803  * reports the results.
804  *
805  * \param execution promptness executing the memory measurement.
806  * The kEager value is expected to be used only in tests.
807  */
809  std::unique_ptr<MeasureMemoryDelegate> delegate,
811 
812  /**
813  * Get a call stack sample from the isolate.
814  * \param state Execution state.
815  * \param frames Caller allocated buffer to store stack frames.
816  * \param frames_limit Maximum number of frames to capture. The buffer must
817  * be large enough to hold the number of frames.
818  * \param sample_info The sample info is filled up by the function
819  * provides number of actual captured stack frames and
820  * the current VM state.
821  * \note GetStackSample should only be called when the JS thread is paused or
822  * interrupted. Otherwise the behavior is undefined.
823  */
824  void GetStackSample(const RegisterState& state, void** frames,
825  size_t frames_limit, SampleInfo* sample_info);
826 
827  /**
828  * Adjusts the amount of registered external memory. Used to give V8 an
829  * indication of the amount of externally allocated memory that is kept alive
830  * by JavaScript objects. V8 uses this to decide when to perform global
831  * garbage collections. Registering externally allocated memory will trigger
832  * global garbage collections more often than it would otherwise in an attempt
833  * to garbage collect the JavaScript objects that keep the externally
834  * allocated memory alive.
835  *
836  * \param change_in_bytes the change in externally allocated memory that is
837  * kept alive by JavaScript objects.
838  * \returns the adjusted value.
839  */
840  int64_t AdjustAmountOfExternalAllocatedMemory(int64_t change_in_bytes);
841 
842  /**
843  * Returns the number of phantom handles without callbacks that were reset
844  * by the garbage collector since the last call to this function.
845  */
847 
848  /**
849  * Returns heap profiler for this isolate. Will return NULL until the isolate
850  * is initialized.
851  */
853 
854  /**
855  * Tells the VM whether the embedder is idle or not.
856  */
857  void SetIdle(bool is_idle);
858 
859  /** Returns the ArrayBuffer::Allocator used in this isolate. */
861 
862  /** Returns true if this isolate has a current context. */
863  bool InContext();
864 
865  /**
866  * Returns the context of the currently running JavaScript, or the context
867  * on the top of the stack if no JavaScript is running.
868  */
870 
871  /**
872  * Returns either the last context entered through V8's C++ API, or the
873  * context of the currently running microtask while processing microtasks.
874  * If a context is entered while executing a microtask, that context is
875  * returned.
876  */
878 
879  /**
880  * Returns the Context that corresponds to the Incumbent realm in HTML spec.
881  * https://html.spec.whatwg.org/multipage/webappapis.html#incumbent
882  */
884 
885  /**
886  * Schedules a v8::Exception::Error with the given message.
887  * See ThrowException for more details. Templatized to provide compile-time
888  * errors in case of too long strings (see v8::String::NewFromUtf8Literal).
889  */
890  template <int N>
891  Local<Value> ThrowError(const char (&message)[N]) {
892  return ThrowError(String::NewFromUtf8Literal(this, message));
893  }
895 
896  /**
897  * Schedules an exception to be thrown when returning to JavaScript. When an
898  * exception has been scheduled it is illegal to invoke any JavaScript
899  * operation; the caller must return immediately and only after the exception
900  * has been handled does it become legal to invoke JavaScript operations.
901  */
903 
904  using GCCallback = void (*)(Isolate* isolate, GCType type,
905  GCCallbackFlags flags);
906  using GCCallbackWithData = void (*)(Isolate* isolate, GCType type,
907  GCCallbackFlags flags, void* data);
908 
909  /**
910  * Enables the host application to receive a notification before a
911  * garbage collection. Allocations are allowed in the callback function,
912  * but the callback is not re-entrant: if the allocation inside it will
913  * trigger the garbage collection, the callback won't be called again.
914  * It is possible to specify the GCType filter for your callback. But it is
915  * not possible to register the same callback function two times with
916  * different GCType filters.
917  */
918  void AddGCPrologueCallback(GCCallbackWithData callback, void* data = nullptr,
919  GCType gc_type_filter = kGCTypeAll);
920  void AddGCPrologueCallback(GCCallback callback,
921  GCType gc_type_filter = kGCTypeAll);
922 
923  /**
924  * This function removes callback which was installed by
925  * AddGCPrologueCallback function.
926  */
927  void RemoveGCPrologueCallback(GCCallbackWithData, void* data = nullptr);
928  void RemoveGCPrologueCallback(GCCallback callback);
929 
930  /**
931  * Sets the embedder heap tracer for the isolate.
932  * SetEmbedderHeapTracer cannot be used simultaneously with AttachCppHeap.
933  */
935 
936  /*
937  * Gets the currently active heap tracer for the isolate that was set with
938  * SetEmbedderHeapTracer.
939  */
941 
942  /**
943  * Sets an embedder roots handle that V8 should consider when performing
944  * non-unified heap garbage collections.
945  *
946  * Using only EmbedderHeapTracer automatically sets up a default handler.
947  * The intended use case is for setting a custom handler after invoking
948  * `AttachCppHeap()`.
949  *
950  * V8 does not take ownership of the handler.
951  */
953 
954  /**
955  * Attaches a managed C++ heap as an extension to the JavaScript heap. The
956  * embedder maintains ownership of the CppHeap. At most one C++ heap can be
957  * attached to V8.
958  * AttachCppHeap cannot be used simultaneously with SetEmbedderHeapTracer.
959  *
960  * This is an experimental feature and may still change significantly.
961  */
963 
964  /**
965  * Detaches a managed C++ heap if one was attached using `AttachCppHeap()`.
966  *
967  * This is an experimental feature and may still change significantly.
968  */
970 
971  /**
972  * This is an experimental feature and may still change significantly.
973 
974  * \returns the C++ heap managed by V8. Only available if such a heap has been
975  * attached using `AttachCppHeap()`.
976  */
977  CppHeap* GetCppHeap() const;
978 
979  /**
980  * Use for |AtomicsWaitCallback| to indicate the type of event it receives.
981  */
982  enum class AtomicsWaitEvent {
983  /** Indicates that this call is happening before waiting. */
984  kStartWait,
985  /** `Atomics.wait()` finished because of an `Atomics.wake()` call. */
986  kWokenUp,
987  /** `Atomics.wait()` finished because it timed out. */
988  kTimedOut,
989  /** `Atomics.wait()` was interrupted through |TerminateExecution()|. */
991  /** `Atomics.wait()` was stopped through |AtomicsWaitWakeHandle|. */
992  kAPIStopped,
993  /** `Atomics.wait()` did not wait, as the initial condition was not met. */
994  kNotEqual
995  };
996 
997  /**
998  * Passed to |AtomicsWaitCallback| as a means of stopping an ongoing
999  * `Atomics.wait` call.
1000  */
1002  public:
1003  /**
1004  * Stop this `Atomics.wait()` call and call the |AtomicsWaitCallback|
1005  * with |kAPIStopped|.
1006  *
1007  * This function may be called from another thread. The caller has to ensure
1008  * through proper synchronization that it is not called after
1009  * the finishing |AtomicsWaitCallback|.
1010  *
1011  * Note that the ECMAScript specification does not plan for the possibility
1012  * of wakeups that are neither coming from a timeout or an `Atomics.wake()`
1013  * call, so this may invalidate assumptions made by existing code.
1014  * The embedder may accordingly wish to schedule an exception in the
1015  * finishing |AtomicsWaitCallback|.
1016  */
1017  void Wake();
1018  };
1019 
1020  /**
1021  * Embedder callback for `Atomics.wait()` that can be added through
1022  * |SetAtomicsWaitCallback|.
1023  *
1024  * This will be called just before starting to wait with the |event| value
1025  * |kStartWait| and after finishing waiting with one of the other
1026  * values of |AtomicsWaitEvent| inside of an `Atomics.wait()` call.
1027  *
1028  * |array_buffer| will refer to the underlying SharedArrayBuffer,
1029  * |offset_in_bytes| to the location of the waited-on memory address inside
1030  * the SharedArrayBuffer.
1031  *
1032  * |value| and |timeout_in_ms| will be the values passed to
1033  * the `Atomics.wait()` call. If no timeout was used, |timeout_in_ms|
1034  * will be `INFINITY`.
1035  *
1036  * In the |kStartWait| callback, |stop_handle| will be an object that
1037  * is only valid until the corresponding finishing callback and that
1038  * can be used to stop the wait process while it is happening.
1039  *
1040  * This callback may schedule exceptions, *unless* |event| is equal to
1041  * |kTerminatedExecution|.
1042  */
1043  using AtomicsWaitCallback = void (*)(AtomicsWaitEvent event,
1044  Local<SharedArrayBuffer> array_buffer,
1045  size_t offset_in_bytes, int64_t value,
1046  double timeout_in_ms,
1047  AtomicsWaitWakeHandle* stop_handle,
1048  void* data);
1049 
1050  /**
1051  * Set a new |AtomicsWaitCallback|. This overrides an earlier
1052  * |AtomicsWaitCallback|, if there was any. If |callback| is nullptr,
1053  * this unsets the callback. |data| will be passed to the callback
1054  * as its last parameter.
1055  */
1056  void SetAtomicsWaitCallback(AtomicsWaitCallback callback, void* data);
1057 
1058  /**
1059  * Enables the host application to receive a notification after a
1060  * garbage collection. Allocations are allowed in the callback function,
1061  * but the callback is not re-entrant: if the allocation inside it will
1062  * trigger the garbage collection, the callback won't be called again.
1063  * It is possible to specify the GCType filter for your callback. But it is
1064  * not possible to register the same callback function two times with
1065  * different GCType filters.
1066  */
1067  void AddGCEpilogueCallback(GCCallbackWithData callback, void* data = nullptr,
1068  GCType gc_type_filter = kGCTypeAll);
1069  void AddGCEpilogueCallback(GCCallback callback,
1070  GCType gc_type_filter = kGCTypeAll);
1071 
1072  /**
1073  * This function removes callback which was installed by
1074  * AddGCEpilogueCallback function.
1075  */
1076  void RemoveGCEpilogueCallback(GCCallbackWithData callback,
1077  void* data = nullptr);
1078  void RemoveGCEpilogueCallback(GCCallback callback);
1079 
1080  using GetExternallyAllocatedMemoryInBytesCallback = size_t (*)();
1081 
1082  /**
1083  * Set the callback that tells V8 how much memory is currently allocated
1084  * externally of the V8 heap. Ideally this memory is somehow connected to V8
1085  * objects and may get freed-up when the corresponding V8 objects get
1086  * collected by a V8 garbage collection.
1087  */
1089  GetExternallyAllocatedMemoryInBytesCallback callback);
1090 
1091  /**
1092  * Forcefully terminate the current thread of JavaScript execution
1093  * in the given isolate.
1094  *
1095  * This method can be used by any thread even if that thread has not
1096  * acquired the V8 lock with a Locker object.
1097  */
1099 
1100  /**
1101  * Is V8 terminating JavaScript execution.
1102  *
1103  * Returns true if JavaScript execution is currently terminating
1104  * because of a call to TerminateExecution. In that case there are
1105  * still JavaScript frames on the stack and the termination
1106  * exception is still active.
1107  */
1109 
1110  /**
1111  * Resume execution capability in the given isolate, whose execution
1112  * was previously forcefully terminated using TerminateExecution().
1113  *
1114  * When execution is forcefully terminated using TerminateExecution(),
1115  * the isolate can not resume execution until all JavaScript frames
1116  * have propagated the uncatchable exception which is generated. This
1117  * method allows the program embedding the engine to handle the
1118  * termination event and resume execution capability, even if
1119  * JavaScript frames remain on the stack.
1120  *
1121  * This method can be used by any thread even if that thread has not
1122  * acquired the V8 lock with a Locker object.
1123  */
1125 
1126  /**
1127  * Request V8 to interrupt long running JavaScript code and invoke
1128  * the given |callback| passing the given |data| to it. After |callback|
1129  * returns control will be returned to the JavaScript code.
1130  * There may be a number of interrupt requests in flight.
1131  * Can be called from another thread without acquiring a |Locker|.
1132  * Registered |callback| must not reenter interrupted Isolate.
1133  */
1134  void RequestInterrupt(InterruptCallback callback, void* data);
1135 
1136  /**
1137  * Returns true if there is ongoing background work within V8 that will
1138  * eventually post a foreground task, like asynchronous WebAssembly
1139  * compilation.
1140  */
1142 
1143  /**
1144  * Request garbage collection in this Isolate. It is only valid to call this
1145  * function if --expose_gc was specified.
1146  *
1147  * This should only be used for testing purposes and not to enforce a garbage
1148  * collection schedule. It has strong negative impact on the garbage
1149  * collection performance. Use IdleNotificationDeadline() or
1150  * LowMemoryNotification() instead to influence the garbage collection
1151  * schedule.
1152  */
1154 
1155  /**
1156  * Request garbage collection with a specific embedderstack state in this
1157  * Isolate. It is only valid to call this function if --expose_gc was
1158  * specified.
1159  *
1160  * This should only be used for testing purposes and not to enforce a garbage
1161  * collection schedule. It has strong negative impact on the garbage
1162  * collection performance. Use IdleNotificationDeadline() or
1163  * LowMemoryNotification() instead to influence the garbage collection
1164  * schedule.
1165  */
1167  GarbageCollectionType type,
1168  EmbedderHeapTracer::EmbedderStackState stack_state);
1169 
1170  /**
1171  * Set the callback to invoke for logging event.
1172  */
1173  void SetEventLogger(LogEventCallback that);
1174 
1175  /**
1176  * Adds a callback to notify the host application right before a script
1177  * is about to run. If a script re-enters the runtime during executing, the
1178  * BeforeCallEnteredCallback is invoked for each re-entrance.
1179  * Executing scripts inside the callback will re-trigger the callback.
1180  */
1181  void AddBeforeCallEnteredCallback(BeforeCallEnteredCallback callback);
1182 
1183  /**
1184  * Removes callback that was installed by AddBeforeCallEnteredCallback.
1185  */
1186  void RemoveBeforeCallEnteredCallback(BeforeCallEnteredCallback callback);
1187 
1188  /**
1189  * Adds a callback to notify the host application when a script finished
1190  * running. If a script re-enters the runtime during executing, the
1191  * CallCompletedCallback is only invoked when the outer-most script
1192  * execution ends. Executing scripts inside the callback do not trigger
1193  * further callbacks.
1194  */
1195  void AddCallCompletedCallback(CallCompletedCallback callback);
1196 
1197  /**
1198  * Removes callback that was installed by AddCallCompletedCallback.
1199  */
1200  void RemoveCallCompletedCallback(CallCompletedCallback callback);
1201 
1202  /**
1203  * Set the PromiseHook callback for various promise lifecycle
1204  * events.
1205  */
1206  void SetPromiseHook(PromiseHook hook);
1207 
1208  /**
1209  * Set callback to notify about promise reject with no handler, or
1210  * revocation of such a previous notification once the handler is added.
1211  */
1212  void SetPromiseRejectCallback(PromiseRejectCallback callback);
1213 
1214  /**
1215  * Runs the default MicrotaskQueue until it gets empty and perform other
1216  * microtask checkpoint steps, such as calling ClearKeptObjects. Asserts that
1217  * the MicrotasksPolicy is not kScoped. Any exceptions thrown by microtask
1218  * callbacks are swallowed.
1219  */
1221 
1222  /**
1223  * Enqueues the callback to the default MicrotaskQueue
1224  */
1225  void EnqueueMicrotask(Local<Function> microtask);
1226 
1227  /**
1228  * Enqueues the callback to the default MicrotaskQueue
1229  */
1230  void EnqueueMicrotask(MicrotaskCallback callback, void* data = nullptr);
1231 
1232  /**
1233  * Controls how Microtasks are invoked. See MicrotasksPolicy for details.
1234  */
1236 
1237  /**
1238  * Returns the policy controlling how Microtasks are invoked.
1239  */
1241 
1242  /**
1243  * Adds a callback to notify the host application after
1244  * microtasks were run on the default MicrotaskQueue. The callback is
1245  * triggered by explicit RunMicrotasks call or automatic microtasks execution
1246  * (see SetMicrotaskPolicy).
1247  *
1248  * Callback will trigger even if microtasks were attempted to run,
1249  * but the microtasks queue was empty and no single microtask was actually
1250  * executed.
1251  *
1252  * Executing scripts inside the callback will not re-trigger microtasks and
1253  * the callback.
1254  */
1256  MicrotasksCompletedCallbackWithData callback, void* data = nullptr);
1257 
1258  /**
1259  * Removes callback that was installed by AddMicrotasksCompletedCallback.
1260  */
1262  MicrotasksCompletedCallbackWithData callback, void* data = nullptr);
1263 
1264  /**
1265  * Sets a callback for counting the number of times a feature of V8 is used.
1266  */
1267  void SetUseCounterCallback(UseCounterCallback callback);
1268 
1269  /**
1270  * Enables the host application to provide a mechanism for recording
1271  * statistics counters.
1272  */
1273  void SetCounterFunction(CounterLookupCallback);
1274 
1275  /**
1276  * Enables the host application to provide a mechanism for recording
1277  * histograms. The CreateHistogram function returns a
1278  * histogram which will later be passed to the AddHistogramSample
1279  * function.
1280  */
1281  void SetCreateHistogramFunction(CreateHistogramCallback);
1282  void SetAddHistogramSampleFunction(AddHistogramSampleCallback);
1283 
1284  /**
1285  * Enables the host application to provide a mechanism for recording
1286  * event based metrics. In order to use this interface
1287  * include/v8-metrics.h
1288  * needs to be included and the recorder needs to be derived from the
1289  * Recorder base class defined there.
1290  * This method can only be called once per isolate and must happen during
1291  * isolate initialization before background threads are spawned.
1292  */
1294  const std::shared_ptr<metrics::Recorder>& metrics_recorder);
1295 
1296  /**
1297  * Enables the host application to provide a mechanism for recording a
1298  * predefined set of data as crash keys to be used in postmortem debugging in
1299  * case of a crash.
1300  */
1301  void SetAddCrashKeyCallback(AddCrashKeyCallback);
1302 
1303  /**
1304  * Optional notification that the embedder is idle.
1305  * V8 uses the notification to perform garbage collection.
1306  * This call can be used repeatedly if the embedder remains idle.
1307  * Returns true if the embedder should stop calling IdleNotificationDeadline
1308  * until real work has been done. This indicates that V8 has done
1309  * as much cleanup as it will be able to do.
1310  *
1311  * The deadline_in_seconds argument specifies the deadline V8 has to finish
1312  * garbage collection work. deadline_in_seconds is compared with
1313  * MonotonicallyIncreasingTime() and should be based on the same timebase as
1314  * that function. There is no guarantee that the actual work will be done
1315  * within the time limit.
1316  */
1317  bool IdleNotificationDeadline(double deadline_in_seconds);
1318 
1319  /**
1320  * Optional notification that the system is running low on memory.
1321  * V8 uses these notifications to attempt to free memory.
1322  */
1324 
1325  /**
1326  * Optional notification that a context has been disposed. V8 uses these
1327  * notifications to guide the GC heuristic and cancel FinalizationRegistry
1328  * cleanup tasks. Returns the number of context disposals - including this one
1329  * - since the last time V8 had a chance to clean up.
1330  *
1331  * The optional parameter |dependant_context| specifies whether the disposed
1332  * context was depending on state from other contexts or not.
1333  */
1334  int ContextDisposedNotification(bool dependant_context = true);
1335 
1336  /**
1337  * Optional notification that the isolate switched to the foreground.
1338  * V8 uses these notifications to guide heuristics.
1339  */
1341 
1342  /**
1343  * Optional notification that the isolate switched to the background.
1344  * V8 uses these notifications to guide heuristics.
1345  */
1347 
1348  /**
1349  * Optional notification which will enable the memory savings mode.
1350  * V8 uses this notification to guide heuristics which may result in a
1351  * smaller memory footprint at the cost of reduced runtime performance.
1352  */
1354 
1355  /**
1356  * Optional notification which will disable the memory savings mode.
1357  */
1359 
1360  /**
1361  * Optional notification to tell V8 the current performance requirements
1362  * of the embedder based on RAIL.
1363  * V8 uses these notifications to guide heuristics.
1364  * This is an unfinished experimental feature. Semantics and implementation
1365  * may change frequently.
1366  */
1367  void SetRAILMode(RAILMode rail_mode);
1368 
1369  /**
1370  * Update load start time of the RAIL mode
1371  */
1373 
1374  /**
1375  * Optional notification to tell V8 the current isolate is used for debugging
1376  * and requires higher heap limit.
1377  */
1379 
1380  /**
1381  * Restores the original heap limit after IncreaseHeapLimitForDebugging().
1382  */
1384 
1385  /**
1386  * Returns true if the heap limit was increased for debugging and the
1387  * original heap limit was not restored yet.
1388  */
1390 
1391  /**
1392  * Allows the host application to provide the address of a function that is
1393  * notified each time code is added, moved or removed.
1394  *
1395  * \param options options for the JIT code event handler.
1396  * \param event_handler the JIT code event handler, which will be invoked
1397  * each time code is added, moved or removed.
1398  * \note \p event_handler won't get notified of existent code.
1399  * \note since code removal notifications are not currently issued, the
1400  * \p event_handler may get notifications of code that overlaps earlier
1401  * code notifications. This happens when code areas are reused, and the
1402  * earlier overlapping code areas should therefore be discarded.
1403  * \note the events passed to \p event_handler and the strings they point to
1404  * are not guaranteed to live past each call. The \p event_handler must
1405  * copy strings and other parameters it needs to keep around.
1406  * \note the set of events declared in JitCodeEvent::EventType is expected to
1407  * grow over time, and the JitCodeEvent structure is expected to accrue
1408  * new members. The \p event_handler function must ignore event codes
1409  * it does not recognize to maintain future compatibility.
1410  * \note Use Isolate::CreateParams to get events for code executed during
1411  * Isolate setup.
1412  */
1414  JitCodeEventHandler event_handler);
1415 
1416  /**
1417  * Modifies the stack limit for this Isolate.
1418  *
1419  * \param stack_limit An address beyond which the Vm's stack may not grow.
1420  *
1421  * \note If you are using threads then you should hold the V8::Locker lock
1422  * while setting the stack limit and you must set a non-default stack
1423  * limit separately for each thread.
1424  */
1425  void SetStackLimit(uintptr_t stack_limit);
1426 
1427  /**
1428  * Returns a memory range that can potentially contain jitted code. Code for
1429  * V8's 'builtins' will not be in this range if embedded builtins is enabled.
1430  *
1431  * On Win64, embedders are advised to install function table callbacks for
1432  * these ranges, as default SEH won't be able to unwind through jitted code.
1433  * The first page of the code range is reserved for the embedder and is
1434  * committed, writable, and executable, to be used to store unwind data, as
1435  * documented in
1436  * https://docs.microsoft.com/en-us/cpp/build/exception-handling-x64.
1437  *
1438  * Might be empty on other platforms.
1439  *
1440  * https://code.google.com/p/v8/issues/detail?id=3598
1441  */
1442  void GetCodeRange(void** start, size_t* length_in_bytes);
1443 
1444  /**
1445  * As GetCodeRange, but for embedded builtins (these live in a distinct
1446  * memory region from other V8 Code objects).
1447  */
1448  void GetEmbeddedCodeRange(const void** start, size_t* length_in_bytes);
1449 
1450  /**
1451  * Returns the JSEntryStubs necessary for use with the Unwinder API.
1452  */
1454 
1455  static constexpr size_t kMinCodePagesBufferSize = 32;
1456 
1457  /**
1458  * Copies the code heap pages currently in use by V8 into |code_pages_out|.
1459  * |code_pages_out| must have at least kMinCodePagesBufferSize capacity and
1460  * must be empty.
1461  *
1462  * Signal-safe, does not allocate, does not access the V8 heap.
1463  * No code on the stack can rely on pages that might be missing.
1464  *
1465  * Returns the number of pages available to be copied, which might be greater
1466  * than |capacity|. In this case, only |capacity| pages will be copied into
1467  * |code_pages_out|. The caller should provide a bigger buffer on the next
1468  * call in order to get all available code pages, but this is not required.
1469  */
1470  size_t CopyCodePages(size_t capacity, MemoryRange* code_pages_out);
1471 
1472  /** Set the callback to invoke in case of fatal errors. */
1473  void SetFatalErrorHandler(FatalErrorCallback that);
1474 
1475  /** Set the callback to invoke in case of OOM errors. */
1476  void SetOOMErrorHandler(OOMErrorCallback that);
1477 
1478  /**
1479  * Add a callback to invoke in case the heap size is close to the heap limit.
1480  * If multiple callbacks are added, only the most recently added callback is
1481  * invoked.
1482  */
1483  void AddNearHeapLimitCallback(NearHeapLimitCallback callback, void* data);
1484 
1485  /**
1486  * Remove the given callback and restore the heap limit to the
1487  * given limit. If the given limit is zero, then it is ignored.
1488  * If the current heap size is greater than the given limit,
1489  * then the heap limit is restored to the minimal limit that
1490  * is possible for the current heap size.
1491  */
1492  void RemoveNearHeapLimitCallback(NearHeapLimitCallback callback,
1493  size_t heap_limit);
1494 
1495  /**
1496  * If the heap limit was changed by the NearHeapLimitCallback, then the
1497  * initial heap limit will be restored once the heap size falls below the
1498  * given threshold percentage of the initial heap limit.
1499  * The threshold percentage is a number in (0.0, 1.0) range.
1500  */
1501  void AutomaticallyRestoreInitialHeapLimit(double threshold_percent = 0.5);
1502 
1503  /**
1504  * Set the callback to invoke to check if code generation from
1505  * strings should be allowed.
1506  */
1508  ModifyCodeGenerationFromStringsCallback2 callback);
1509 
1510  /**
1511  * Set the callback to invoke to check if wasm code generation should
1512  * be allowed.
1513  */
1515  AllowWasmCodeGenerationCallback callback);
1516 
1517  /**
1518  * Embedder over{ride|load} injection points for wasm APIs. The expectation
1519  * is that the embedder sets them at most once.
1520  */
1521  void SetWasmModuleCallback(ExtensionCallback callback);
1522  void SetWasmInstanceCallback(ExtensionCallback callback);
1523 
1524  void SetWasmStreamingCallback(WasmStreamingCallback callback);
1525 
1526  void SetWasmLoadSourceMapCallback(WasmLoadSourceMapCallback callback);
1527 
1528  void SetWasmSimdEnabledCallback(WasmSimdEnabledCallback callback);
1529 
1530  void SetWasmExceptionsEnabledCallback(WasmExceptionsEnabledCallback callback);
1531 
1533  WasmDynamicTieringEnabledCallback callback);
1534 
1536  SharedArrayBufferConstructorEnabledCallback callback);
1537 
1538  /**
1539  * This function can be called by the embedder to signal V8 that the dynamic
1540  * enabling of features has finished. V8 can now set up dynamically added
1541  * features.
1542  */
1544 
1545  /**
1546  * Check if V8 is dead and therefore unusable. This is the case after
1547  * fatal errors such as out-of-memory situations.
1548  */
1549  bool IsDead();
1550 
1551  /**
1552  * Adds a message listener (errors only).
1553  *
1554  * The same message listener can be added more than once and in that
1555  * case it will be called more than once for each message.
1556  *
1557  * If data is specified, it will be passed to the callback when it is called.
1558  * Otherwise, the exception object will be passed to the callback instead.
1559  */
1560  bool AddMessageListener(MessageCallback that,
1561  Local<Value> data = Local<Value>());
1562 
1563  /**
1564  * Adds a message listener.
1565  *
1566  * The same message listener can be added more than once and in that
1567  * case it will be called more than once for each message.
1568  *
1569  * If data is specified, it will be passed to the callback when it is called.
1570  * Otherwise, the exception object will be passed to the callback instead.
1571  *
1572  * A listener can listen for particular error levels by providing a mask.
1573  */
1574  bool AddMessageListenerWithErrorLevel(MessageCallback that,
1575  int message_levels,
1576  Local<Value> data = Local<Value>());
1577 
1578  /**
1579  * Remove all message listeners from the specified callback function.
1580  */
1581  void RemoveMessageListeners(MessageCallback that);
1582 
1583  /** Callback function for reporting failed access checks.*/
1584  void SetFailedAccessCheckCallbackFunction(FailedAccessCheckCallback);
1585 
1586  /**
1587  * Tells V8 to capture current stack trace when uncaught exception occurs
1588  * and report it to the message listeners. The option is off by default.
1589  */
1591  bool capture, int frame_limit = 10,
1593 
1594  /**
1595  * Iterates through all external resources referenced from current isolate
1596  * heap. GC is not invoked prior to iterating, therefore there is no
1597  * guarantee that visited objects are still alive.
1598  */
1600 
1601  /**
1602  * Iterates through all the persistent handles in the current isolate's heap
1603  * that have class_ids.
1604  */
1606 
1607  /**
1608  * Iterates through all the persistent handles in the current isolate's heap
1609  * that have class_ids and are weak to be marked as inactive if there is no
1610  * pending activity for the handle.
1611  */
1613 
1614  /**
1615  * Check if this isolate is in use.
1616  * True if at least one thread Enter'ed this isolate.
1617  */
1618  bool IsInUse();
1619 
1620  /**
1621  * Set whether calling Atomics.wait (a function that may block) is allowed in
1622  * this isolate. This can also be configured via
1623  * CreateParams::allow_atomics_wait.
1624  */
1625  void SetAllowAtomicsWait(bool allow);
1626 
1627  /**
1628  * Time zone redetection indicator for
1629  * DateTimeConfigurationChangeNotification.
1630  *
1631  * kSkip indicates V8 that the notification should not trigger redetecting
1632  * host time zone. kRedetect indicates V8 that host time zone should be
1633  * redetected, and used to set the default time zone.
1634  *
1635  * The host time zone detection may require file system access or similar
1636  * operations unlikely to be available inside a sandbox. If v8 is run inside a
1637  * sandbox, the host time zone has to be detected outside the sandbox before
1638  * calling DateTimeConfigurationChangeNotification function.
1639  */
1641 
1642  /**
1643  * Notification that the embedder has changed the time zone, daylight savings
1644  * time or other date / time configuration parameters. V8 keeps a cache of
1645  * various values used for date / time computation. This notification will
1646  * reset those cached values for the current context so that date / time
1647  * configuration changes would be reflected.
1648  *
1649  * This API should not be called more than needed as it will negatively impact
1650  * the performance of date operations.
1651  */
1653  TimeZoneDetection time_zone_detection = TimeZoneDetection::kSkip);
1654 
1655  /**
1656  * Notification that the embedder has changed the locale. V8 keeps a cache of
1657  * various values used for locale computation. This notification will reset
1658  * those cached values for the current context so that locale configuration
1659  * changes would be reflected.
1660  *
1661  * This API should not be called more than needed as it will negatively impact
1662  * the performance of locale operations.
1663  */
1665 
1666  Isolate() = delete;
1667  ~Isolate() = delete;
1668  Isolate(const Isolate&) = delete;
1669  Isolate& operator=(const Isolate&) = delete;
1670  // Deleting operator new and delete here is allowed as ctor and dtor is also
1671  // deleted.
1672  void* operator new(size_t size) = delete;
1673  void* operator new[](size_t size) = delete;
1674  void operator delete(void*, size_t) = delete;
1675  void operator delete[](void*, size_t) = delete;
1676 
1677  private:
1678  template <class K, class V, class Traits>
1680 
1681  internal::Address* GetDataFromSnapshotOnce(size_t index);
1682  void ReportExternalAllocationLimitReached();
1683 };
1684 
1685 void Isolate::SetData(uint32_t slot, void* data) {
1686  using I = internal::Internals;
1687  I::SetEmbedderData(this, slot, data);
1688 }
1689 
1690 void* Isolate::GetData(uint32_t slot) {
1691  using I = internal::Internals;
1692  return I::GetEmbedderData(this, slot);
1693 }
1694 
1696  using I = internal::Internals;
1697  return I::kNumIsolateDataSlots;
1698 }
1699 
1700 template <class T>
1702  T* data = reinterpret_cast<T*>(GetDataFromSnapshotOnce(index));
1703  if (data) internal::PerformCastCheck(data);
1704  return Local<T>(data);
1705 }
1706 
1707 } // namespace v8
1708 
1709 #endif // INCLUDE_V8_ISOLATE_H_