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