Line data Source code
1 : // Copyright 2012 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 : /** \mainpage V8 API Reference Guide
6 : *
7 : * V8 is Google's open source JavaScript engine.
8 : *
9 : * This set of documents provides reference material generated from the
10 : * V8 header file, include/v8.h.
11 : *
12 : * For other documentation see http://code.google.com/apis/v8/
13 : */
14 :
15 : #ifndef INCLUDE_V8_H_
16 : #define INCLUDE_V8_H_
17 :
18 : #include <stddef.h>
19 : #include <stdint.h>
20 : #include <stdio.h>
21 : #include <memory>
22 : #include <utility>
23 : #include <vector>
24 :
25 : #include "v8-internal.h" // NOLINT(build/include)
26 : #include "v8-version.h" // NOLINT(build/include)
27 : #include "v8config.h" // NOLINT(build/include)
28 :
29 : // We reserve the V8_* prefix for macros defined in V8 public API and
30 : // assume there are no name conflicts with the embedder's code.
31 :
32 : /**
33 : * The v8 JavaScript engine.
34 : */
35 : namespace v8 {
36 :
37 : class AccessorSignature;
38 : class Array;
39 : class ArrayBuffer;
40 : class BigInt;
41 : class BigIntObject;
42 : class Boolean;
43 : class BooleanObject;
44 : class Context;
45 : class Data;
46 : class Date;
47 : class External;
48 : class Function;
49 : class FunctionTemplate;
50 : class HeapProfiler;
51 : class ImplementationUtilities;
52 : class Int32;
53 : class Integer;
54 : class Isolate;
55 : template <class T>
56 : class Maybe;
57 : class Name;
58 : class Number;
59 : class NumberObject;
60 : class Object;
61 : class ObjectOperationDescriptor;
62 : class ObjectTemplate;
63 : class Platform;
64 : class Primitive;
65 : class Promise;
66 : class PropertyDescriptor;
67 : class Proxy;
68 : class RawOperationDescriptor;
69 : class Script;
70 : class SharedArrayBuffer;
71 : class Signature;
72 : class StartupData;
73 : class StackFrame;
74 : class StackTrace;
75 : class String;
76 : class StringObject;
77 : class Symbol;
78 : class SymbolObject;
79 : class PrimitiveArray;
80 : class Private;
81 : class Uint32;
82 : class Utils;
83 : class Value;
84 : class WasmModuleObject;
85 : template <class T> class Local;
86 : template <class T>
87 : class MaybeLocal;
88 : template <class T> class Eternal;
89 : template<class T> class NonCopyablePersistentTraits;
90 : template<class T> class PersistentBase;
91 : template <class T, class M = NonCopyablePersistentTraits<T> >
92 : class Persistent;
93 : template <class T>
94 : class Global;
95 : template<class K, class V, class T> class PersistentValueMap;
96 : template <class K, class V, class T>
97 : class PersistentValueMapBase;
98 : template <class K, class V, class T>
99 : class GlobalValueMap;
100 : template<class V, class T> class PersistentValueVector;
101 : template<class T, class P> class WeakCallbackObject;
102 : class FunctionTemplate;
103 : class ObjectTemplate;
104 : template<typename T> class FunctionCallbackInfo;
105 : template<typename T> class PropertyCallbackInfo;
106 : class StackTrace;
107 : class StackFrame;
108 : class Isolate;
109 : class CallHandlerHelper;
110 : class EscapableHandleScope;
111 : template<typename T> class ReturnValue;
112 :
113 : namespace internal {
114 : class Arguments;
115 : class DeferredHandles;
116 : class Heap;
117 : class HeapObject;
118 : class Isolate;
119 : class LocalEmbedderHeapTracer;
120 : class NeverReadOnlySpaceObject;
121 : struct ScriptStreamingData;
122 : template<typename T> class CustomArguments;
123 : class PropertyCallbackArguments;
124 : class FunctionCallbackArguments;
125 : class GlobalHandles;
126 : class ScopedExternalStringLock;
127 :
128 : namespace wasm {
129 : class NativeModule;
130 : class StreamingDecoder;
131 : } // namespace wasm
132 :
133 : } // namespace internal
134 :
135 : namespace debug {
136 : class ConsoleCallArguments;
137 : } // namespace debug
138 :
139 : // --- Handles ---
140 :
141 : #define TYPE_CHECK(T, S) \
142 : while (false) { \
143 : *(static_cast<T* volatile*>(0)) = static_cast<S*>(0); \
144 : }
145 :
146 : /**
147 : * An object reference managed by the v8 garbage collector.
148 : *
149 : * All objects returned from v8 have to be tracked by the garbage
150 : * collector so that it knows that the objects are still alive. Also,
151 : * because the garbage collector may move objects, it is unsafe to
152 : * point directly to an object. Instead, all objects are stored in
153 : * handles which are known by the garbage collector and updated
154 : * whenever an object moves. Handles should always be passed by value
155 : * (except in cases like out-parameters) and they should never be
156 : * allocated on the heap.
157 : *
158 : * There are two types of handles: local and persistent handles.
159 : *
160 : * Local handles are light-weight and transient and typically used in
161 : * local operations. They are managed by HandleScopes. That means that a
162 : * HandleScope must exist on the stack when they are created and that they are
163 : * only valid inside of the HandleScope active during their creation.
164 : * For passing a local handle to an outer HandleScope, an EscapableHandleScope
165 : * and its Escape() method must be used.
166 : *
167 : * Persistent handles can be used when storing objects across several
168 : * independent operations and have to be explicitly deallocated when they're no
169 : * longer used.
170 : *
171 : * It is safe to extract the object stored in the handle by
172 : * dereferencing the handle (for instance, to extract the Object* from
173 : * a Local<Object>); the value will still be governed by a handle
174 : * behind the scenes and the same rules apply to these values as to
175 : * their handles.
176 : */
177 : template <class T>
178 : class Local {
179 : public:
180 9713069 : V8_INLINE Local() : val_(nullptr) {}
181 : template <class S>
182 : V8_INLINE Local(Local<S> that)
183 20492442 : : val_(reinterpret_cast<T*>(*that)) {
184 : /**
185 : * This check fails when trying to convert between incompatible
186 : * handles. For example, converting from a Local<String> to a
187 : * Local<Number>.
188 : */
189 : TYPE_CHECK(T, S);
190 : }
191 :
192 : /**
193 : * Returns true if the handle is empty.
194 : */
195 40890470 : V8_INLINE bool IsEmpty() const { return val_ == nullptr; }
196 :
197 : /**
198 : * Sets the handle to be empty. IsEmpty() will then return true.
199 : */
200 111617 : V8_INLINE void Clear() { val_ = nullptr; }
201 :
202 71677114 : V8_INLINE T* operator->() const { return val_; }
203 :
204 22348764 : V8_INLINE T* operator*() const { return val_; }
205 :
206 : /**
207 : * Checks whether two handles are the same.
208 : * Returns true if both are empty, or if the objects
209 : * to which they refer are identical.
210 : * The handles' references are not checked.
211 : */
212 : template <class S>
213 : V8_INLINE bool operator==(const Local<S>& that) const {
214 505852 : internal::Address* a = reinterpret_cast<internal::Address*>(this->val_);
215 377271 : internal::Address* b = reinterpret_cast<internal::Address*>(that.val_);
216 508543 : if (a == nullptr) return b == nullptr;
217 507789 : if (b == nullptr) return false;
218 507789 : return *a == *b;
219 : }
220 :
221 : template <class S> V8_INLINE bool operator==(
222 : const PersistentBase<S>& that) const {
223 : internal::Address* a = reinterpret_cast<internal::Address*>(this->val_);
224 10 : internal::Address* b = reinterpret_cast<internal::Address*>(that.val_);
225 44 : if (a == nullptr) return b == nullptr;
226 44 : if (b == nullptr) return false;
227 44 : return *a == *b;
228 : }
229 :
230 : /**
231 : * Checks whether two handles are different.
232 : * Returns true if only one of the handles is empty, or if
233 : * the objects to which they refer are different.
234 : * The handles' references are not checked.
235 : */
236 : template <class S>
237 : V8_INLINE bool operator!=(const Local<S>& that) const {
238 64343 : return !operator==(that);
239 : }
240 :
241 : template <class S> V8_INLINE bool operator!=(
242 : const Persistent<S>& that) const {
243 12 : return !operator==(that);
244 : }
245 :
246 : /**
247 : * Cast a handle to a subclass, e.g. Local<Value> to Local<Object>.
248 : * This is only valid if the handle actually refers to a value of the
249 : * target type.
250 : */
251 : template <class S> V8_INLINE static Local<T> Cast(Local<S> that) {
252 : #ifdef V8_ENABLE_CHECKS
253 : // If we're going to perform the type check then we have to check
254 : // that the handle isn't empty before doing the checked cast.
255 : if (that.IsEmpty()) return Local<T>();
256 : #endif
257 63 : return Local<T>(T::Cast(*that));
258 : }
259 :
260 : /**
261 : * Calling this is equivalent to Local<S>::Cast().
262 : * In particular, this is only valid if the handle actually refers to a value
263 : * of the target type.
264 : */
265 : template <class S>
266 : V8_INLINE Local<S> As() const {
267 : return Local<S>::Cast(*this);
268 : }
269 :
270 : /**
271 : * Create a local handle for the content of another handle.
272 : * The referee is kept alive by the local handle even when
273 : * the original handle is destroyed/disposed.
274 : */
275 : V8_INLINE static Local<T> New(Isolate* isolate, Local<T> that);
276 : V8_INLINE static Local<T> New(Isolate* isolate,
277 : const PersistentBase<T>& that);
278 :
279 : private:
280 : friend class Utils;
281 : template<class F> friend class Eternal;
282 : template<class F> friend class PersistentBase;
283 : template<class F, class M> friend class Persistent;
284 : template<class F> friend class Local;
285 : template <class F>
286 : friend class MaybeLocal;
287 : template<class F> friend class FunctionCallbackInfo;
288 : template<class F> friend class PropertyCallbackInfo;
289 : friend class String;
290 : friend class Object;
291 : friend class Context;
292 : friend class Isolate;
293 : friend class Private;
294 : template<class F> friend class internal::CustomArguments;
295 : friend Local<Primitive> Undefined(Isolate* isolate);
296 : friend Local<Primitive> Null(Isolate* isolate);
297 : friend Local<Boolean> True(Isolate* isolate);
298 : friend Local<Boolean> False(Isolate* isolate);
299 : friend class HandleScope;
300 : friend class EscapableHandleScope;
301 : template <class F1, class F2, class F3>
302 : friend class PersistentValueMapBase;
303 : template<class F1, class F2> friend class PersistentValueVector;
304 : template <class F>
305 : friend class ReturnValue;
306 :
307 81697 : explicit V8_INLINE Local(T* that) : val_(that) {}
308 : V8_INLINE static Local<T> New(Isolate* isolate, T* that);
309 : T* val_;
310 : };
311 :
312 :
313 : #if !defined(V8_IMMINENT_DEPRECATION_WARNINGS)
314 : // Handle is an alias for Local for historical reasons.
315 : template <class T>
316 : using Handle = Local<T>;
317 : #endif
318 :
319 :
320 : /**
321 : * A MaybeLocal<> is a wrapper around Local<> that enforces a check whether
322 : * the Local<> is empty before it can be used.
323 : *
324 : * If an API method returns a MaybeLocal<>, the API method can potentially fail
325 : * either because an exception is thrown, or because an exception is pending,
326 : * e.g. because a previous API call threw an exception that hasn't been caught
327 : * yet, or because a TerminateExecution exception was thrown. In that case, an
328 : * empty MaybeLocal is returned.
329 : */
330 : template <class T>
331 : class MaybeLocal {
332 : public:
333 3120482 : V8_INLINE MaybeLocal() : val_(nullptr) {}
334 : template <class S>
335 : V8_INLINE MaybeLocal(Local<S> that)
336 72313 : : val_(reinterpret_cast<T*>(*that)) {
337 : TYPE_CHECK(T, S);
338 : }
339 :
340 27115 : V8_INLINE bool IsEmpty() const { return val_ == nullptr; }
341 :
342 : /**
343 : * Converts this MaybeLocal<> to a Local<>. If this MaybeLocal<> is empty,
344 : * |false| is returned and |out| is left untouched.
345 : */
346 : template <class S>
347 : V8_WARN_UNUSED_RESULT V8_INLINE bool ToLocal(Local<S>* out) const {
348 19073096 : out->val_ = IsEmpty() ? nullptr : this->val_;
349 : return !IsEmpty();
350 : }
351 :
352 : /**
353 : * Converts this MaybeLocal<> to a Local<>. If this MaybeLocal<> is empty,
354 : * V8 will crash the process.
355 : */
356 : V8_INLINE Local<T> ToLocalChecked();
357 :
358 : /**
359 : * Converts this MaybeLocal<> to a Local<>, using a default value if this
360 : * MaybeLocal<> is empty.
361 : */
362 : template <class S>
363 : V8_INLINE Local<S> FromMaybe(Local<S> default_value) const {
364 8714 : return IsEmpty() ? default_value : Local<S>(val_);
365 : }
366 :
367 : private:
368 : T* val_;
369 : };
370 :
371 : /**
372 : * Eternal handles are set-once handles that live for the lifetime of the
373 : * isolate.
374 : */
375 : template <class T> class Eternal {
376 : public:
377 10235 : V8_INLINE Eternal() : val_(nullptr) {}
378 : template <class S>
379 : V8_INLINE Eternal(Isolate* isolate, Local<S> handle) : val_(nullptr) {
380 : Set(isolate, handle);
381 : }
382 : // Can only be safely called if already set.
383 : V8_INLINE Local<T> Get(Isolate* isolate) const;
384 20475 : V8_INLINE bool IsEmpty() const { return val_ == nullptr; }
385 : template<class S> V8_INLINE void Set(Isolate* isolate, Local<S> handle);
386 :
387 : private:
388 : T* val_;
389 : };
390 :
391 :
392 : static const int kInternalFieldsInWeakCallback = 2;
393 : static const int kEmbedderFieldsInWeakCallback = 2;
394 :
395 : template <typename T>
396 : class WeakCallbackInfo {
397 : public:
398 : typedef void (*Callback)(const WeakCallbackInfo<T>& data);
399 :
400 : WeakCallbackInfo(Isolate* isolate, T* parameter,
401 : void* embedder_fields[kEmbedderFieldsInWeakCallback],
402 : Callback* callback)
403 6916811 : : isolate_(isolate), parameter_(parameter), callback_(callback) {
404 13833622 : for (int i = 0; i < kEmbedderFieldsInWeakCallback; ++i) {
405 13833622 : embedder_fields_[i] = embedder_fields[i];
406 : }
407 : }
408 :
409 : V8_INLINE Isolate* GetIsolate() const { return isolate_; }
410 : V8_INLINE T* GetParameter() const { return parameter_; }
411 : V8_INLINE void* GetInternalField(int index) const;
412 :
413 : // When first called, the embedder MUST Reset() the Global which triggered the
414 : // callback. The Global itself is unusable for anything else. No v8 other api
415 : // calls may be called in the first callback. Should additional work be
416 : // required, the embedder must set a second pass callback, which will be
417 : // called after all the initial callbacks are processed.
418 : // Calling SetSecondPassCallback on the second pass will immediately crash.
419 3235965 : void SetSecondPassCallback(Callback callback) const { *callback_ = callback; }
420 :
421 : private:
422 : Isolate* isolate_;
423 : T* parameter_;
424 : Callback* callback_;
425 : void* embedder_fields_[kEmbedderFieldsInWeakCallback];
426 : };
427 :
428 :
429 : // kParameter will pass a void* parameter back to the callback, kInternalFields
430 : // will pass the first two internal fields back to the callback, kFinalizer
431 : // will pass a void* parameter back, but is invoked before the object is
432 : // actually collected, so it can be resurrected. In the last case, it is not
433 : // possible to request a second pass callback.
434 : enum class WeakCallbackType { kParameter, kInternalFields, kFinalizer };
435 :
436 : /**
437 : * An object reference that is independent of any handle scope. Where
438 : * a Local handle only lives as long as the HandleScope in which it was
439 : * allocated, a PersistentBase handle remains valid until it is explicitly
440 : * disposed using Reset().
441 : *
442 : * A persistent handle contains a reference to a storage cell within
443 : * the V8 engine which holds an object value and which is updated by
444 : * the garbage collector whenever the object is moved. A new storage
445 : * cell can be created using the constructor or PersistentBase::Reset and
446 : * existing handles can be disposed using PersistentBase::Reset.
447 : *
448 : */
449 : template <class T> class PersistentBase {
450 : public:
451 : /**
452 : * If non-empty, destroy the underlying storage cell
453 : * IsEmpty() will return true after this call.
454 : */
455 : V8_INLINE void Reset();
456 : /**
457 : * If non-empty, destroy the underlying storage cell
458 : * and create a new one with the contents of other if other is non empty
459 : */
460 : template <class S>
461 : V8_INLINE void Reset(Isolate* isolate, const Local<S>& other);
462 :
463 : /**
464 : * If non-empty, destroy the underlying storage cell
465 : * and create a new one with the contents of other if other is non empty
466 : */
467 : template <class S>
468 : V8_INLINE void Reset(Isolate* isolate, const PersistentBase<S>& other);
469 :
470 7295183 : V8_INLINE bool IsEmpty() const { return val_ == nullptr; }
471 : V8_INLINE void Empty() { val_ = 0; }
472 :
473 : V8_INLINE Local<T> Get(Isolate* isolate) const {
474 : return Local<T>::New(isolate, *this);
475 : }
476 :
477 : template <class S>
478 : V8_INLINE bool operator==(const PersistentBase<S>& that) const {
479 851 : internal::Address* a = reinterpret_cast<internal::Address*>(this->val_);
480 851 : internal::Address* b = reinterpret_cast<internal::Address*>(that.val_);
481 903 : if (a == nullptr) return b == nullptr;
482 903 : if (b == nullptr) return false;
483 885 : return *a == *b;
484 : }
485 :
486 : template <class S>
487 : V8_INLINE bool operator==(const Local<S>& that) const {
488 2237 : internal::Address* a = reinterpret_cast<internal::Address*>(this->val_);
489 2237 : internal::Address* b = reinterpret_cast<internal::Address*>(that.val_);
490 2261 : if (a == nullptr) return b == nullptr;
491 551 : if (b == nullptr) return false;
492 551 : return *a == *b;
493 : }
494 :
495 : template <class S>
496 : V8_INLINE bool operator!=(const PersistentBase<S>& that) const {
497 6 : return !operator==(that);
498 : }
499 :
500 : template <class S>
501 : V8_INLINE bool operator!=(const Local<S>& that) const {
502 12 : return !operator==(that);
503 : }
504 :
505 : /**
506 : * Install a finalization callback on this object.
507 : * NOTE: There is no guarantee as to *when* or even *if* the callback is
508 : * invoked. The invocation is performed solely on a best effort basis.
509 : * As always, GC-based finalization should *not* be relied upon for any
510 : * critical form of resource management!
511 : */
512 : template <typename P>
513 : V8_INLINE void SetWeak(P* parameter,
514 : typename WeakCallbackInfo<P>::Callback callback,
515 : WeakCallbackType type);
516 :
517 : /**
518 : * Turns this handle into a weak phantom handle without finalization callback.
519 : * The handle will be reset automatically when the garbage collector detects
520 : * that the object is no longer reachable.
521 : * A related function Isolate::NumberOfPhantomHandleResetsSinceLastCall
522 : * returns how many phantom handles were reset by the garbage collector.
523 : */
524 : V8_INLINE void SetWeak();
525 :
526 : template<typename P>
527 : V8_INLINE P* ClearWeak();
528 :
529 : // TODO(dcarney): remove this.
530 : V8_INLINE void ClearWeak() { ClearWeak<void>(); }
531 :
532 : /**
533 : * Annotates the strong handle with the given label, which is then used by the
534 : * heap snapshot generator as a name of the edge from the root to the handle.
535 : * The function does not take ownership of the label and assumes that the
536 : * label is valid as long as the handle is valid.
537 : */
538 : V8_INLINE void AnnotateStrongRetainer(const char* label);
539 :
540 : /**
541 : * Allows the embedder to tell the v8 garbage collector that a certain object
542 : * is alive. Only allowed when the embedder is asked to trace its heap by
543 : * EmbedderHeapTracer.
544 : */
545 : V8_INLINE void RegisterExternalReference(Isolate* isolate) const;
546 :
547 : /**
548 : * Marks the reference to this object independent. Garbage collector is free
549 : * to ignore any object groups containing this object. Weak callback for an
550 : * independent handle should not assume that it will be preceded by a global
551 : * GC prologue callback or followed by a global GC epilogue callback.
552 : */
553 : V8_DEPRECATE_SOON(
554 : "Objects are always considered independent. "
555 : "Use MarkActive to avoid collecting otherwise dead weak handles.",
556 : V8_INLINE void MarkIndependent());
557 :
558 : /**
559 : * Marks the reference to this object as active. The scavenge garbage
560 : * collection should not reclaim the objects marked as active, even if the
561 : * object held by the handle is otherwise unreachable.
562 : *
563 : * This bit is cleared after the each garbage collection pass.
564 : */
565 : V8_INLINE void MarkActive();
566 :
567 : V8_DEPRECATE_SOON("See MarkIndependent.",
568 : V8_INLINE bool IsIndependent() const);
569 :
570 : /** Checks if the handle holds the only reference to an object. */
571 : V8_INLINE bool IsNearDeath() const;
572 :
573 : /** Returns true if the handle's reference is weak. */
574 : V8_INLINE bool IsWeak() const;
575 :
576 : /**
577 : * Assigns a wrapper class ID to the handle. See RetainedObjectInfo interface
578 : * description in v8-profiler.h for details.
579 : */
580 : V8_INLINE void SetWrapperClassId(uint16_t class_id);
581 :
582 : /**
583 : * Returns the class ID previously assigned to this handle or 0 if no class ID
584 : * was previously assigned.
585 : */
586 : V8_INLINE uint16_t WrapperClassId() const;
587 :
588 : PersistentBase(const PersistentBase& other) = delete; // NOLINT
589 : void operator=(const PersistentBase&) = delete;
590 :
591 : private:
592 : friend class Isolate;
593 : friend class Utils;
594 : template<class F> friend class Local;
595 : template<class F1, class F2> friend class Persistent;
596 : template <class F>
597 : friend class Global;
598 : template<class F> friend class PersistentBase;
599 : template<class F> friend class ReturnValue;
600 : template <class F1, class F2, class F3>
601 : friend class PersistentValueMapBase;
602 : template<class F1, class F2> friend class PersistentValueVector;
603 : friend class Object;
604 :
605 3393823 : explicit V8_INLINE PersistentBase(T* val) : val_(val) {}
606 : V8_INLINE static T* New(Isolate* isolate, T* that);
607 :
608 : T* val_;
609 : };
610 :
611 :
612 : /**
613 : * Default traits for Persistent. This class does not allow
614 : * use of the copy constructor or assignment operator.
615 : * At present kResetInDestructor is not set, but that will change in a future
616 : * version.
617 : */
618 : template<class T>
619 : class NonCopyablePersistentTraits {
620 : public:
621 : typedef Persistent<T, NonCopyablePersistentTraits<T> > NonCopyablePersistent;
622 : static const bool kResetInDestructor = false;
623 : template<class S, class M>
624 : V8_INLINE static void Copy(const Persistent<S, M>& source,
625 : NonCopyablePersistent* dest) {
626 : Uncompilable<Object>();
627 : }
628 : // TODO(dcarney): come up with a good compile error here.
629 : template<class O> V8_INLINE static void Uncompilable() {
630 : TYPE_CHECK(O, Primitive);
631 : }
632 : };
633 :
634 :
635 : /**
636 : * Helper class traits to allow copying and assignment of Persistent.
637 : * This will clone the contents of storage cell, but not any of the flags, etc.
638 : */
639 : template<class T>
640 : struct CopyablePersistentTraits {
641 : typedef Persistent<T, CopyablePersistentTraits<T> > CopyablePersistent;
642 : static const bool kResetInDestructor = true;
643 : template<class S, class M>
644 : static V8_INLINE void Copy(const Persistent<S, M>& source,
645 : CopyablePersistent* dest) {
646 : // do nothing, just allow copy
647 : }
648 : };
649 :
650 :
651 : /**
652 : * A PersistentBase which allows copy and assignment.
653 : *
654 : * Copy, assignment and destructor behavior is controlled by the traits
655 : * class M.
656 : *
657 : * Note: Persistent class hierarchy is subject to future changes.
658 : */
659 : template <class T, class M> class Persistent : public PersistentBase<T> {
660 : public:
661 : /**
662 : * A Persistent with no storage cell.
663 : */
664 : V8_INLINE Persistent() : PersistentBase<T>(nullptr) {}
665 : /**
666 : * Construct a Persistent from a Local.
667 : * When the Local is non-empty, a new storage cell is created
668 : * pointing to the same object, and no flags are set.
669 : */
670 : template <class S>
671 : V8_INLINE Persistent(Isolate* isolate, Local<S> that)
672 : : PersistentBase<T>(PersistentBase<T>::New(isolate, *that)) {
673 : TYPE_CHECK(T, S);
674 : }
675 : /**
676 : * Construct a Persistent from a Persistent.
677 : * When the Persistent is non-empty, a new storage cell is created
678 : * pointing to the same object, and no flags are set.
679 : */
680 : template <class S, class M2>
681 : V8_INLINE Persistent(Isolate* isolate, const Persistent<S, M2>& that)
682 : : PersistentBase<T>(PersistentBase<T>::New(isolate, *that)) {
683 : TYPE_CHECK(T, S);
684 : }
685 : /**
686 : * The copy constructors and assignment operator create a Persistent
687 : * exactly as the Persistent constructor, but the Copy function from the
688 : * traits class is called, allowing the setting of flags based on the
689 : * copied Persistent.
690 : */
691 : V8_INLINE Persistent(const Persistent& that) : PersistentBase<T>(nullptr) {
692 : Copy(that);
693 : }
694 : template <class S, class M2>
695 : V8_INLINE Persistent(const Persistent<S, M2>& that) : PersistentBase<T>(0) {
696 : Copy(that);
697 : }
698 : V8_INLINE Persistent& operator=(const Persistent& that) {
699 : Copy(that);
700 : return *this;
701 : }
702 : template <class S, class M2>
703 : V8_INLINE Persistent& operator=(const Persistent<S, M2>& that) { // NOLINT
704 : Copy(that);
705 : return *this;
706 : }
707 : /**
708 : * The destructor will dispose the Persistent based on the
709 : * kResetInDestructor flags in the traits class. Since not calling dispose
710 : * can result in a memory leak, it is recommended to always set this flag.
711 : */
712 226702 : V8_INLINE ~Persistent() {
713 : if (M::kResetInDestructor) this->Reset();
714 226702 : }
715 :
716 : // TODO(dcarney): this is pretty useless, fix or remove
717 : template <class S>
718 : V8_INLINE static Persistent<T>& Cast(const Persistent<S>& that) { // NOLINT
719 : #ifdef V8_ENABLE_CHECKS
720 : // If we're going to perform the type check then we have to check
721 : // that the handle isn't empty before doing the checked cast.
722 : if (!that.IsEmpty()) T::Cast(*that);
723 : #endif
724 : return reinterpret_cast<Persistent<T>&>(const_cast<Persistent<S>&>(that));
725 : }
726 :
727 : // TODO(dcarney): this is pretty useless, fix or remove
728 : template <class S>
729 : V8_INLINE Persistent<S>& As() const { // NOLINT
730 : return Persistent<S>::Cast(*this);
731 : }
732 :
733 : private:
734 : friend class Isolate;
735 : friend class Utils;
736 : template<class F> friend class Local;
737 : template<class F1, class F2> friend class Persistent;
738 : template<class F> friend class ReturnValue;
739 :
740 : explicit V8_INLINE Persistent(T* that) : PersistentBase<T>(that) {}
741 : V8_INLINE T* operator*() const { return this->val_; }
742 : template<class S, class M2>
743 : V8_INLINE void Copy(const Persistent<S, M2>& that);
744 : };
745 :
746 :
747 : /**
748 : * A PersistentBase which has move semantics.
749 : *
750 : * Note: Persistent class hierarchy is subject to future changes.
751 : */
752 : template <class T>
753 : class Global : public PersistentBase<T> {
754 : public:
755 : /**
756 : * A Global with no storage cell.
757 : */
758 : V8_INLINE Global() : PersistentBase<T>(nullptr) {}
759 : /**
760 : * Construct a Global from a Local.
761 : * When the Local is non-empty, a new storage cell is created
762 : * pointing to the same object, and no flags are set.
763 : */
764 : template <class S>
765 : V8_INLINE Global(Isolate* isolate, Local<S> that)
766 : : PersistentBase<T>(PersistentBase<T>::New(isolate, *that)) {
767 : TYPE_CHECK(T, S);
768 : }
769 : /**
770 : * Construct a Global from a PersistentBase.
771 : * When the Persistent is non-empty, a new storage cell is created
772 : * pointing to the same object, and no flags are set.
773 : */
774 : template <class S>
775 : V8_INLINE Global(Isolate* isolate, const PersistentBase<S>& that)
776 : : PersistentBase<T>(PersistentBase<T>::New(isolate, that.val_)) {
777 : TYPE_CHECK(T, S);
778 : }
779 : /**
780 : * Move constructor.
781 : */
782 2462 : V8_INLINE Global(Global&& other) : PersistentBase<T>(other.val_) {
783 2427 : other.val_ = nullptr;
784 : }
785 115092 : V8_INLINE ~Global() { this->Reset(); }
786 : /**
787 : * Move via assignment.
788 : */
789 : template <class S>
790 : V8_INLINE Global& operator=(Global<S>&& rhs) { // NOLINT
791 : TYPE_CHECK(T, S);
792 : if (this != &rhs) {
793 : this->Reset();
794 15 : this->val_ = rhs.val_;
795 15 : rhs.val_ = nullptr;
796 : }
797 : return *this;
798 : }
799 : /**
800 : * Pass allows returning uniques from functions, etc.
801 : */
802 : Global Pass() { return static_cast<Global&&>(*this); } // NOLINT
803 :
804 : /*
805 : * For compatibility with Chromium's base::Bind (base::Passed).
806 : */
807 : typedef void MoveOnlyTypeForCPP03;
808 :
809 : Global(const Global&) = delete;
810 : void operator=(const Global&) = delete;
811 :
812 : private:
813 : template <class F>
814 : friend class ReturnValue;
815 : V8_INLINE T* operator*() const { return this->val_; }
816 : };
817 :
818 :
819 : // UniquePersistent is an alias for Global for historical reason.
820 : template <class T>
821 : using UniquePersistent = Global<T>;
822 :
823 :
824 : /**
825 : * A stack-allocated class that governs a number of local handles.
826 : * After a handle scope has been created, all local handles will be
827 : * allocated within that handle scope until either the handle scope is
828 : * deleted or another handle scope is created. If there is already a
829 : * handle scope and a new one is created, all allocations will take
830 : * place in the new handle scope until it is deleted. After that,
831 : * new handles will again be allocated in the original handle scope.
832 : *
833 : * After the handle scope of a local handle has been deleted the
834 : * garbage collector will no longer track the object stored in the
835 : * handle and may deallocate it. The behavior of accessing a handle
836 : * for which the handle scope has been deleted is undefined.
837 : */
838 : class V8_EXPORT HandleScope {
839 : public:
840 : explicit HandleScope(Isolate* isolate);
841 :
842 : ~HandleScope();
843 :
844 : /**
845 : * Counts the number of allocated handles.
846 : */
847 : static int NumberOfHandles(Isolate* isolate);
848 :
849 : V8_INLINE Isolate* GetIsolate() const {
850 : return reinterpret_cast<Isolate*>(isolate_);
851 : }
852 :
853 : HandleScope(const HandleScope&) = delete;
854 : void operator=(const HandleScope&) = delete;
855 :
856 : protected:
857 : V8_INLINE HandleScope() = default;
858 :
859 : void Initialize(Isolate* isolate);
860 :
861 : static internal::Address* CreateHandle(internal::Isolate* isolate,
862 : internal::Address value);
863 :
864 : private:
865 : // Declaring operator new and delete as deleted is not spec compliant.
866 : // Therefore declare them private instead to disable dynamic alloc
867 : void* operator new(size_t size);
868 : void* operator new[](size_t size);
869 : void operator delete(void*, size_t);
870 : void operator delete[](void*, size_t);
871 :
872 : internal::Isolate* isolate_;
873 : internal::Address* prev_next_;
874 : internal::Address* prev_limit_;
875 :
876 : // Local::New uses CreateHandle with an Isolate* parameter.
877 : template<class F> friend class Local;
878 :
879 : // Object::GetInternalField and Context::GetEmbedderData use CreateHandle with
880 : // a HeapObject in their shortcuts.
881 : friend class Object;
882 : friend class Context;
883 : };
884 :
885 :
886 : /**
887 : * A HandleScope which first allocates a handle in the current scope
888 : * which will be later filled with the escape value.
889 : */
890 : class V8_EXPORT EscapableHandleScope : public HandleScope {
891 : public:
892 : explicit EscapableHandleScope(Isolate* isolate);
893 7646918 : V8_INLINE ~EscapableHandleScope() = default;
894 :
895 : /**
896 : * Pushes the value into the previous scope and returns a handle to it.
897 : * Cannot be called twice.
898 : */
899 : template <class T>
900 : V8_INLINE Local<T> Escape(Local<T> value) {
901 : internal::Address* slot =
902 6776454 : Escape(reinterpret_cast<internal::Address*>(*value));
903 : return Local<T>(reinterpret_cast<T*>(slot));
904 : }
905 :
906 : template <class T>
907 : V8_INLINE MaybeLocal<T> EscapeMaybe(MaybeLocal<T> value) {
908 : return Escape(value.FromMaybe(Local<T>()));
909 : }
910 :
911 : EscapableHandleScope(const EscapableHandleScope&) = delete;
912 : void operator=(const EscapableHandleScope&) = delete;
913 :
914 : private:
915 : // Declaring operator new and delete as deleted is not spec compliant.
916 : // Therefore declare them private instead to disable dynamic alloc
917 : void* operator new(size_t size);
918 : void* operator new[](size_t size);
919 : void operator delete(void*, size_t);
920 : void operator delete[](void*, size_t);
921 :
922 : internal::Address* Escape(internal::Address* escape_value);
923 : internal::Address* escape_slot_;
924 : };
925 :
926 : /**
927 : * A SealHandleScope acts like a handle scope in which no handle allocations
928 : * are allowed. It can be useful for debugging handle leaks.
929 : * Handles can be allocated within inner normal HandleScopes.
930 : */
931 : class V8_EXPORT SealHandleScope {
932 : public:
933 : explicit SealHandleScope(Isolate* isolate);
934 : ~SealHandleScope();
935 :
936 : SealHandleScope(const SealHandleScope&) = delete;
937 : void operator=(const SealHandleScope&) = delete;
938 :
939 : private:
940 : // Declaring operator new and delete as deleted is not spec compliant.
941 : // Therefore declare them private instead to disable dynamic alloc
942 : void* operator new(size_t size);
943 : void* operator new[](size_t size);
944 : void operator delete(void*, size_t);
945 : void operator delete[](void*, size_t);
946 :
947 : internal::Isolate* const isolate_;
948 : internal::Address* prev_limit_;
949 : int prev_sealed_level_;
950 : };
951 :
952 :
953 : // --- Special objects ---
954 :
955 :
956 : /**
957 : * The superclass of values and API object templates.
958 : */
959 : class V8_EXPORT Data {
960 : private:
961 : Data();
962 : };
963 :
964 : /**
965 : * A container type that holds relevant metadata for module loading.
966 : *
967 : * This is passed back to the embedder as part of
968 : * HostImportModuleDynamicallyCallback for module loading.
969 : */
970 : class V8_EXPORT ScriptOrModule {
971 : public:
972 : /**
973 : * The name that was passed by the embedder as ResourceName to the
974 : * ScriptOrigin. This can be either a v8::String or v8::Undefined.
975 : */
976 : Local<Value> GetResourceName();
977 :
978 : /**
979 : * The options that were passed by the embedder as HostDefinedOptions to
980 : * the ScriptOrigin.
981 : */
982 : Local<PrimitiveArray> GetHostDefinedOptions();
983 : };
984 :
985 : /**
986 : * An array to hold Primitive values. This is used by the embedder to
987 : * pass host defined options to the ScriptOptions during compilation.
988 : *
989 : * This is passed back to the embedder as part of
990 : * HostImportModuleDynamicallyCallback for module loading.
991 : *
992 : */
993 : class V8_EXPORT PrimitiveArray {
994 : public:
995 : static Local<PrimitiveArray> New(Isolate* isolate, int length);
996 : int Length() const;
997 : void Set(Isolate* isolate, int index, Local<Primitive> item);
998 : Local<Primitive> Get(Isolate* isolate, int index);
999 : };
1000 :
1001 : /**
1002 : * The optional attributes of ScriptOrigin.
1003 : */
1004 : class ScriptOriginOptions {
1005 : public:
1006 : V8_INLINE ScriptOriginOptions(bool is_shared_cross_origin = false,
1007 : bool is_opaque = false, bool is_wasm = false,
1008 : bool is_module = false)
1009 1324141 : : flags_((is_shared_cross_origin ? kIsSharedCrossOrigin : 0) |
1010 1325760 : (is_wasm ? kIsWasm : 0) | (is_opaque ? kIsOpaque : 0) |
1011 277928 : (is_module ? kIsModule : 0)) {}
1012 : V8_INLINE ScriptOriginOptions(int flags)
1013 3875276 : : flags_(flags &
1014 : (kIsSharedCrossOrigin | kIsOpaque | kIsWasm | kIsModule)) {}
1015 :
1016 : bool IsSharedCrossOrigin() const {
1017 1323263 : return (flags_ & kIsSharedCrossOrigin) != 0;
1018 : }
1019 1323132 : bool IsOpaque() const { return (flags_ & kIsOpaque) != 0; }
1020 5403 : bool IsWasm() const { return (flags_ & kIsWasm) != 0; }
1021 2923438 : bool IsModule() const { return (flags_ & kIsModule) != 0; }
1022 :
1023 1592854 : int Flags() const { return flags_; }
1024 :
1025 : private:
1026 : enum {
1027 : kIsSharedCrossOrigin = 1,
1028 : kIsOpaque = 1 << 1,
1029 : kIsWasm = 1 << 2,
1030 : kIsModule = 1 << 3
1031 : };
1032 : const int flags_;
1033 : };
1034 :
1035 : /**
1036 : * The origin, within a file, of a script.
1037 : */
1038 : class ScriptOrigin {
1039 : public:
1040 : V8_INLINE ScriptOrigin(
1041 : Local<Value> resource_name,
1042 : Local<Integer> resource_line_offset = Local<Integer>(),
1043 : Local<Integer> resource_column_offset = Local<Integer>(),
1044 : Local<Boolean> resource_is_shared_cross_origin = Local<Boolean>(),
1045 : Local<Integer> script_id = Local<Integer>(),
1046 : Local<Value> source_map_url = Local<Value>(),
1047 : Local<Boolean> resource_is_opaque = Local<Boolean>(),
1048 : Local<Boolean> is_wasm = Local<Boolean>(),
1049 : Local<Boolean> is_module = Local<Boolean>(),
1050 : Local<PrimitiveArray> host_defined_options = Local<PrimitiveArray>());
1051 :
1052 : V8_INLINE Local<Value> ResourceName() const;
1053 : V8_INLINE Local<Integer> ResourceLineOffset() const;
1054 : V8_INLINE Local<Integer> ResourceColumnOffset() const;
1055 : V8_INLINE Local<Integer> ScriptID() const;
1056 : V8_INLINE Local<Value> SourceMapUrl() const;
1057 : V8_INLINE Local<PrimitiveArray> HostDefinedOptions() const;
1058 : V8_INLINE ScriptOriginOptions Options() const { return options_; }
1059 :
1060 : private:
1061 : Local<Value> resource_name_;
1062 : Local<Integer> resource_line_offset_;
1063 : Local<Integer> resource_column_offset_;
1064 : ScriptOriginOptions options_;
1065 : Local<Integer> script_id_;
1066 : Local<Value> source_map_url_;
1067 : Local<PrimitiveArray> host_defined_options_;
1068 : };
1069 :
1070 : /**
1071 : * A compiled JavaScript script, not yet tied to a Context.
1072 : */
1073 : class V8_EXPORT UnboundScript {
1074 : public:
1075 : /**
1076 : * Binds the script to the currently entered context.
1077 : */
1078 : Local<Script> BindToCurrentContext();
1079 :
1080 : int GetId();
1081 : Local<Value> GetScriptName();
1082 :
1083 : /**
1084 : * Data read from magic sourceURL comments.
1085 : */
1086 : Local<Value> GetSourceURL();
1087 : /**
1088 : * Data read from magic sourceMappingURL comments.
1089 : */
1090 : Local<Value> GetSourceMappingURL();
1091 :
1092 : /**
1093 : * Returns zero based line number of the code_pos location in the script.
1094 : * -1 will be returned if no information available.
1095 : */
1096 : int GetLineNumber(int code_pos);
1097 :
1098 : static const int kNoScriptId = 0;
1099 : };
1100 :
1101 : /**
1102 : * A compiled JavaScript module, not yet tied to a Context.
1103 : */
1104 : class V8_EXPORT UnboundModuleScript {
1105 : // Only used as a container for code caching.
1106 : };
1107 :
1108 : /**
1109 : * A location in JavaScript source.
1110 : */
1111 : class V8_EXPORT Location {
1112 : public:
1113 : int GetLineNumber() { return line_number_; }
1114 : int GetColumnNumber() { return column_number_; }
1115 :
1116 : Location(int line_number, int column_number)
1117 : : line_number_(line_number), column_number_(column_number) {}
1118 :
1119 : private:
1120 : int line_number_;
1121 : int column_number_;
1122 : };
1123 :
1124 : /**
1125 : * A compiled JavaScript module.
1126 : */
1127 : class V8_EXPORT Module {
1128 : public:
1129 : /**
1130 : * The different states a module can be in.
1131 : *
1132 : * This corresponds to the states used in ECMAScript except that "evaluated"
1133 : * is split into kEvaluated and kErrored, indicating success and failure,
1134 : * respectively.
1135 : */
1136 : enum Status {
1137 : kUninstantiated,
1138 : kInstantiating,
1139 : kInstantiated,
1140 : kEvaluating,
1141 : kEvaluated,
1142 : kErrored
1143 : };
1144 :
1145 : /**
1146 : * Returns the module's current status.
1147 : */
1148 : Status GetStatus() const;
1149 :
1150 : /**
1151 : * For a module in kErrored status, this returns the corresponding exception.
1152 : */
1153 : Local<Value> GetException() const;
1154 :
1155 : /**
1156 : * Returns the number of modules requested by this module.
1157 : */
1158 : int GetModuleRequestsLength() const;
1159 :
1160 : /**
1161 : * Returns the ith module specifier in this module.
1162 : * i must be < GetModuleRequestsLength() and >= 0.
1163 : */
1164 : Local<String> GetModuleRequest(int i) const;
1165 :
1166 : /**
1167 : * Returns the source location (line number and column number) of the ith
1168 : * module specifier's first occurrence in this module.
1169 : */
1170 : Location GetModuleRequestLocation(int i) const;
1171 :
1172 : /**
1173 : * Returns the identity hash for this object.
1174 : */
1175 : int GetIdentityHash() const;
1176 :
1177 : typedef MaybeLocal<Module> (*ResolveCallback)(Local<Context> context,
1178 : Local<String> specifier,
1179 : Local<Module> referrer);
1180 :
1181 : /**
1182 : * Instantiates the module and its dependencies.
1183 : *
1184 : * Returns an empty Maybe<bool> if an exception occurred during
1185 : * instantiation. (In the case where the callback throws an exception, that
1186 : * exception is propagated.)
1187 : */
1188 : V8_WARN_UNUSED_RESULT Maybe<bool> InstantiateModule(Local<Context> context,
1189 : ResolveCallback callback);
1190 :
1191 : /**
1192 : * Evaluates the module and its dependencies.
1193 : *
1194 : * If status is kInstantiated, run the module's code. On success, set status
1195 : * to kEvaluated and return the completion value; on failure, set status to
1196 : * kErrored and propagate the thrown exception (which is then also available
1197 : * via |GetException|).
1198 : */
1199 : V8_WARN_UNUSED_RESULT MaybeLocal<Value> Evaluate(Local<Context> context);
1200 :
1201 : /**
1202 : * Returns the namespace object of this module.
1203 : *
1204 : * The module's status must be at least kInstantiated.
1205 : */
1206 : Local<Value> GetModuleNamespace();
1207 :
1208 : /**
1209 : * Returns the corresponding context-unbound module script.
1210 : *
1211 : * The module must be unevaluated, i.e. its status must not be kEvaluating,
1212 : * kEvaluated or kErrored.
1213 : */
1214 : Local<UnboundModuleScript> GetUnboundModuleScript();
1215 : };
1216 :
1217 : /**
1218 : * A compiled JavaScript script, tied to a Context which was active when the
1219 : * script was compiled.
1220 : */
1221 : class V8_EXPORT Script {
1222 : public:
1223 : /**
1224 : * A shorthand for ScriptCompiler::Compile().
1225 : */
1226 : static V8_WARN_UNUSED_RESULT MaybeLocal<Script> Compile(
1227 : Local<Context> context, Local<String> source,
1228 : ScriptOrigin* origin = nullptr);
1229 :
1230 : /**
1231 : * Runs the script returning the resulting value. It will be run in the
1232 : * context in which it was created (ScriptCompiler::CompileBound or
1233 : * UnboundScript::BindToCurrentContext()).
1234 : */
1235 : V8_WARN_UNUSED_RESULT MaybeLocal<Value> Run(Local<Context> context);
1236 :
1237 : /**
1238 : * Returns the corresponding context-unbound script.
1239 : */
1240 : Local<UnboundScript> GetUnboundScript();
1241 : };
1242 :
1243 :
1244 : /**
1245 : * For compiling scripts.
1246 : */
1247 : class V8_EXPORT ScriptCompiler {
1248 : public:
1249 : /**
1250 : * Compilation data that the embedder can cache and pass back to speed up
1251 : * future compilations. The data is produced if the CompilerOptions passed to
1252 : * the compilation functions in ScriptCompiler contains produce_data_to_cache
1253 : * = true. The data to cache can then can be retrieved from
1254 : * UnboundScript.
1255 : */
1256 : struct V8_EXPORT CachedData {
1257 : enum BufferPolicy {
1258 : BufferNotOwned,
1259 : BufferOwned
1260 : };
1261 :
1262 : CachedData()
1263 : : data(nullptr),
1264 : length(0),
1265 : rejected(false),
1266 : buffer_policy(BufferNotOwned) {}
1267 :
1268 : // If buffer_policy is BufferNotOwned, the caller keeps the ownership of
1269 : // data and guarantees that it stays alive until the CachedData object is
1270 : // destroyed. If the policy is BufferOwned, the given data will be deleted
1271 : // (with delete[]) when the CachedData object is destroyed.
1272 : CachedData(const uint8_t* data, int length,
1273 : BufferPolicy buffer_policy = BufferNotOwned);
1274 : ~CachedData();
1275 : // TODO(marja): Async compilation; add constructors which take a callback
1276 : // which will be called when V8 no longer needs the data.
1277 : const uint8_t* data;
1278 : int length;
1279 : bool rejected;
1280 : BufferPolicy buffer_policy;
1281 :
1282 : // Prevent copying.
1283 : CachedData(const CachedData&) = delete;
1284 : CachedData& operator=(const CachedData&) = delete;
1285 : };
1286 :
1287 : /**
1288 : * Source code which can be then compiled to a UnboundScript or Script.
1289 : */
1290 : class Source {
1291 : public:
1292 : // Source takes ownership of CachedData.
1293 : V8_INLINE Source(Local<String> source_string, const ScriptOrigin& origin,
1294 : CachedData* cached_data = nullptr);
1295 : V8_INLINE Source(Local<String> source_string,
1296 : CachedData* cached_data = nullptr);
1297 : V8_INLINE ~Source();
1298 :
1299 : // Ownership of the CachedData or its buffers is *not* transferred to the
1300 : // caller. The CachedData object is alive as long as the Source object is
1301 : // alive.
1302 : V8_INLINE const CachedData* GetCachedData() const;
1303 :
1304 : V8_INLINE const ScriptOriginOptions& GetResourceOptions() const;
1305 :
1306 : // Prevent copying.
1307 : Source(const Source&) = delete;
1308 : Source& operator=(const Source&) = delete;
1309 :
1310 : private:
1311 : friend class ScriptCompiler;
1312 :
1313 : Local<String> source_string;
1314 :
1315 : // Origin information
1316 : Local<Value> resource_name;
1317 : Local<Integer> resource_line_offset;
1318 : Local<Integer> resource_column_offset;
1319 : ScriptOriginOptions resource_options;
1320 : Local<Value> source_map_url;
1321 : Local<PrimitiveArray> host_defined_options;
1322 :
1323 : // Cached data from previous compilation (if a kConsume*Cache flag is
1324 : // set), or hold newly generated cache data (kProduce*Cache flags) are
1325 : // set when calling a compile method.
1326 : CachedData* cached_data;
1327 : };
1328 :
1329 : /**
1330 : * For streaming incomplete script data to V8. The embedder should implement a
1331 : * subclass of this class.
1332 : */
1333 13541 : class V8_EXPORT ExternalSourceStream {
1334 : public:
1335 13511 : virtual ~ExternalSourceStream() = default;
1336 :
1337 : /**
1338 : * V8 calls this to request the next chunk of data from the embedder. This
1339 : * function will be called on a background thread, so it's OK to block and
1340 : * wait for the data, if the embedder doesn't have data yet. Returns the
1341 : * length of the data returned. When the data ends, GetMoreData should
1342 : * return 0. Caller takes ownership of the data.
1343 : *
1344 : * When streaming UTF-8 data, V8 handles multi-byte characters split between
1345 : * two data chunks, but doesn't handle multi-byte characters split between
1346 : * more than two data chunks. The embedder can avoid this problem by always
1347 : * returning at least 2 bytes of data.
1348 : *
1349 : * When streaming UTF-16 data, V8 does not handle characters split between
1350 : * two data chunks. The embedder has to make sure that chunks have an even
1351 : * length.
1352 : *
1353 : * If the embedder wants to cancel the streaming, they should make the next
1354 : * GetMoreData call return 0. V8 will interpret it as end of data (and most
1355 : * probably, parsing will fail). The streaming task will return as soon as
1356 : * V8 has parsed the data it received so far.
1357 : */
1358 : virtual size_t GetMoreData(const uint8_t** src) = 0;
1359 :
1360 : /**
1361 : * V8 calls this method to set a 'bookmark' at the current position in
1362 : * the source stream, for the purpose of (maybe) later calling
1363 : * ResetToBookmark. If ResetToBookmark is called later, then subsequent
1364 : * calls to GetMoreData should return the same data as they did when
1365 : * SetBookmark was called earlier.
1366 : *
1367 : * The embedder may return 'false' to indicate it cannot provide this
1368 : * functionality.
1369 : */
1370 : virtual bool SetBookmark();
1371 :
1372 : /**
1373 : * V8 calls this to return to a previously set bookmark.
1374 : */
1375 : virtual void ResetToBookmark();
1376 : };
1377 :
1378 : /**
1379 : * Source code which can be streamed into V8 in pieces. It will be parsed
1380 : * while streaming and compiled after parsing has completed. StreamedSource
1381 : * must be kept alive while the streaming task is run (see ScriptStreamingTask
1382 : * below).
1383 : */
1384 26102 : class V8_EXPORT StreamedSource {
1385 : public:
1386 : enum Encoding { ONE_BYTE, TWO_BYTE, UTF8 };
1387 :
1388 : StreamedSource(ExternalSourceStream* source_stream, Encoding encoding);
1389 : ~StreamedSource();
1390 :
1391 : internal::ScriptStreamingData* impl() const { return impl_.get(); }
1392 :
1393 : // Prevent copying.
1394 : StreamedSource(const StreamedSource&) = delete;
1395 : StreamedSource& operator=(const StreamedSource&) = delete;
1396 :
1397 : private:
1398 : std::unique_ptr<internal::ScriptStreamingData> impl_;
1399 : };
1400 :
1401 : /**
1402 : * A streaming task which the embedder must run on a background thread to
1403 : * stream scripts into V8. Returned by ScriptCompiler::StartStreamingScript.
1404 : */
1405 : class V8_EXPORT ScriptStreamingTask final {
1406 : public:
1407 : void Run();
1408 :
1409 : private:
1410 : friend class ScriptCompiler;
1411 :
1412 : explicit ScriptStreamingTask(internal::ScriptStreamingData* data)
1413 13051 : : data_(data) {}
1414 :
1415 : internal::ScriptStreamingData* data_;
1416 : };
1417 :
1418 : enum CompileOptions {
1419 : kNoCompileOptions = 0,
1420 : kConsumeCodeCache,
1421 : kEagerCompile
1422 : };
1423 :
1424 : /**
1425 : * The reason for which we are not requesting or providing a code cache.
1426 : */
1427 : enum NoCacheReason {
1428 : kNoCacheNoReason = 0,
1429 : kNoCacheBecauseCachingDisabled,
1430 : kNoCacheBecauseNoResource,
1431 : kNoCacheBecauseInlineScript,
1432 : kNoCacheBecauseModule,
1433 : kNoCacheBecauseStreamingSource,
1434 : kNoCacheBecauseInspector,
1435 : kNoCacheBecauseScriptTooSmall,
1436 : kNoCacheBecauseCacheTooCold,
1437 : kNoCacheBecauseV8Extension,
1438 : kNoCacheBecauseExtensionModule,
1439 : kNoCacheBecausePacScript,
1440 : kNoCacheBecauseInDocumentWrite,
1441 : kNoCacheBecauseResourceWithNoCacheHandler,
1442 : kNoCacheBecauseDeferredProduceCodeCache
1443 : };
1444 :
1445 : /**
1446 : * Compiles the specified script (context-independent).
1447 : * Cached data as part of the source object can be optionally produced to be
1448 : * consumed later to speed up compilation of identical source scripts.
1449 : *
1450 : * Note that when producing cached data, the source must point to NULL for
1451 : * cached data. When consuming cached data, the cached data must have been
1452 : * produced by the same version of V8.
1453 : *
1454 : * \param source Script source code.
1455 : * \return Compiled script object (context independent; for running it must be
1456 : * bound to a context).
1457 : */
1458 : static V8_WARN_UNUSED_RESULT MaybeLocal<UnboundScript> CompileUnboundScript(
1459 : Isolate* isolate, Source* source,
1460 : CompileOptions options = kNoCompileOptions,
1461 : NoCacheReason no_cache_reason = kNoCacheNoReason);
1462 :
1463 : /**
1464 : * Compiles the specified script (bound to current context).
1465 : *
1466 : * \param source Script source code.
1467 : * \param pre_data Pre-parsing data, as obtained by ScriptData::PreCompile()
1468 : * using pre_data speeds compilation if it's done multiple times.
1469 : * Owned by caller, no references are kept when this function returns.
1470 : * \return Compiled script object, bound to the context that was active
1471 : * when this function was called. When run it will always use this
1472 : * context.
1473 : */
1474 : static V8_WARN_UNUSED_RESULT MaybeLocal<Script> Compile(
1475 : Local<Context> context, Source* source,
1476 : CompileOptions options = kNoCompileOptions,
1477 : NoCacheReason no_cache_reason = kNoCacheNoReason);
1478 :
1479 : /**
1480 : * Returns a task which streams script data into V8, or NULL if the script
1481 : * cannot be streamed. The user is responsible for running the task on a
1482 : * background thread and deleting it. When ran, the task starts parsing the
1483 : * script, and it will request data from the StreamedSource as needed. When
1484 : * ScriptStreamingTask::Run exits, all data has been streamed and the script
1485 : * can be compiled (see Compile below).
1486 : *
1487 : * This API allows to start the streaming with as little data as possible, and
1488 : * the remaining data (for example, the ScriptOrigin) is passed to Compile.
1489 : */
1490 : static ScriptStreamingTask* StartStreamingScript(
1491 : Isolate* isolate, StreamedSource* source,
1492 : CompileOptions options = kNoCompileOptions);
1493 :
1494 : /**
1495 : * Compiles a streamed script (bound to current context).
1496 : *
1497 : * This can only be called after the streaming has finished
1498 : * (ScriptStreamingTask has been run). V8 doesn't construct the source string
1499 : * during streaming, so the embedder needs to pass the full source here.
1500 : */
1501 : static V8_WARN_UNUSED_RESULT MaybeLocal<Script> Compile(
1502 : Local<Context> context, StreamedSource* source,
1503 : Local<String> full_source_string, const ScriptOrigin& origin);
1504 :
1505 : /**
1506 : * Return a version tag for CachedData for the current V8 version & flags.
1507 : *
1508 : * This value is meant only for determining whether a previously generated
1509 : * CachedData instance is still valid; the tag has no other meaing.
1510 : *
1511 : * Background: The data carried by CachedData may depend on the exact
1512 : * V8 version number or current compiler flags. This means that when
1513 : * persisting CachedData, the embedder must take care to not pass in
1514 : * data from another V8 version, or the same version with different
1515 : * features enabled.
1516 : *
1517 : * The easiest way to do so is to clear the embedder's cache on any
1518 : * such change.
1519 : *
1520 : * Alternatively, this tag can be stored alongside the cached data and
1521 : * compared when it is being used.
1522 : */
1523 : static uint32_t CachedDataVersionTag();
1524 :
1525 : /**
1526 : * Compile an ES module, returning a Module that encapsulates
1527 : * the compiled code.
1528 : *
1529 : * Corresponds to the ParseModule abstract operation in the
1530 : * ECMAScript specification.
1531 : */
1532 : static V8_WARN_UNUSED_RESULT MaybeLocal<Module> CompileModule(
1533 : Isolate* isolate, Source* source,
1534 : CompileOptions options = kNoCompileOptions,
1535 : NoCacheReason no_cache_reason = kNoCacheNoReason);
1536 :
1537 : /**
1538 : * Compile a function for a given context. This is equivalent to running
1539 : *
1540 : * with (obj) {
1541 : * return function(args) { ... }
1542 : * }
1543 : *
1544 : * It is possible to specify multiple context extensions (obj in the above
1545 : * example).
1546 : */
1547 : static V8_WARN_UNUSED_RESULT MaybeLocal<Function> CompileFunctionInContext(
1548 : Local<Context> context, Source* source, size_t arguments_count,
1549 : Local<String> arguments[], size_t context_extension_count,
1550 : Local<Object> context_extensions[],
1551 : CompileOptions options = kNoCompileOptions,
1552 : NoCacheReason no_cache_reason = kNoCacheNoReason);
1553 :
1554 : /**
1555 : * Creates and returns code cache for the specified unbound_script.
1556 : * This will return nullptr if the script cannot be serialized. The
1557 : * CachedData returned by this function should be owned by the caller.
1558 : */
1559 : static CachedData* CreateCodeCache(Local<UnboundScript> unbound_script);
1560 :
1561 : /**
1562 : * Creates and returns code cache for the specified unbound_module_script.
1563 : * This will return nullptr if the script cannot be serialized. The
1564 : * CachedData returned by this function should be owned by the caller.
1565 : */
1566 : static CachedData* CreateCodeCache(
1567 : Local<UnboundModuleScript> unbound_module_script);
1568 :
1569 : /**
1570 : * Creates and returns code cache for the specified function that was
1571 : * previously produced by CompileFunctionInContext.
1572 : * This will return nullptr if the script cannot be serialized. The
1573 : * CachedData returned by this function should be owned by the caller.
1574 : */
1575 : static CachedData* CreateCodeCacheForFunction(Local<Function> function);
1576 :
1577 : private:
1578 : static V8_WARN_UNUSED_RESULT MaybeLocal<UnboundScript> CompileUnboundInternal(
1579 : Isolate* isolate, Source* source, CompileOptions options,
1580 : NoCacheReason no_cache_reason);
1581 : };
1582 :
1583 :
1584 : /**
1585 : * An error message.
1586 : */
1587 : class V8_EXPORT Message {
1588 : public:
1589 : Local<String> Get() const;
1590 :
1591 : /**
1592 : * Return the isolate to which the Message belongs.
1593 : */
1594 : Isolate* GetIsolate() const;
1595 :
1596 : V8_WARN_UNUSED_RESULT MaybeLocal<String> GetSourceLine(
1597 : Local<Context> context) const;
1598 :
1599 : /**
1600 : * Returns the origin for the script from where the function causing the
1601 : * error originates.
1602 : */
1603 : ScriptOrigin GetScriptOrigin() const;
1604 :
1605 : /**
1606 : * Returns the resource name for the script from where the function causing
1607 : * the error originates.
1608 : */
1609 : Local<Value> GetScriptResourceName() const;
1610 :
1611 : /**
1612 : * Exception stack trace. By default stack traces are not captured for
1613 : * uncaught exceptions. SetCaptureStackTraceForUncaughtExceptions allows
1614 : * to change this option.
1615 : */
1616 : Local<StackTrace> GetStackTrace() const;
1617 :
1618 : /**
1619 : * Returns the number, 1-based, of the line where the error occurred.
1620 : */
1621 : V8_WARN_UNUSED_RESULT Maybe<int> GetLineNumber(Local<Context> context) const;
1622 :
1623 : /**
1624 : * Returns the index within the script of the first character where
1625 : * the error occurred.
1626 : */
1627 : int GetStartPosition() const;
1628 :
1629 : /**
1630 : * Returns the index within the script of the last character where
1631 : * the error occurred.
1632 : */
1633 : int GetEndPosition() const;
1634 :
1635 : /**
1636 : * Returns the error level of the message.
1637 : */
1638 : int ErrorLevel() const;
1639 :
1640 : /**
1641 : * Returns the index within the line of the first character where
1642 : * the error occurred.
1643 : */
1644 : int GetStartColumn() const;
1645 : V8_WARN_UNUSED_RESULT Maybe<int> GetStartColumn(Local<Context> context) const;
1646 :
1647 : /**
1648 : * Returns the index within the line of the last character where
1649 : * the error occurred.
1650 : */
1651 : int GetEndColumn() const;
1652 : V8_WARN_UNUSED_RESULT Maybe<int> GetEndColumn(Local<Context> context) const;
1653 :
1654 : /**
1655 : * Passes on the value set by the embedder when it fed the script from which
1656 : * this Message was generated to V8.
1657 : */
1658 : bool IsSharedCrossOrigin() const;
1659 : bool IsOpaque() const;
1660 :
1661 : // TODO(1245381): Print to a string instead of on a FILE.
1662 : static void PrintCurrentStackTrace(Isolate* isolate, FILE* out);
1663 :
1664 : static const int kNoLineNumberInfo = 0;
1665 : static const int kNoColumnInfo = 0;
1666 : static const int kNoScriptIdInfo = 0;
1667 : };
1668 :
1669 :
1670 : /**
1671 : * Representation of a JavaScript stack trace. The information collected is a
1672 : * snapshot of the execution stack and the information remains valid after
1673 : * execution continues.
1674 : */
1675 : class V8_EXPORT StackTrace {
1676 : public:
1677 : /**
1678 : * Flags that determine what information is placed captured for each
1679 : * StackFrame when grabbing the current stack trace.
1680 : * Note: these options are deprecated and we always collect all available
1681 : * information (kDetailed).
1682 : */
1683 : enum StackTraceOptions {
1684 : kLineNumber = 1,
1685 : kColumnOffset = 1 << 1 | kLineNumber,
1686 : kScriptName = 1 << 2,
1687 : kFunctionName = 1 << 3,
1688 : kIsEval = 1 << 4,
1689 : kIsConstructor = 1 << 5,
1690 : kScriptNameOrSourceURL = 1 << 6,
1691 : kScriptId = 1 << 7,
1692 : kExposeFramesAcrossSecurityOrigins = 1 << 8,
1693 : kOverview = kLineNumber | kColumnOffset | kScriptName | kFunctionName,
1694 : kDetailed = kOverview | kIsEval | kIsConstructor | kScriptNameOrSourceURL
1695 : };
1696 :
1697 : /**
1698 : * Returns a StackFrame at a particular index.
1699 : */
1700 : Local<StackFrame> GetFrame(Isolate* isolate, uint32_t index) const;
1701 :
1702 : /**
1703 : * Returns the number of StackFrames.
1704 : */
1705 : int GetFrameCount() const;
1706 :
1707 : /**
1708 : * Grab a snapshot of the current JavaScript execution stack.
1709 : *
1710 : * \param frame_limit The maximum number of stack frames we want to capture.
1711 : * \param options Enumerates the set of things we will capture for each
1712 : * StackFrame.
1713 : */
1714 : static Local<StackTrace> CurrentStackTrace(
1715 : Isolate* isolate, int frame_limit, StackTraceOptions options = kDetailed);
1716 : };
1717 :
1718 :
1719 : /**
1720 : * A single JavaScript stack frame.
1721 : */
1722 : class V8_EXPORT StackFrame {
1723 : public:
1724 : /**
1725 : * Returns the number, 1-based, of the line for the associate function call.
1726 : * This method will return Message::kNoLineNumberInfo if it is unable to
1727 : * retrieve the line number, or if kLineNumber was not passed as an option
1728 : * when capturing the StackTrace.
1729 : */
1730 : int GetLineNumber() const;
1731 :
1732 : /**
1733 : * Returns the 1-based column offset on the line for the associated function
1734 : * call.
1735 : * This method will return Message::kNoColumnInfo if it is unable to retrieve
1736 : * the column number, or if kColumnOffset was not passed as an option when
1737 : * capturing the StackTrace.
1738 : */
1739 : int GetColumn() const;
1740 :
1741 : /**
1742 : * Returns the id of the script for the function for this StackFrame.
1743 : * This method will return Message::kNoScriptIdInfo if it is unable to
1744 : * retrieve the script id, or if kScriptId was not passed as an option when
1745 : * capturing the StackTrace.
1746 : */
1747 : int GetScriptId() const;
1748 :
1749 : /**
1750 : * Returns the name of the resource that contains the script for the
1751 : * function for this StackFrame.
1752 : */
1753 : Local<String> GetScriptName() const;
1754 :
1755 : /**
1756 : * Returns the name of the resource that contains the script for the
1757 : * function for this StackFrame or sourceURL value if the script name
1758 : * is undefined and its source ends with //# sourceURL=... string or
1759 : * deprecated //@ sourceURL=... string.
1760 : */
1761 : Local<String> GetScriptNameOrSourceURL() const;
1762 :
1763 : /**
1764 : * Returns the name of the function associated with this stack frame.
1765 : */
1766 : Local<String> GetFunctionName() const;
1767 :
1768 : /**
1769 : * Returns whether or not the associated function is compiled via a call to
1770 : * eval().
1771 : */
1772 : bool IsEval() const;
1773 :
1774 : /**
1775 : * Returns whether or not the associated function is called as a
1776 : * constructor via "new".
1777 : */
1778 : bool IsConstructor() const;
1779 :
1780 : /**
1781 : * Returns whether or not the associated functions is defined in wasm.
1782 : */
1783 : bool IsWasm() const;
1784 : };
1785 :
1786 :
1787 : // A StateTag represents a possible state of the VM.
1788 : enum StateTag {
1789 : JS,
1790 : GC,
1791 : PARSER,
1792 : BYTECODE_COMPILER,
1793 : COMPILER,
1794 : OTHER,
1795 : EXTERNAL,
1796 : IDLE
1797 : };
1798 :
1799 : // A RegisterState represents the current state of registers used
1800 : // by the sampling profiler API.
1801 : struct RegisterState {
1802 27912 : RegisterState() : pc(nullptr), sp(nullptr), fp(nullptr) {}
1803 : void* pc; // Instruction pointer.
1804 : void* sp; // Stack pointer.
1805 : void* fp; // Frame pointer.
1806 : };
1807 :
1808 : // The output structure filled up by GetStackSample API function.
1809 : struct SampleInfo {
1810 : size_t frames_count; // Number of frames collected.
1811 : StateTag vm_state; // Current VM state.
1812 : void* external_callback_entry; // External callback address if VM is
1813 : // executing an external callback.
1814 : };
1815 :
1816 : struct MemoryRange {
1817 : const void* start = nullptr;
1818 : size_t length_in_bytes = 0;
1819 : };
1820 :
1821 : struct JSEntryStub {
1822 : MemoryRange code;
1823 : };
1824 :
1825 : struct UnwindState {
1826 : MemoryRange code_range;
1827 : MemoryRange embedded_code_range;
1828 : JSEntryStub js_entry_stub;
1829 : };
1830 :
1831 : /**
1832 : * A JSON Parser and Stringifier.
1833 : */
1834 : class V8_EXPORT JSON {
1835 : public:
1836 : /**
1837 : * Tries to parse the string |json_string| and returns it as value if
1838 : * successful.
1839 : *
1840 : * \param the context in which to parse and create the value.
1841 : * \param json_string The string to parse.
1842 : * \return The corresponding value if successfully parsed.
1843 : */
1844 : static V8_WARN_UNUSED_RESULT MaybeLocal<Value> Parse(
1845 : Local<Context> context, Local<String> json_string);
1846 :
1847 : /**
1848 : * Tries to stringify the JSON-serializable object |json_object| and returns
1849 : * it as string if successful.
1850 : *
1851 : * \param json_object The JSON-serializable object to stringify.
1852 : * \return The corresponding string if successfully stringified.
1853 : */
1854 : static V8_WARN_UNUSED_RESULT MaybeLocal<String> Stringify(
1855 : Local<Context> context, Local<Value> json_object,
1856 : Local<String> gap = Local<String>());
1857 : };
1858 :
1859 : /**
1860 : * Value serialization compatible with the HTML structured clone algorithm.
1861 : * The format is backward-compatible (i.e. safe to store to disk).
1862 : *
1863 : * WARNING: This API is under development, and changes (including incompatible
1864 : * changes to the API or wire format) may occur without notice until this
1865 : * warning is removed.
1866 : */
1867 : class V8_EXPORT ValueSerializer {
1868 : public:
1869 1921 : class V8_EXPORT Delegate {
1870 : public:
1871 1944 : virtual ~Delegate() = default;
1872 :
1873 : /**
1874 : * Handles the case where a DataCloneError would be thrown in the structured
1875 : * clone spec. Other V8 embedders may throw some other appropriate exception
1876 : * type.
1877 : */
1878 : virtual void ThrowDataCloneError(Local<String> message) = 0;
1879 :
1880 : /**
1881 : * The embedder overrides this method to write some kind of host object, if
1882 : * possible. If not, a suitable exception should be thrown and
1883 : * Nothing<bool>() returned.
1884 : */
1885 : virtual Maybe<bool> WriteHostObject(Isolate* isolate, Local<Object> object);
1886 :
1887 : /**
1888 : * Called when the ValueSerializer is going to serialize a
1889 : * SharedArrayBuffer object. The embedder must return an ID for the
1890 : * object, using the same ID if this SharedArrayBuffer has already been
1891 : * serialized in this buffer. When deserializing, this ID will be passed to
1892 : * ValueDeserializer::GetSharedArrayBufferFromId as |clone_id|.
1893 : *
1894 : * If the object cannot be serialized, an
1895 : * exception should be thrown and Nothing<uint32_t>() returned.
1896 : */
1897 : virtual Maybe<uint32_t> GetSharedArrayBufferId(
1898 : Isolate* isolate, Local<SharedArrayBuffer> shared_array_buffer);
1899 :
1900 : virtual Maybe<uint32_t> GetWasmModuleTransferId(
1901 : Isolate* isolate, Local<WasmModuleObject> module);
1902 : /**
1903 : * Allocates memory for the buffer of at least the size provided. The actual
1904 : * size (which may be greater or equal) is written to |actual_size|. If no
1905 : * buffer has been allocated yet, nullptr will be provided.
1906 : *
1907 : * If the memory cannot be allocated, nullptr should be returned.
1908 : * |actual_size| will be ignored. It is assumed that |old_buffer| is still
1909 : * valid in this case and has not been modified.
1910 : *
1911 : * The default implementation uses the stdlib's `realloc()` function.
1912 : */
1913 : virtual void* ReallocateBufferMemory(void* old_buffer, size_t size,
1914 : size_t* actual_size);
1915 :
1916 : /**
1917 : * Frees a buffer allocated with |ReallocateBufferMemory|.
1918 : *
1919 : * The default implementation uses the stdlib's `free()` function.
1920 : */
1921 : virtual void FreeBufferMemory(void* buffer);
1922 : };
1923 :
1924 : explicit ValueSerializer(Isolate* isolate);
1925 : ValueSerializer(Isolate* isolate, Delegate* delegate);
1926 : ~ValueSerializer();
1927 :
1928 : /**
1929 : * Writes out a header, which includes the format version.
1930 : */
1931 : void WriteHeader();
1932 :
1933 : /**
1934 : * Serializes a JavaScript value into the buffer.
1935 : */
1936 : V8_WARN_UNUSED_RESULT Maybe<bool> WriteValue(Local<Context> context,
1937 : Local<Value> value);
1938 :
1939 : /**
1940 : * Returns the stored data (allocated using the delegate's
1941 : * ReallocateBufferMemory) and its size. This serializer should not be used
1942 : * once the buffer is released. The contents are undefined if a previous write
1943 : * has failed. Ownership of the buffer is transferred to the caller.
1944 : */
1945 : V8_WARN_UNUSED_RESULT std::pair<uint8_t*, size_t> Release();
1946 :
1947 : /**
1948 : * Marks an ArrayBuffer as havings its contents transferred out of band.
1949 : * Pass the corresponding ArrayBuffer in the deserializing context to
1950 : * ValueDeserializer::TransferArrayBuffer.
1951 : */
1952 : void TransferArrayBuffer(uint32_t transfer_id,
1953 : Local<ArrayBuffer> array_buffer);
1954 :
1955 :
1956 : /**
1957 : * Indicate whether to treat ArrayBufferView objects as host objects,
1958 : * i.e. pass them to Delegate::WriteHostObject. This should not be
1959 : * called when no Delegate was passed.
1960 : *
1961 : * The default is not to treat ArrayBufferViews as host objects.
1962 : */
1963 : void SetTreatArrayBufferViewsAsHostObjects(bool mode);
1964 :
1965 : /**
1966 : * Write raw data in various common formats to the buffer.
1967 : * Note that integer types are written in base-128 varint format, not with a
1968 : * binary copy. For use during an override of Delegate::WriteHostObject.
1969 : */
1970 : void WriteUint32(uint32_t value);
1971 : void WriteUint64(uint64_t value);
1972 : void WriteDouble(double value);
1973 : void WriteRawBytes(const void* source, size_t length);
1974 :
1975 : private:
1976 : ValueSerializer(const ValueSerializer&) = delete;
1977 : void operator=(const ValueSerializer&) = delete;
1978 :
1979 : struct PrivateData;
1980 : PrivateData* private_;
1981 : };
1982 :
1983 : /**
1984 : * Deserializes values from data written with ValueSerializer, or a compatible
1985 : * implementation.
1986 : *
1987 : * WARNING: This API is under development, and changes (including incompatible
1988 : * changes to the API or wire format) may occur without notice until this
1989 : * warning is removed.
1990 : */
1991 : class V8_EXPORT ValueDeserializer {
1992 : public:
1993 1695 : class V8_EXPORT Delegate {
1994 : public:
1995 1709 : virtual ~Delegate() = default;
1996 :
1997 : /**
1998 : * The embedder overrides this method to read some kind of host object, if
1999 : * possible. If not, a suitable exception should be thrown and
2000 : * MaybeLocal<Object>() returned.
2001 : */
2002 : virtual MaybeLocal<Object> ReadHostObject(Isolate* isolate);
2003 :
2004 : /**
2005 : * Get a WasmModuleObject given a transfer_id previously provided
2006 : * by ValueSerializer::GetWasmModuleTransferId
2007 : */
2008 : virtual MaybeLocal<WasmModuleObject> GetWasmModuleFromId(
2009 : Isolate* isolate, uint32_t transfer_id);
2010 :
2011 : /**
2012 : * Get a SharedArrayBuffer given a clone_id previously provided
2013 : * by ValueSerializer::GetSharedArrayBufferId
2014 : */
2015 : virtual MaybeLocal<SharedArrayBuffer> GetSharedArrayBufferFromId(
2016 : Isolate* isolate, uint32_t clone_id);
2017 : };
2018 :
2019 : ValueDeserializer(Isolate* isolate, const uint8_t* data, size_t size);
2020 : ValueDeserializer(Isolate* isolate, const uint8_t* data, size_t size,
2021 : Delegate* delegate);
2022 : ~ValueDeserializer();
2023 :
2024 : /**
2025 : * Reads and validates a header (including the format version).
2026 : * May, for example, reject an invalid or unsupported wire format.
2027 : */
2028 : V8_WARN_UNUSED_RESULT Maybe<bool> ReadHeader(Local<Context> context);
2029 :
2030 : /**
2031 : * Deserializes a JavaScript value from the buffer.
2032 : */
2033 : V8_WARN_UNUSED_RESULT MaybeLocal<Value> ReadValue(Local<Context> context);
2034 :
2035 : /**
2036 : * Accepts the array buffer corresponding to the one passed previously to
2037 : * ValueSerializer::TransferArrayBuffer.
2038 : */
2039 : void TransferArrayBuffer(uint32_t transfer_id,
2040 : Local<ArrayBuffer> array_buffer);
2041 :
2042 : /**
2043 : * Similar to TransferArrayBuffer, but for SharedArrayBuffer.
2044 : * The id is not necessarily in the same namespace as unshared ArrayBuffer
2045 : * objects.
2046 : */
2047 : void TransferSharedArrayBuffer(uint32_t id,
2048 : Local<SharedArrayBuffer> shared_array_buffer);
2049 :
2050 : /**
2051 : * Must be called before ReadHeader to enable support for reading the legacy
2052 : * wire format (i.e., which predates this being shipped).
2053 : *
2054 : * Don't use this unless you need to read data written by previous versions of
2055 : * blink::ScriptValueSerializer.
2056 : */
2057 : void SetSupportsLegacyWireFormat(bool supports_legacy_wire_format);
2058 :
2059 : /**
2060 : * Expect inline wasm in the data stream (rather than in-memory transfer)
2061 : */
2062 : void SetExpectInlineWasm(bool allow_inline_wasm);
2063 :
2064 : /**
2065 : * Reads the underlying wire format version. Likely mostly to be useful to
2066 : * legacy code reading old wire format versions. Must be called after
2067 : * ReadHeader.
2068 : */
2069 : uint32_t GetWireFormatVersion() const;
2070 :
2071 : /**
2072 : * Reads raw data in various common formats to the buffer.
2073 : * Note that integer types are read in base-128 varint format, not with a
2074 : * binary copy. For use during an override of Delegate::ReadHostObject.
2075 : */
2076 : V8_WARN_UNUSED_RESULT bool ReadUint32(uint32_t* value);
2077 : V8_WARN_UNUSED_RESULT bool ReadUint64(uint64_t* value);
2078 : V8_WARN_UNUSED_RESULT bool ReadDouble(double* value);
2079 : V8_WARN_UNUSED_RESULT bool ReadRawBytes(size_t length, const void** data);
2080 :
2081 : private:
2082 : ValueDeserializer(const ValueDeserializer&) = delete;
2083 : void operator=(const ValueDeserializer&) = delete;
2084 :
2085 : struct PrivateData;
2086 : PrivateData* private_;
2087 : };
2088 :
2089 :
2090 : // --- Value ---
2091 :
2092 :
2093 : /**
2094 : * The superclass of all JavaScript values and objects.
2095 : */
2096 : class V8_EXPORT Value : public Data {
2097 : public:
2098 : /**
2099 : * Returns true if this value is the undefined value. See ECMA-262
2100 : * 4.3.10.
2101 : */
2102 : V8_INLINE bool IsUndefined() const;
2103 :
2104 : /**
2105 : * Returns true if this value is the null value. See ECMA-262
2106 : * 4.3.11.
2107 : */
2108 : V8_INLINE bool IsNull() const;
2109 :
2110 : /**
2111 : * Returns true if this value is either the null or the undefined value.
2112 : * See ECMA-262
2113 : * 4.3.11. and 4.3.12
2114 : */
2115 : V8_INLINE bool IsNullOrUndefined() const;
2116 :
2117 : /**
2118 : * Returns true if this value is true.
2119 : */
2120 : bool IsTrue() const;
2121 :
2122 : /**
2123 : * Returns true if this value is false.
2124 : */
2125 : bool IsFalse() const;
2126 :
2127 : /**
2128 : * Returns true if this value is a symbol or a string.
2129 : */
2130 : bool IsName() const;
2131 :
2132 : /**
2133 : * Returns true if this value is an instance of the String type.
2134 : * See ECMA-262 8.4.
2135 : */
2136 : V8_INLINE bool IsString() const;
2137 :
2138 : /**
2139 : * Returns true if this value is a symbol.
2140 : */
2141 : bool IsSymbol() const;
2142 :
2143 : /**
2144 : * Returns true if this value is a function.
2145 : */
2146 : bool IsFunction() const;
2147 :
2148 : /**
2149 : * Returns true if this value is an array. Note that it will return false for
2150 : * an Proxy for an array.
2151 : */
2152 : bool IsArray() const;
2153 :
2154 : /**
2155 : * Returns true if this value is an object.
2156 : */
2157 : bool IsObject() const;
2158 :
2159 : /**
2160 : * Returns true if this value is a bigint.
2161 : */
2162 : bool IsBigInt() const;
2163 :
2164 : /**
2165 : * Returns true if this value is boolean.
2166 : */
2167 : bool IsBoolean() const;
2168 :
2169 : /**
2170 : * Returns true if this value is a number.
2171 : */
2172 : bool IsNumber() const;
2173 :
2174 : /**
2175 : * Returns true if this value is external.
2176 : */
2177 : bool IsExternal() const;
2178 :
2179 : /**
2180 : * Returns true if this value is a 32-bit signed integer.
2181 : */
2182 : bool IsInt32() const;
2183 :
2184 : /**
2185 : * Returns true if this value is a 32-bit unsigned integer.
2186 : */
2187 : bool IsUint32() const;
2188 :
2189 : /**
2190 : * Returns true if this value is a Date.
2191 : */
2192 : bool IsDate() const;
2193 :
2194 : /**
2195 : * Returns true if this value is an Arguments object.
2196 : */
2197 : bool IsArgumentsObject() const;
2198 :
2199 : /**
2200 : * Returns true if this value is a BigInt object.
2201 : */
2202 : bool IsBigIntObject() const;
2203 :
2204 : /**
2205 : * Returns true if this value is a Boolean object.
2206 : */
2207 : bool IsBooleanObject() const;
2208 :
2209 : /**
2210 : * Returns true if this value is a Number object.
2211 : */
2212 : bool IsNumberObject() const;
2213 :
2214 : /**
2215 : * Returns true if this value is a String object.
2216 : */
2217 : bool IsStringObject() const;
2218 :
2219 : /**
2220 : * Returns true if this value is a Symbol object.
2221 : */
2222 : bool IsSymbolObject() const;
2223 :
2224 : /**
2225 : * Returns true if this value is a NativeError.
2226 : */
2227 : bool IsNativeError() const;
2228 :
2229 : /**
2230 : * Returns true if this value is a RegExp.
2231 : */
2232 : bool IsRegExp() const;
2233 :
2234 : /**
2235 : * Returns true if this value is an async function.
2236 : */
2237 : bool IsAsyncFunction() const;
2238 :
2239 : /**
2240 : * Returns true if this value is a Generator function.
2241 : */
2242 : bool IsGeneratorFunction() const;
2243 :
2244 : /**
2245 : * Returns true if this value is a Generator object (iterator).
2246 : */
2247 : bool IsGeneratorObject() const;
2248 :
2249 : /**
2250 : * Returns true if this value is a Promise.
2251 : */
2252 : bool IsPromise() const;
2253 :
2254 : /**
2255 : * Returns true if this value is a Map.
2256 : */
2257 : bool IsMap() const;
2258 :
2259 : /**
2260 : * Returns true if this value is a Set.
2261 : */
2262 : bool IsSet() const;
2263 :
2264 : /**
2265 : * Returns true if this value is a Map Iterator.
2266 : */
2267 : bool IsMapIterator() const;
2268 :
2269 : /**
2270 : * Returns true if this value is a Set Iterator.
2271 : */
2272 : bool IsSetIterator() const;
2273 :
2274 : /**
2275 : * Returns true if this value is a WeakMap.
2276 : */
2277 : bool IsWeakMap() const;
2278 :
2279 : /**
2280 : * Returns true if this value is a WeakSet.
2281 : */
2282 : bool IsWeakSet() const;
2283 :
2284 : /**
2285 : * Returns true if this value is an ArrayBuffer.
2286 : */
2287 : bool IsArrayBuffer() const;
2288 :
2289 : /**
2290 : * Returns true if this value is an ArrayBufferView.
2291 : */
2292 : bool IsArrayBufferView() const;
2293 :
2294 : /**
2295 : * Returns true if this value is one of TypedArrays.
2296 : */
2297 : bool IsTypedArray() const;
2298 :
2299 : /**
2300 : * Returns true if this value is an Uint8Array.
2301 : */
2302 : bool IsUint8Array() const;
2303 :
2304 : /**
2305 : * Returns true if this value is an Uint8ClampedArray.
2306 : */
2307 : bool IsUint8ClampedArray() const;
2308 :
2309 : /**
2310 : * Returns true if this value is an Int8Array.
2311 : */
2312 : bool IsInt8Array() const;
2313 :
2314 : /**
2315 : * Returns true if this value is an Uint16Array.
2316 : */
2317 : bool IsUint16Array() const;
2318 :
2319 : /**
2320 : * Returns true if this value is an Int16Array.
2321 : */
2322 : bool IsInt16Array() const;
2323 :
2324 : /**
2325 : * Returns true if this value is an Uint32Array.
2326 : */
2327 : bool IsUint32Array() const;
2328 :
2329 : /**
2330 : * Returns true if this value is an Int32Array.
2331 : */
2332 : bool IsInt32Array() const;
2333 :
2334 : /**
2335 : * Returns true if this value is a Float32Array.
2336 : */
2337 : bool IsFloat32Array() const;
2338 :
2339 : /**
2340 : * Returns true if this value is a Float64Array.
2341 : */
2342 : bool IsFloat64Array() const;
2343 :
2344 : /**
2345 : * Returns true if this value is a BigInt64Array.
2346 : */
2347 : bool IsBigInt64Array() const;
2348 :
2349 : /**
2350 : * Returns true if this value is a BigUint64Array.
2351 : */
2352 : bool IsBigUint64Array() const;
2353 :
2354 : /**
2355 : * Returns true if this value is a DataView.
2356 : */
2357 : bool IsDataView() const;
2358 :
2359 : /**
2360 : * Returns true if this value is a SharedArrayBuffer.
2361 : * This is an experimental feature.
2362 : */
2363 : bool IsSharedArrayBuffer() const;
2364 :
2365 : /**
2366 : * Returns true if this value is a JavaScript Proxy.
2367 : */
2368 : bool IsProxy() const;
2369 :
2370 : bool IsWebAssemblyCompiledModule() const;
2371 :
2372 : /**
2373 : * Returns true if the value is a Module Namespace Object.
2374 : */
2375 : bool IsModuleNamespaceObject() const;
2376 :
2377 : V8_WARN_UNUSED_RESULT MaybeLocal<BigInt> ToBigInt(
2378 : Local<Context> context) const;
2379 : V8_DEPRECATE_SOON("ToBoolean can never throw. Use Local version.",
2380 : V8_WARN_UNUSED_RESULT MaybeLocal<Boolean> ToBoolean(
2381 : Local<Context> context) const);
2382 : V8_WARN_UNUSED_RESULT MaybeLocal<Number> ToNumber(
2383 : Local<Context> context) const;
2384 : V8_WARN_UNUSED_RESULT MaybeLocal<String> ToString(
2385 : Local<Context> context) const;
2386 : V8_WARN_UNUSED_RESULT MaybeLocal<String> ToDetailString(
2387 : Local<Context> context) const;
2388 : V8_WARN_UNUSED_RESULT MaybeLocal<Object> ToObject(
2389 : Local<Context> context) const;
2390 : V8_WARN_UNUSED_RESULT MaybeLocal<Integer> ToInteger(
2391 : Local<Context> context) const;
2392 : V8_WARN_UNUSED_RESULT MaybeLocal<Uint32> ToUint32(
2393 : Local<Context> context) const;
2394 : V8_WARN_UNUSED_RESULT MaybeLocal<Int32> ToInt32(Local<Context> context) const;
2395 :
2396 : Local<Boolean> ToBoolean(Isolate* isolate) const;
2397 : V8_DEPRECATE_SOON("Use maybe version",
2398 : Local<Number> ToNumber(Isolate* isolate) const);
2399 : V8_DEPRECATE_SOON("Use maybe version",
2400 : Local<String> ToString(Isolate* isolate) const);
2401 : V8_DEPRECATE_SOON("Use maybe version",
2402 : Local<Object> ToObject(Isolate* isolate) const);
2403 : V8_DEPRECATE_SOON("Use maybe version",
2404 : Local<Integer> ToInteger(Isolate* isolate) const);
2405 : V8_DEPRECATE_SOON("Use maybe version",
2406 : Local<Int32> ToInt32(Isolate* isolate) const);
2407 :
2408 : /**
2409 : * Attempts to convert a string to an array index.
2410 : * Returns an empty handle if the conversion fails.
2411 : */
2412 : V8_WARN_UNUSED_RESULT MaybeLocal<Uint32> ToArrayIndex(
2413 : Local<Context> context) const;
2414 :
2415 : bool BooleanValue(Isolate* isolate) const;
2416 :
2417 : V8_DEPRECATE_SOON("BooleanValue can never throw. Use Isolate version.",
2418 : V8_WARN_UNUSED_RESULT Maybe<bool> BooleanValue(
2419 : Local<Context> context) const);
2420 : V8_WARN_UNUSED_RESULT Maybe<double> NumberValue(Local<Context> context) const;
2421 : V8_WARN_UNUSED_RESULT Maybe<int64_t> IntegerValue(
2422 : Local<Context> context) const;
2423 : V8_WARN_UNUSED_RESULT Maybe<uint32_t> Uint32Value(
2424 : Local<Context> context) const;
2425 : V8_WARN_UNUSED_RESULT Maybe<int32_t> Int32Value(Local<Context> context) const;
2426 :
2427 : /** JS == */
2428 : V8_WARN_UNUSED_RESULT Maybe<bool> Equals(Local<Context> context,
2429 : Local<Value> that) const;
2430 : bool StrictEquals(Local<Value> that) const;
2431 : bool SameValue(Local<Value> that) const;
2432 :
2433 : template <class T> V8_INLINE static Value* Cast(T* value);
2434 :
2435 : Local<String> TypeOf(Isolate*);
2436 :
2437 : Maybe<bool> InstanceOf(Local<Context> context, Local<Object> object);
2438 :
2439 : private:
2440 : V8_INLINE bool QuickIsUndefined() const;
2441 : V8_INLINE bool QuickIsNull() const;
2442 : V8_INLINE bool QuickIsNullOrUndefined() const;
2443 : V8_INLINE bool QuickIsString() const;
2444 : bool FullIsUndefined() const;
2445 : bool FullIsNull() const;
2446 : bool FullIsString() const;
2447 : };
2448 :
2449 :
2450 : /**
2451 : * The superclass of primitive values. See ECMA-262 4.3.2.
2452 : */
2453 : class V8_EXPORT Primitive : public Value { };
2454 :
2455 :
2456 : /**
2457 : * A primitive boolean value (ECMA-262, 4.3.14). Either the true
2458 : * or false value.
2459 : */
2460 : class V8_EXPORT Boolean : public Primitive {
2461 : public:
2462 : bool Value() const;
2463 : V8_INLINE static Boolean* Cast(v8::Value* obj);
2464 : V8_INLINE static Local<Boolean> New(Isolate* isolate, bool value);
2465 :
2466 : private:
2467 : static void CheckCast(v8::Value* obj);
2468 : };
2469 :
2470 :
2471 : /**
2472 : * A superclass for symbols and strings.
2473 : */
2474 : class V8_EXPORT Name : public Primitive {
2475 : public:
2476 : /**
2477 : * Returns the identity hash for this object. The current implementation
2478 : * uses an inline property on the object to store the identity hash.
2479 : *
2480 : * The return value will never be 0. Also, it is not guaranteed to be
2481 : * unique.
2482 : */
2483 : int GetIdentityHash();
2484 :
2485 : V8_INLINE static Name* Cast(Value* obj);
2486 :
2487 : private:
2488 : static void CheckCast(Value* obj);
2489 : };
2490 :
2491 : /**
2492 : * A flag describing different modes of string creation.
2493 : *
2494 : * Aside from performance implications there are no differences between the two
2495 : * creation modes.
2496 : */
2497 : enum class NewStringType {
2498 : /**
2499 : * Create a new string, always allocating new storage memory.
2500 : */
2501 : kNormal,
2502 :
2503 : /**
2504 : * Acts as a hint that the string should be created in the
2505 : * old generation heap space and be deduplicated if an identical string
2506 : * already exists.
2507 : */
2508 : kInternalized
2509 : };
2510 :
2511 : /**
2512 : * A JavaScript string value (ECMA-262, 4.3.17).
2513 : */
2514 : class V8_EXPORT String : public Name {
2515 : public:
2516 : static constexpr int kMaxLength = internal::kApiTaggedSize == 4
2517 : ? (1 << 28) - 16
2518 : : internal::kSmiMaxValue / 2 - 24;
2519 :
2520 : enum Encoding {
2521 : UNKNOWN_ENCODING = 0x1,
2522 : TWO_BYTE_ENCODING = 0x0,
2523 : ONE_BYTE_ENCODING = 0x8
2524 : };
2525 : /**
2526 : * Returns the number of characters (UTF-16 code units) in this string.
2527 : */
2528 : int Length() const;
2529 :
2530 : /**
2531 : * Returns the number of bytes in the UTF-8 encoded
2532 : * representation of this string.
2533 : */
2534 : int Utf8Length(Isolate* isolate) const;
2535 :
2536 : /**
2537 : * Returns whether this string is known to contain only one byte data,
2538 : * i.e. ISO-8859-1 code points.
2539 : * Does not read the string.
2540 : * False negatives are possible.
2541 : */
2542 : bool IsOneByte() const;
2543 :
2544 : /**
2545 : * Returns whether this string contain only one byte data,
2546 : * i.e. ISO-8859-1 code points.
2547 : * Will read the entire string in some cases.
2548 : */
2549 : bool ContainsOnlyOneByte() const;
2550 :
2551 : /**
2552 : * Write the contents of the string to an external buffer.
2553 : * If no arguments are given, expects the buffer to be large
2554 : * enough to hold the entire string and NULL terminator. Copies
2555 : * the contents of the string and the NULL terminator into the
2556 : * buffer.
2557 : *
2558 : * WriteUtf8 will not write partial UTF-8 sequences, preferring to stop
2559 : * before the end of the buffer.
2560 : *
2561 : * Copies up to length characters into the output buffer.
2562 : * Only null-terminates if there is enough space in the buffer.
2563 : *
2564 : * \param buffer The buffer into which the string will be copied.
2565 : * \param start The starting position within the string at which
2566 : * copying begins.
2567 : * \param length The number of characters to copy from the string. For
2568 : * WriteUtf8 the number of bytes in the buffer.
2569 : * \param nchars_ref The number of characters written, can be NULL.
2570 : * \param options Various options that might affect performance of this or
2571 : * subsequent operations.
2572 : * \return The number of characters copied to the buffer excluding the null
2573 : * terminator. For WriteUtf8: The number of bytes copied to the buffer
2574 : * including the null terminator (if written).
2575 : */
2576 : enum WriteOptions {
2577 : NO_OPTIONS = 0,
2578 : HINT_MANY_WRITES_EXPECTED = 1,
2579 : NO_NULL_TERMINATION = 2,
2580 : PRESERVE_ONE_BYTE_NULL = 4,
2581 : // Used by WriteUtf8 to replace orphan surrogate code units with the
2582 : // unicode replacement character. Needs to be set to guarantee valid UTF-8
2583 : // output.
2584 : REPLACE_INVALID_UTF8 = 8
2585 : };
2586 :
2587 : // 16-bit character codes.
2588 : int Write(Isolate* isolate, uint16_t* buffer, int start = 0, int length = -1,
2589 : int options = NO_OPTIONS) const;
2590 : // One byte characters.
2591 : int WriteOneByte(Isolate* isolate, uint8_t* buffer, int start = 0,
2592 : int length = -1, int options = NO_OPTIONS) const;
2593 : // UTF-8 encoded characters.
2594 : int WriteUtf8(Isolate* isolate, char* buffer, int length = -1,
2595 : int* nchars_ref = nullptr, int options = NO_OPTIONS) const;
2596 :
2597 : /**
2598 : * A zero length string.
2599 : */
2600 : V8_INLINE static Local<String> Empty(Isolate* isolate);
2601 :
2602 : /**
2603 : * Returns true if the string is external
2604 : */
2605 : bool IsExternal() const;
2606 :
2607 : /**
2608 : * Returns true if the string is both external and one-byte.
2609 : */
2610 : bool IsExternalOneByte() const;
2611 :
2612 : class V8_EXPORT ExternalStringResourceBase { // NOLINT
2613 : public:
2614 416484 : virtual ~ExternalStringResourceBase() = default;
2615 :
2616 0 : V8_DEPRECATED("Use IsCacheable().", virtual bool IsCompressible() const) {
2617 0 : return false;
2618 : }
2619 :
2620 : /**
2621 : * If a string is cacheable, the value returned by
2622 : * ExternalStringResource::data() may be cached, otherwise it is not
2623 : * expected to be stable beyond the current top-level task.
2624 : */
2625 24744 : virtual bool IsCacheable() const { return true; }
2626 :
2627 : protected:
2628 593390 : ExternalStringResourceBase() = default;
2629 :
2630 : /**
2631 : * Internally V8 will call this Dispose method when the external string
2632 : * resource is no longer needed. The default implementation will use the
2633 : * delete operator. This method can be overridden in subclasses to
2634 : * control how allocated external string resources are disposed.
2635 : */
2636 83637 : virtual void Dispose() { delete this; }
2637 :
2638 : /**
2639 : * For a non-cacheable string, the value returned by
2640 : * |ExternalStringResource::data()| has to be stable between |Lock()| and
2641 : * |Unlock()|, that is the string must behave as is |IsCacheable()| returned
2642 : * true.
2643 : *
2644 : * These two functions must be thread-safe, and can be called from anywhere.
2645 : * They also must handle lock depth, in the sense that each can be called
2646 : * several times, from different threads, and unlocking should only happen
2647 : * when the balance of Lock() and Unlock() calls is 0.
2648 : */
2649 3735 : virtual void Lock() const {}
2650 :
2651 : /**
2652 : * Unlocks the string.
2653 : */
2654 3729 : virtual void Unlock() const {}
2655 :
2656 : // Disallow copying and assigning.
2657 : ExternalStringResourceBase(const ExternalStringResourceBase&) = delete;
2658 : void operator=(const ExternalStringResourceBase&) = delete;
2659 :
2660 : private:
2661 : friend class internal::Heap;
2662 : friend class v8::String;
2663 : friend class internal::ScopedExternalStringLock;
2664 : };
2665 :
2666 : /**
2667 : * An ExternalStringResource is a wrapper around a two-byte string
2668 : * buffer that resides outside V8's heap. Implement an
2669 : * ExternalStringResource to manage the life cycle of the underlying
2670 : * buffer. Note that the string data must be immutable.
2671 : */
2672 : class V8_EXPORT ExternalStringResource
2673 : : public ExternalStringResourceBase {
2674 : public:
2675 : /**
2676 : * Override the destructor to manage the life cycle of the underlying
2677 : * buffer.
2678 : */
2679 47594 : ~ExternalStringResource() override = default;
2680 :
2681 : /**
2682 : * The string data from the underlying buffer.
2683 : */
2684 : virtual const uint16_t* data() const = 0;
2685 :
2686 : /**
2687 : * The length of the string. That is, the number of two-byte characters.
2688 : */
2689 : virtual size_t length() const = 0;
2690 :
2691 : protected:
2692 47594 : ExternalStringResource() = default;
2693 : };
2694 :
2695 : /**
2696 : * An ExternalOneByteStringResource is a wrapper around an one-byte
2697 : * string buffer that resides outside V8's heap. Implement an
2698 : * ExternalOneByteStringResource to manage the life cycle of the
2699 : * underlying buffer. Note that the string data must be immutable
2700 : * and that the data must be Latin-1 and not UTF-8, which would require
2701 : * special treatment internally in the engine and do not allow efficient
2702 : * indexing. Use String::New or convert to 16 bit data for non-Latin1.
2703 : */
2704 :
2705 : class V8_EXPORT ExternalOneByteStringResource
2706 : : public ExternalStringResourceBase {
2707 : public:
2708 : /**
2709 : * Override the destructor to manage the life cycle of the underlying
2710 : * buffer.
2711 : */
2712 368890 : ~ExternalOneByteStringResource() override = default;
2713 : /** The string data from the underlying buffer.*/
2714 : virtual const char* data() const = 0;
2715 : /** The number of Latin-1 characters in the string.*/
2716 : virtual size_t length() const = 0;
2717 : protected:
2718 545796 : ExternalOneByteStringResource() = default;
2719 : };
2720 :
2721 : /**
2722 : * If the string is an external string, return the ExternalStringResourceBase
2723 : * regardless of the encoding, otherwise return NULL. The encoding of the
2724 : * string is returned in encoding_out.
2725 : */
2726 : V8_INLINE ExternalStringResourceBase* GetExternalStringResourceBase(
2727 : Encoding* encoding_out) const;
2728 :
2729 : /**
2730 : * Get the ExternalStringResource for an external string. Returns
2731 : * NULL if IsExternal() doesn't return true.
2732 : */
2733 : V8_INLINE ExternalStringResource* GetExternalStringResource() const;
2734 :
2735 : /**
2736 : * Get the ExternalOneByteStringResource for an external one-byte string.
2737 : * Returns NULL if IsExternalOneByte() doesn't return true.
2738 : */
2739 : const ExternalOneByteStringResource* GetExternalOneByteStringResource() const;
2740 :
2741 : V8_INLINE static String* Cast(v8::Value* obj);
2742 :
2743 : // TODO(dcarney): remove with deprecation of New functions.
2744 : enum NewStringType {
2745 : kNormalString = static_cast<int>(v8::NewStringType::kNormal),
2746 : kInternalizedString = static_cast<int>(v8::NewStringType::kInternalized)
2747 : };
2748 :
2749 : /** Allocates a new string from UTF-8 data.*/
2750 : static V8_DEPRECATED(
2751 : "Use maybe version",
2752 : Local<String> NewFromUtf8(Isolate* isolate, const char* data,
2753 : NewStringType type = kNormalString,
2754 : int length = -1));
2755 :
2756 : /** Allocates a new string from UTF-8 data. Only returns an empty value when
2757 : * length > kMaxLength. **/
2758 : static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewFromUtf8(
2759 : Isolate* isolate, const char* data, v8::NewStringType type,
2760 : int length = -1);
2761 :
2762 : /** Allocates a new string from Latin-1 data. Only returns an empty value
2763 : * when length > kMaxLength. **/
2764 : static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewFromOneByte(
2765 : Isolate* isolate, const uint8_t* data, v8::NewStringType type,
2766 : int length = -1);
2767 :
2768 : /** Allocates a new string from UTF-16 data.*/
2769 : static V8_DEPRECATE_SOON(
2770 : "Use maybe version",
2771 : Local<String> NewFromTwoByte(Isolate* isolate, const uint16_t* data,
2772 : NewStringType type = kNormalString,
2773 : int length = -1));
2774 :
2775 : /** Allocates a new string from UTF-16 data. Only returns an empty value when
2776 : * length > kMaxLength. **/
2777 : static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewFromTwoByte(
2778 : Isolate* isolate, const uint16_t* data, v8::NewStringType type,
2779 : int length = -1);
2780 :
2781 : /**
2782 : * Creates a new string by concatenating the left and the right strings
2783 : * passed in as parameters.
2784 : */
2785 : static Local<String> Concat(Isolate* isolate, Local<String> left,
2786 : Local<String> right);
2787 :
2788 : /**
2789 : * Creates a new external string using the data defined in the given
2790 : * resource. When the external string is no longer live on V8's heap the
2791 : * resource will be disposed by calling its Dispose method. The caller of
2792 : * this function should not otherwise delete or modify the resource. Neither
2793 : * should the underlying buffer be deallocated or modified except through the
2794 : * destructor of the external string resource.
2795 : */
2796 : static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewExternalTwoByte(
2797 : Isolate* isolate, ExternalStringResource* resource);
2798 :
2799 : /**
2800 : * Associate an external string resource with this string by transforming it
2801 : * in place so that existing references to this string in the JavaScript heap
2802 : * will use the external string resource. The external string resource's
2803 : * character contents need to be equivalent to this string.
2804 : * Returns true if the string has been changed to be an external string.
2805 : * The string is not modified if the operation fails. See NewExternal for
2806 : * information on the lifetime of the resource.
2807 : */
2808 : bool MakeExternal(ExternalStringResource* resource);
2809 :
2810 : /**
2811 : * Creates a new external string using the one-byte data defined in the given
2812 : * resource. When the external string is no longer live on V8's heap the
2813 : * resource will be disposed by calling its Dispose method. The caller of
2814 : * this function should not otherwise delete or modify the resource. Neither
2815 : * should the underlying buffer be deallocated or modified except through the
2816 : * destructor of the external string resource.
2817 : */
2818 : static V8_DEPRECATE_SOON(
2819 : "Use maybe version",
2820 : Local<String> NewExternal(Isolate* isolate,
2821 : ExternalOneByteStringResource* resource));
2822 : static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewExternalOneByte(
2823 : Isolate* isolate, ExternalOneByteStringResource* resource);
2824 :
2825 : /**
2826 : * Associate an external string resource with this string by transforming it
2827 : * in place so that existing references to this string in the JavaScript heap
2828 : * will use the external string resource. The external string resource's
2829 : * character contents need to be equivalent to this string.
2830 : * Returns true if the string has been changed to be an external string.
2831 : * The string is not modified if the operation fails. See NewExternal for
2832 : * information on the lifetime of the resource.
2833 : */
2834 : bool MakeExternal(ExternalOneByteStringResource* resource);
2835 :
2836 : /**
2837 : * Returns true if this string can be made external.
2838 : */
2839 : bool CanMakeExternal();
2840 :
2841 : /**
2842 : * Returns true if the strings values are equal. Same as JS ==/===.
2843 : */
2844 : bool StringEquals(Local<String> str);
2845 :
2846 : /**
2847 : * Converts an object to a UTF-8-encoded character array. Useful if
2848 : * you want to print the object. If conversion to a string fails
2849 : * (e.g. due to an exception in the toString() method of the object)
2850 : * then the length() method returns 0 and the * operator returns
2851 : * NULL.
2852 : */
2853 : class V8_EXPORT Utf8Value {
2854 : public:
2855 : Utf8Value(Isolate* isolate, Local<v8::Value> obj);
2856 : ~Utf8Value();
2857 : char* operator*() { return str_; }
2858 : const char* operator*() const { return str_; }
2859 : int length() const { return length_; }
2860 :
2861 : // Disallow copying and assigning.
2862 : Utf8Value(const Utf8Value&) = delete;
2863 : void operator=(const Utf8Value&) = delete;
2864 :
2865 : private:
2866 : char* str_;
2867 : int length_;
2868 : };
2869 :
2870 : /**
2871 : * Converts an object to a two-byte (UTF-16-encoded) string.
2872 : * If conversion to a string fails (eg. due to an exception in the toString()
2873 : * method of the object) then the length() method returns 0 and the * operator
2874 : * returns NULL.
2875 : */
2876 : class V8_EXPORT Value {
2877 : public:
2878 : Value(Isolate* isolate, Local<v8::Value> obj);
2879 : ~Value();
2880 : uint16_t* operator*() { return str_; }
2881 : const uint16_t* operator*() const { return str_; }
2882 : int length() const { return length_; }
2883 :
2884 : // Disallow copying and assigning.
2885 : Value(const Value&) = delete;
2886 : void operator=(const Value&) = delete;
2887 :
2888 : private:
2889 : uint16_t* str_;
2890 : int length_;
2891 : };
2892 :
2893 : private:
2894 : void VerifyExternalStringResourceBase(ExternalStringResourceBase* v,
2895 : Encoding encoding) const;
2896 : void VerifyExternalStringResource(ExternalStringResource* val) const;
2897 : ExternalStringResource* GetExternalStringResourceSlow() const;
2898 : ExternalStringResourceBase* GetExternalStringResourceBaseSlow(
2899 : String::Encoding* encoding_out) const;
2900 :
2901 : static void CheckCast(v8::Value* obj);
2902 : };
2903 :
2904 :
2905 : /**
2906 : * A JavaScript symbol (ECMA-262 edition 6)
2907 : */
2908 : class V8_EXPORT Symbol : public Name {
2909 : public:
2910 : /**
2911 : * Returns the print name string of the symbol, or undefined if none.
2912 : */
2913 : Local<Value> Name() const;
2914 :
2915 : /**
2916 : * Create a symbol. If name is not empty, it will be used as the description.
2917 : */
2918 : static Local<Symbol> New(Isolate* isolate,
2919 : Local<String> name = Local<String>());
2920 :
2921 : /**
2922 : * Access global symbol registry.
2923 : * Note that symbols created this way are never collected, so
2924 : * they should only be used for statically fixed properties.
2925 : * Also, there is only one global name space for the names used as keys.
2926 : * To minimize the potential for clashes, use qualified names as keys.
2927 : */
2928 : static Local<Symbol> For(Isolate *isolate, Local<String> name);
2929 :
2930 : /**
2931 : * Retrieve a global symbol. Similar to |For|, but using a separate
2932 : * registry that is not accessible by (and cannot clash with) JavaScript code.
2933 : */
2934 : static Local<Symbol> ForApi(Isolate *isolate, Local<String> name);
2935 :
2936 : // Well-known symbols
2937 : static Local<Symbol> GetAsyncIterator(Isolate* isolate);
2938 : static Local<Symbol> GetHasInstance(Isolate* isolate);
2939 : static Local<Symbol> GetIsConcatSpreadable(Isolate* isolate);
2940 : static Local<Symbol> GetIterator(Isolate* isolate);
2941 : static Local<Symbol> GetMatch(Isolate* isolate);
2942 : static Local<Symbol> GetReplace(Isolate* isolate);
2943 : static Local<Symbol> GetSearch(Isolate* isolate);
2944 : static Local<Symbol> GetSplit(Isolate* isolate);
2945 : static Local<Symbol> GetToPrimitive(Isolate* isolate);
2946 : static Local<Symbol> GetToStringTag(Isolate* isolate);
2947 : static Local<Symbol> GetUnscopables(Isolate* isolate);
2948 :
2949 : V8_INLINE static Symbol* Cast(Value* obj);
2950 :
2951 : private:
2952 : Symbol();
2953 : static void CheckCast(Value* obj);
2954 : };
2955 :
2956 :
2957 : /**
2958 : * A private symbol
2959 : *
2960 : * This is an experimental feature. Use at your own risk.
2961 : */
2962 : class V8_EXPORT Private : public Data {
2963 : public:
2964 : /**
2965 : * Returns the print name string of the private symbol, or undefined if none.
2966 : */
2967 : Local<Value> Name() const;
2968 :
2969 : /**
2970 : * Create a private symbol. If name is not empty, it will be the description.
2971 : */
2972 : static Local<Private> New(Isolate* isolate,
2973 : Local<String> name = Local<String>());
2974 :
2975 : /**
2976 : * Retrieve a global private symbol. If a symbol with this name has not
2977 : * been retrieved in the same isolate before, it is created.
2978 : * Note that private symbols created this way are never collected, so
2979 : * they should only be used for statically fixed properties.
2980 : * Also, there is only one global name space for the names used as keys.
2981 : * To minimize the potential for clashes, use qualified names as keys,
2982 : * e.g., "Class#property".
2983 : */
2984 : static Local<Private> ForApi(Isolate* isolate, Local<String> name);
2985 :
2986 : V8_INLINE static Private* Cast(Data* data);
2987 :
2988 : private:
2989 : Private();
2990 :
2991 : static void CheckCast(Data* that);
2992 : };
2993 :
2994 :
2995 : /**
2996 : * A JavaScript number value (ECMA-262, 4.3.20)
2997 : */
2998 : class V8_EXPORT Number : public Primitive {
2999 : public:
3000 : double Value() const;
3001 : static Local<Number> New(Isolate* isolate, double value);
3002 : V8_INLINE static Number* Cast(v8::Value* obj);
3003 : private:
3004 : Number();
3005 : static void CheckCast(v8::Value* obj);
3006 : };
3007 :
3008 :
3009 : /**
3010 : * A JavaScript value representing a signed integer.
3011 : */
3012 : class V8_EXPORT Integer : public Number {
3013 : public:
3014 : static Local<Integer> New(Isolate* isolate, int32_t value);
3015 : static Local<Integer> NewFromUnsigned(Isolate* isolate, uint32_t value);
3016 : int64_t Value() const;
3017 : V8_INLINE static Integer* Cast(v8::Value* obj);
3018 : private:
3019 : Integer();
3020 : static void CheckCast(v8::Value* obj);
3021 : };
3022 :
3023 :
3024 : /**
3025 : * A JavaScript value representing a 32-bit signed integer.
3026 : */
3027 : class V8_EXPORT Int32 : public Integer {
3028 : public:
3029 : int32_t Value() const;
3030 : V8_INLINE static Int32* Cast(v8::Value* obj);
3031 :
3032 : private:
3033 : Int32();
3034 : static void CheckCast(v8::Value* obj);
3035 : };
3036 :
3037 :
3038 : /**
3039 : * A JavaScript value representing a 32-bit unsigned integer.
3040 : */
3041 : class V8_EXPORT Uint32 : public Integer {
3042 : public:
3043 : uint32_t Value() const;
3044 : V8_INLINE static Uint32* Cast(v8::Value* obj);
3045 :
3046 : private:
3047 : Uint32();
3048 : static void CheckCast(v8::Value* obj);
3049 : };
3050 :
3051 : /**
3052 : * A JavaScript BigInt value (https://tc39.github.io/proposal-bigint)
3053 : */
3054 : class V8_EXPORT BigInt : public Primitive {
3055 : public:
3056 : static Local<BigInt> New(Isolate* isolate, int64_t value);
3057 : static Local<BigInt> NewFromUnsigned(Isolate* isolate, uint64_t value);
3058 : /**
3059 : * Creates a new BigInt object using a specified sign bit and a
3060 : * specified list of digits/words.
3061 : * The resulting number is calculated as:
3062 : *
3063 : * (-1)^sign_bit * (words[0] * (2^64)^0 + words[1] * (2^64)^1 + ...)
3064 : */
3065 : static MaybeLocal<BigInt> NewFromWords(Local<Context> context, int sign_bit,
3066 : int word_count, const uint64_t* words);
3067 :
3068 : /**
3069 : * Returns the value of this BigInt as an unsigned 64-bit integer.
3070 : * If `lossless` is provided, it will reflect whether the return value was
3071 : * truncated or wrapped around. In particular, it is set to `false` if this
3072 : * BigInt is negative.
3073 : */
3074 : uint64_t Uint64Value(bool* lossless = nullptr) const;
3075 :
3076 : /**
3077 : * Returns the value of this BigInt as a signed 64-bit integer.
3078 : * If `lossless` is provided, it will reflect whether this BigInt was
3079 : * truncated or not.
3080 : */
3081 : int64_t Int64Value(bool* lossless = nullptr) const;
3082 :
3083 : /**
3084 : * Returns the number of 64-bit words needed to store the result of
3085 : * ToWordsArray().
3086 : */
3087 : int WordCount() const;
3088 :
3089 : /**
3090 : * Writes the contents of this BigInt to a specified memory location.
3091 : * `sign_bit` must be provided and will be set to 1 if this BigInt is
3092 : * negative.
3093 : * `*word_count` has to be initialized to the length of the `words` array.
3094 : * Upon return, it will be set to the actual number of words that would
3095 : * be needed to store this BigInt (i.e. the return value of `WordCount()`).
3096 : */
3097 : void ToWordsArray(int* sign_bit, int* word_count, uint64_t* words) const;
3098 :
3099 : V8_INLINE static BigInt* Cast(v8::Value* obj);
3100 :
3101 : private:
3102 : BigInt();
3103 : static void CheckCast(v8::Value* obj);
3104 : };
3105 :
3106 : /**
3107 : * PropertyAttribute.
3108 : */
3109 : enum PropertyAttribute {
3110 : /** None. **/
3111 : None = 0,
3112 : /** ReadOnly, i.e., not writable. **/
3113 : ReadOnly = 1 << 0,
3114 : /** DontEnum, i.e., not enumerable. **/
3115 : DontEnum = 1 << 1,
3116 : /** DontDelete, i.e., not configurable. **/
3117 : DontDelete = 1 << 2
3118 : };
3119 :
3120 : /**
3121 : * Accessor[Getter|Setter] are used as callback functions when
3122 : * setting|getting a particular property. See Object and ObjectTemplate's
3123 : * method SetAccessor.
3124 : */
3125 : typedef void (*AccessorGetterCallback)(
3126 : Local<String> property,
3127 : const PropertyCallbackInfo<Value>& info);
3128 : typedef void (*AccessorNameGetterCallback)(
3129 : Local<Name> property,
3130 : const PropertyCallbackInfo<Value>& info);
3131 :
3132 :
3133 : typedef void (*AccessorSetterCallback)(
3134 : Local<String> property,
3135 : Local<Value> value,
3136 : const PropertyCallbackInfo<void>& info);
3137 : typedef void (*AccessorNameSetterCallback)(
3138 : Local<Name> property,
3139 : Local<Value> value,
3140 : const PropertyCallbackInfo<void>& info);
3141 :
3142 :
3143 : /**
3144 : * Access control specifications.
3145 : *
3146 : * Some accessors should be accessible across contexts. These
3147 : * accessors have an explicit access control parameter which specifies
3148 : * the kind of cross-context access that should be allowed.
3149 : *
3150 : * TODO(dcarney): Remove PROHIBITS_OVERWRITING as it is now unused.
3151 : */
3152 : enum AccessControl {
3153 : DEFAULT = 0,
3154 : ALL_CAN_READ = 1,
3155 : ALL_CAN_WRITE = 1 << 1,
3156 : PROHIBITS_OVERWRITING = 1 << 2
3157 : };
3158 :
3159 : /**
3160 : * Property filter bits. They can be or'ed to build a composite filter.
3161 : */
3162 : enum PropertyFilter {
3163 : ALL_PROPERTIES = 0,
3164 : ONLY_WRITABLE = 1,
3165 : ONLY_ENUMERABLE = 2,
3166 : ONLY_CONFIGURABLE = 4,
3167 : SKIP_STRINGS = 8,
3168 : SKIP_SYMBOLS = 16
3169 : };
3170 :
3171 : /**
3172 : * Options for marking whether callbacks may trigger JS-observable side effects.
3173 : * Side-effect-free callbacks are whitelisted during debug evaluation with
3174 : * throwOnSideEffect. It applies when calling a Function, FunctionTemplate,
3175 : * or an Accessor callback. For Interceptors, please see
3176 : * PropertyHandlerFlags's kHasNoSideEffect.
3177 : * Callbacks that only cause side effects to the receiver are whitelisted if
3178 : * invoked on receiver objects that are created within the same debug-evaluate
3179 : * call, as these objects are temporary and the side effect does not escape.
3180 : */
3181 : enum class SideEffectType {
3182 : kHasSideEffect,
3183 : kHasNoSideEffect,
3184 : kHasSideEffectToReceiver
3185 : };
3186 :
3187 : /**
3188 : * Keys/Properties filter enums:
3189 : *
3190 : * KeyCollectionMode limits the range of collected properties. kOwnOnly limits
3191 : * the collected properties to the given Object only. kIncludesPrototypes will
3192 : * include all keys of the objects's prototype chain as well.
3193 : */
3194 : enum class KeyCollectionMode { kOwnOnly, kIncludePrototypes };
3195 :
3196 : /**
3197 : * kIncludesIndices allows for integer indices to be collected, while
3198 : * kSkipIndices will exclude integer indices from being collected.
3199 : */
3200 : enum class IndexFilter { kIncludeIndices, kSkipIndices };
3201 :
3202 : /**
3203 : * kConvertToString will convert integer indices to strings.
3204 : * kKeepNumbers will return numbers for integer indices.
3205 : */
3206 : enum class KeyConversionMode { kConvertToString, kKeepNumbers };
3207 :
3208 : /**
3209 : * Integrity level for objects.
3210 : */
3211 : enum class IntegrityLevel { kFrozen, kSealed };
3212 :
3213 : /**
3214 : * A JavaScript object (ECMA-262, 4.3.3)
3215 : */
3216 : class V8_EXPORT Object : public Value {
3217 : public:
3218 : V8_DEPRECATE_SOON("Use maybe version",
3219 : bool Set(Local<Value> key, Local<Value> value));
3220 : /**
3221 : * Set only return Just(true) or Empty(), so if it should never fail, use
3222 : * result.Check().
3223 : */
3224 : V8_WARN_UNUSED_RESULT Maybe<bool> Set(Local<Context> context,
3225 : Local<Value> key, Local<Value> value);
3226 :
3227 : V8_DEPRECATE_SOON("Use maybe version",
3228 : bool Set(uint32_t index, Local<Value> value));
3229 : V8_WARN_UNUSED_RESULT Maybe<bool> Set(Local<Context> context, uint32_t index,
3230 : Local<Value> value);
3231 :
3232 : // Implements CreateDataProperty (ECMA-262, 7.3.4).
3233 : //
3234 : // Defines a configurable, writable, enumerable property with the given value
3235 : // on the object unless the property already exists and is not configurable
3236 : // or the object is not extensible.
3237 : //
3238 : // Returns true on success.
3239 : V8_WARN_UNUSED_RESULT Maybe<bool> CreateDataProperty(Local<Context> context,
3240 : Local<Name> key,
3241 : Local<Value> value);
3242 : V8_WARN_UNUSED_RESULT Maybe<bool> CreateDataProperty(Local<Context> context,
3243 : uint32_t index,
3244 : Local<Value> value);
3245 :
3246 : // Implements DefineOwnProperty.
3247 : //
3248 : // In general, CreateDataProperty will be faster, however, does not allow
3249 : // for specifying attributes.
3250 : //
3251 : // Returns true on success.
3252 : V8_WARN_UNUSED_RESULT Maybe<bool> DefineOwnProperty(
3253 : Local<Context> context, Local<Name> key, Local<Value> value,
3254 : PropertyAttribute attributes = None);
3255 :
3256 : // Implements Object.DefineProperty(O, P, Attributes), see Ecma-262 19.1.2.4.
3257 : //
3258 : // The defineProperty function is used to add an own property or
3259 : // update the attributes of an existing own property of an object.
3260 : //
3261 : // Both data and accessor descriptors can be used.
3262 : //
3263 : // In general, CreateDataProperty is faster, however, does not allow
3264 : // for specifying attributes or an accessor descriptor.
3265 : //
3266 : // The PropertyDescriptor can change when redefining a property.
3267 : //
3268 : // Returns true on success.
3269 : V8_WARN_UNUSED_RESULT Maybe<bool> DefineProperty(
3270 : Local<Context> context, Local<Name> key, PropertyDescriptor& descriptor);
3271 :
3272 : V8_DEPRECATE_SOON("Use maybe version", Local<Value> Get(Local<Value> key));
3273 : V8_WARN_UNUSED_RESULT MaybeLocal<Value> Get(Local<Context> context,
3274 : Local<Value> key);
3275 :
3276 : V8_DEPRECATE_SOON("Use maybe version", Local<Value> Get(uint32_t index));
3277 : V8_WARN_UNUSED_RESULT MaybeLocal<Value> Get(Local<Context> context,
3278 : uint32_t index);
3279 :
3280 : /**
3281 : * Gets the property attributes of a property which can be None or
3282 : * any combination of ReadOnly, DontEnum and DontDelete. Returns
3283 : * None when the property doesn't exist.
3284 : */
3285 : V8_WARN_UNUSED_RESULT Maybe<PropertyAttribute> GetPropertyAttributes(
3286 : Local<Context> context, Local<Value> key);
3287 :
3288 : /**
3289 : * Returns Object.getOwnPropertyDescriptor as per ES2016 section 19.1.2.6.
3290 : */
3291 : V8_WARN_UNUSED_RESULT MaybeLocal<Value> GetOwnPropertyDescriptor(
3292 : Local<Context> context, Local<Name> key);
3293 :
3294 : /**
3295 : * Object::Has() calls the abstract operation HasProperty(O, P) described
3296 : * in ECMA-262, 7.3.10. Has() returns
3297 : * true, if the object has the property, either own or on the prototype chain.
3298 : * Interceptors, i.e., PropertyQueryCallbacks, are called if present.
3299 : *
3300 : * Has() has the same side effects as JavaScript's `variable in object`.
3301 : * For example, calling Has() on a revoked proxy will throw an exception.
3302 : *
3303 : * \note Has() converts the key to a name, which possibly calls back into
3304 : * JavaScript.
3305 : *
3306 : * See also v8::Object::HasOwnProperty() and
3307 : * v8::Object::HasRealNamedProperty().
3308 : */
3309 : V8_WARN_UNUSED_RESULT Maybe<bool> Has(Local<Context> context,
3310 : Local<Value> key);
3311 :
3312 : V8_WARN_UNUSED_RESULT Maybe<bool> Delete(Local<Context> context,
3313 : Local<Value> key);
3314 :
3315 : V8_WARN_UNUSED_RESULT Maybe<bool> Has(Local<Context> context, uint32_t index);
3316 :
3317 : V8_WARN_UNUSED_RESULT Maybe<bool> Delete(Local<Context> context,
3318 : uint32_t index);
3319 :
3320 : /**
3321 : * Note: SideEffectType affects the getter only, not the setter.
3322 : */
3323 : V8_WARN_UNUSED_RESULT Maybe<bool> SetAccessor(
3324 : Local<Context> context, Local<Name> name,
3325 : AccessorNameGetterCallback getter,
3326 : AccessorNameSetterCallback setter = nullptr,
3327 : MaybeLocal<Value> data = MaybeLocal<Value>(),
3328 : AccessControl settings = DEFAULT, PropertyAttribute attribute = None,
3329 : SideEffectType getter_side_effect_type = SideEffectType::kHasSideEffect,
3330 : SideEffectType setter_side_effect_type = SideEffectType::kHasSideEffect);
3331 :
3332 : void SetAccessorProperty(Local<Name> name, Local<Function> getter,
3333 : Local<Function> setter = Local<Function>(),
3334 : PropertyAttribute attribute = None,
3335 : AccessControl settings = DEFAULT);
3336 :
3337 : /**
3338 : * Sets a native data property like Template::SetNativeDataProperty, but
3339 : * this method sets on this object directly.
3340 : */
3341 : V8_WARN_UNUSED_RESULT Maybe<bool> SetNativeDataProperty(
3342 : Local<Context> context, Local<Name> name,
3343 : AccessorNameGetterCallback getter,
3344 : AccessorNameSetterCallback setter = nullptr,
3345 : Local<Value> data = Local<Value>(), PropertyAttribute attributes = None,
3346 : SideEffectType getter_side_effect_type = SideEffectType::kHasSideEffect,
3347 : SideEffectType setter_side_effect_type = SideEffectType::kHasSideEffect);
3348 :
3349 : /**
3350 : * Attempts to create a property with the given name which behaves like a data
3351 : * property, except that the provided getter is invoked (and provided with the
3352 : * data value) to supply its value the first time it is read. After the
3353 : * property is accessed once, it is replaced with an ordinary data property.
3354 : *
3355 : * Analogous to Template::SetLazyDataProperty.
3356 : */
3357 : V8_WARN_UNUSED_RESULT Maybe<bool> SetLazyDataProperty(
3358 : Local<Context> context, Local<Name> name,
3359 : AccessorNameGetterCallback getter, Local<Value> data = Local<Value>(),
3360 : PropertyAttribute attributes = None,
3361 : SideEffectType getter_side_effect_type = SideEffectType::kHasSideEffect,
3362 : SideEffectType setter_side_effect_type = SideEffectType::kHasSideEffect);
3363 :
3364 : /**
3365 : * Functionality for private properties.
3366 : * This is an experimental feature, use at your own risk.
3367 : * Note: Private properties are not inherited. Do not rely on this, since it
3368 : * may change.
3369 : */
3370 : Maybe<bool> HasPrivate(Local<Context> context, Local<Private> key);
3371 : Maybe<bool> SetPrivate(Local<Context> context, Local<Private> key,
3372 : Local<Value> value);
3373 : Maybe<bool> DeletePrivate(Local<Context> context, Local<Private> key);
3374 : MaybeLocal<Value> GetPrivate(Local<Context> context, Local<Private> key);
3375 :
3376 : /**
3377 : * Returns an array containing the names of the enumerable properties
3378 : * of this object, including properties from prototype objects. The
3379 : * array returned by this method contains the same values as would
3380 : * be enumerated by a for-in statement over this object.
3381 : */
3382 : V8_DEPRECATED("Use maybe version", Local<Array> GetPropertyNames());
3383 : V8_WARN_UNUSED_RESULT MaybeLocal<Array> GetPropertyNames(
3384 : Local<Context> context);
3385 : V8_WARN_UNUSED_RESULT MaybeLocal<Array> GetPropertyNames(
3386 : Local<Context> context, KeyCollectionMode mode,
3387 : PropertyFilter property_filter, IndexFilter index_filter,
3388 : KeyConversionMode key_conversion = KeyConversionMode::kKeepNumbers);
3389 :
3390 : /**
3391 : * This function has the same functionality as GetPropertyNames but
3392 : * the returned array doesn't contain the names of properties from
3393 : * prototype objects.
3394 : */
3395 : V8_DEPRECATED("Use maybe version", Local<Array> GetOwnPropertyNames());
3396 : V8_WARN_UNUSED_RESULT MaybeLocal<Array> GetOwnPropertyNames(
3397 : Local<Context> context);
3398 :
3399 : /**
3400 : * Returns an array containing the names of the filtered properties
3401 : * of this object, including properties from prototype objects. The
3402 : * array returned by this method contains the same values as would
3403 : * be enumerated by a for-in statement over this object.
3404 : */
3405 : V8_WARN_UNUSED_RESULT MaybeLocal<Array> GetOwnPropertyNames(
3406 : Local<Context> context, PropertyFilter filter,
3407 : KeyConversionMode key_conversion = KeyConversionMode::kKeepNumbers);
3408 :
3409 : /**
3410 : * Get the prototype object. This does not skip objects marked to
3411 : * be skipped by __proto__ and it does not consult the security
3412 : * handler.
3413 : */
3414 : Local<Value> GetPrototype();
3415 :
3416 : /**
3417 : * Set the prototype object. This does not skip objects marked to
3418 : * be skipped by __proto__ and it does not consult the security
3419 : * handler.
3420 : */
3421 : V8_WARN_UNUSED_RESULT Maybe<bool> SetPrototype(Local<Context> context,
3422 : Local<Value> prototype);
3423 :
3424 : /**
3425 : * Finds an instance of the given function template in the prototype
3426 : * chain.
3427 : */
3428 : Local<Object> FindInstanceInPrototypeChain(Local<FunctionTemplate> tmpl);
3429 :
3430 : /**
3431 : * Call builtin Object.prototype.toString on this object.
3432 : * This is different from Value::ToString() that may call
3433 : * user-defined toString function. This one does not.
3434 : */
3435 : V8_WARN_UNUSED_RESULT MaybeLocal<String> ObjectProtoToString(
3436 : Local<Context> context);
3437 :
3438 : /**
3439 : * Returns the name of the function invoked as a constructor for this object.
3440 : */
3441 : Local<String> GetConstructorName();
3442 :
3443 : /**
3444 : * Sets the integrity level of the object.
3445 : */
3446 : Maybe<bool> SetIntegrityLevel(Local<Context> context, IntegrityLevel level);
3447 :
3448 : /** Gets the number of internal fields for this Object. */
3449 : int InternalFieldCount();
3450 :
3451 : /** Same as above, but works for Persistents */
3452 : V8_INLINE static int InternalFieldCount(
3453 : const PersistentBase<Object>& object) {
3454 6 : return object.val_->InternalFieldCount();
3455 : }
3456 :
3457 : /** Gets the value from an internal field. */
3458 : V8_INLINE Local<Value> GetInternalField(int index);
3459 :
3460 : /** Sets the value in an internal field. */
3461 : void SetInternalField(int index, Local<Value> value);
3462 :
3463 : /**
3464 : * Gets a 2-byte-aligned native pointer from an internal field. This field
3465 : * must have been set by SetAlignedPointerInInternalField, everything else
3466 : * leads to undefined behavior.
3467 : */
3468 : V8_INLINE void* GetAlignedPointerFromInternalField(int index);
3469 :
3470 : /** Same as above, but works for Persistents */
3471 : V8_INLINE static void* GetAlignedPointerFromInternalField(
3472 : const PersistentBase<Object>& object, int index) {
3473 5 : return object.val_->GetAlignedPointerFromInternalField(index);
3474 : }
3475 :
3476 : /**
3477 : * Sets a 2-byte-aligned native pointer in an internal field. To retrieve such
3478 : * a field, GetAlignedPointerFromInternalField must be used, everything else
3479 : * leads to undefined behavior.
3480 : */
3481 : void SetAlignedPointerInInternalField(int index, void* value);
3482 : void SetAlignedPointerInInternalFields(int argc, int indices[],
3483 : void* values[]);
3484 :
3485 : /**
3486 : * HasOwnProperty() is like JavaScript's Object.prototype.hasOwnProperty().
3487 : *
3488 : * See also v8::Object::Has() and v8::Object::HasRealNamedProperty().
3489 : */
3490 : V8_WARN_UNUSED_RESULT Maybe<bool> HasOwnProperty(Local<Context> context,
3491 : Local<Name> key);
3492 : V8_WARN_UNUSED_RESULT Maybe<bool> HasOwnProperty(Local<Context> context,
3493 : uint32_t index);
3494 : V8_DEPRECATED("Use maybe version",
3495 : bool HasRealNamedProperty(Local<String> key));
3496 : /**
3497 : * Use HasRealNamedProperty() if you want to check if an object has an own
3498 : * property without causing side effects, i.e., without calling interceptors.
3499 : *
3500 : * This function is similar to v8::Object::HasOwnProperty(), but it does not
3501 : * call interceptors.
3502 : *
3503 : * \note Consider using non-masking interceptors, i.e., the interceptors are
3504 : * not called if the receiver has the real named property. See
3505 : * `v8::PropertyHandlerFlags::kNonMasking`.
3506 : *
3507 : * See also v8::Object::Has().
3508 : */
3509 : V8_WARN_UNUSED_RESULT Maybe<bool> HasRealNamedProperty(Local<Context> context,
3510 : Local<Name> key);
3511 : V8_DEPRECATED("Use maybe version",
3512 : bool HasRealIndexedProperty(uint32_t index));
3513 : V8_WARN_UNUSED_RESULT Maybe<bool> HasRealIndexedProperty(
3514 : Local<Context> context, uint32_t index);
3515 : V8_DEPRECATED("Use maybe version",
3516 : bool HasRealNamedCallbackProperty(Local<String> key));
3517 : V8_WARN_UNUSED_RESULT Maybe<bool> HasRealNamedCallbackProperty(
3518 : Local<Context> context, Local<Name> key);
3519 :
3520 : /**
3521 : * If result.IsEmpty() no real property was located in the prototype chain.
3522 : * This means interceptors in the prototype chain are not called.
3523 : */
3524 : V8_WARN_UNUSED_RESULT MaybeLocal<Value> GetRealNamedPropertyInPrototypeChain(
3525 : Local<Context> context, Local<Name> key);
3526 :
3527 : /**
3528 : * Gets the property attributes of a real property in the prototype chain,
3529 : * which can be None or any combination of ReadOnly, DontEnum and DontDelete.
3530 : * Interceptors in the prototype chain are not called.
3531 : */
3532 : V8_WARN_UNUSED_RESULT Maybe<PropertyAttribute>
3533 : GetRealNamedPropertyAttributesInPrototypeChain(Local<Context> context,
3534 : Local<Name> key);
3535 :
3536 : /**
3537 : * If result.IsEmpty() no real property was located on the object or
3538 : * in the prototype chain.
3539 : * This means interceptors in the prototype chain are not called.
3540 : */
3541 : V8_WARN_UNUSED_RESULT MaybeLocal<Value> GetRealNamedProperty(
3542 : Local<Context> context, Local<Name> key);
3543 :
3544 : /**
3545 : * Gets the property attributes of a real property which can be
3546 : * None or any combination of ReadOnly, DontEnum and DontDelete.
3547 : * Interceptors in the prototype chain are not called.
3548 : */
3549 : V8_WARN_UNUSED_RESULT Maybe<PropertyAttribute> GetRealNamedPropertyAttributes(
3550 : Local<Context> context, Local<Name> key);
3551 :
3552 : /** Tests for a named lookup interceptor.*/
3553 : bool HasNamedLookupInterceptor();
3554 :
3555 : /** Tests for an index lookup interceptor.*/
3556 : bool HasIndexedLookupInterceptor();
3557 :
3558 : /**
3559 : * Returns the identity hash for this object. The current implementation
3560 : * uses a hidden property on the object to store the identity hash.
3561 : *
3562 : * The return value will never be 0. Also, it is not guaranteed to be
3563 : * unique.
3564 : */
3565 : int GetIdentityHash();
3566 :
3567 : /**
3568 : * Clone this object with a fast but shallow copy. Values will point
3569 : * to the same values as the original object.
3570 : */
3571 : // TODO(dcarney): take an isolate and optionally bail out?
3572 : Local<Object> Clone();
3573 :
3574 : /**
3575 : * Returns the context in which the object was created.
3576 : */
3577 : Local<Context> CreationContext();
3578 :
3579 : /** Same as above, but works for Persistents */
3580 : V8_INLINE static Local<Context> CreationContext(
3581 : const PersistentBase<Object>& object) {
3582 : return object.val_->CreationContext();
3583 : }
3584 :
3585 : /**
3586 : * Checks whether a callback is set by the
3587 : * ObjectTemplate::SetCallAsFunctionHandler method.
3588 : * When an Object is callable this method returns true.
3589 : */
3590 : bool IsCallable();
3591 :
3592 : /**
3593 : * True if this object is a constructor.
3594 : */
3595 : bool IsConstructor();
3596 :
3597 : /**
3598 : * Call an Object as a function if a callback is set by the
3599 : * ObjectTemplate::SetCallAsFunctionHandler method.
3600 : */
3601 : V8_WARN_UNUSED_RESULT MaybeLocal<Value> CallAsFunction(Local<Context> context,
3602 : Local<Value> recv,
3603 : int argc,
3604 : Local<Value> argv[]);
3605 :
3606 : /**
3607 : * Call an Object as a constructor if a callback is set by the
3608 : * ObjectTemplate::SetCallAsFunctionHandler method.
3609 : * Note: This method behaves like the Function::NewInstance method.
3610 : */
3611 : V8_WARN_UNUSED_RESULT MaybeLocal<Value> CallAsConstructor(
3612 : Local<Context> context, int argc, Local<Value> argv[]);
3613 :
3614 : /**
3615 : * Return the isolate to which the Object belongs to.
3616 : */
3617 : Isolate* GetIsolate();
3618 :
3619 : /**
3620 : * If this object is a Set, Map, WeakSet or WeakMap, this returns a
3621 : * representation of the elements of this object as an array.
3622 : * If this object is a SetIterator or MapIterator, this returns all
3623 : * elements of the underlying collection, starting at the iterator's current
3624 : * position.
3625 : * For other types, this will return an empty MaybeLocal<Array> (without
3626 : * scheduling an exception).
3627 : */
3628 : MaybeLocal<Array> PreviewEntries(bool* is_key_value);
3629 :
3630 : static Local<Object> New(Isolate* isolate);
3631 :
3632 : /**
3633 : * Creates a JavaScript object with the given properties, and
3634 : * a the given prototype_or_null (which can be any JavaScript
3635 : * value, and if it's null, the newly created object won't have
3636 : * a prototype at all). This is similar to Object.create().
3637 : * All properties will be created as enumerable, configurable
3638 : * and writable properties.
3639 : */
3640 : static Local<Object> New(Isolate* isolate, Local<Value> prototype_or_null,
3641 : Local<Name>* names, Local<Value>* values,
3642 : size_t length);
3643 :
3644 : V8_INLINE static Object* Cast(Value* obj);
3645 :
3646 : private:
3647 : Object();
3648 : static void CheckCast(Value* obj);
3649 : Local<Value> SlowGetInternalField(int index);
3650 : void* SlowGetAlignedPointerFromInternalField(int index);
3651 : };
3652 :
3653 :
3654 : /**
3655 : * An instance of the built-in array constructor (ECMA-262, 15.4.2).
3656 : */
3657 : class V8_EXPORT Array : public Object {
3658 : public:
3659 : uint32_t Length() const;
3660 :
3661 : /**
3662 : * Creates a JavaScript array with the given length. If the length
3663 : * is negative the returned array will have length 0.
3664 : */
3665 : static Local<Array> New(Isolate* isolate, int length = 0);
3666 :
3667 : /**
3668 : * Creates a JavaScript array out of a Local<Value> array in C++
3669 : * with a known length.
3670 : */
3671 : static Local<Array> New(Isolate* isolate, Local<Value>* elements,
3672 : size_t length);
3673 : V8_INLINE static Array* Cast(Value* obj);
3674 : private:
3675 : Array();
3676 : static void CheckCast(Value* obj);
3677 : };
3678 :
3679 :
3680 : /**
3681 : * An instance of the built-in Map constructor (ECMA-262, 6th Edition, 23.1.1).
3682 : */
3683 : class V8_EXPORT Map : public Object {
3684 : public:
3685 : size_t Size() const;
3686 : void Clear();
3687 : V8_WARN_UNUSED_RESULT MaybeLocal<Value> Get(Local<Context> context,
3688 : Local<Value> key);
3689 : V8_WARN_UNUSED_RESULT MaybeLocal<Map> Set(Local<Context> context,
3690 : Local<Value> key,
3691 : Local<Value> value);
3692 : V8_WARN_UNUSED_RESULT Maybe<bool> Has(Local<Context> context,
3693 : Local<Value> key);
3694 : V8_WARN_UNUSED_RESULT Maybe<bool> Delete(Local<Context> context,
3695 : Local<Value> key);
3696 :
3697 : /**
3698 : * Returns an array of length Size() * 2, where index N is the Nth key and
3699 : * index N + 1 is the Nth value.
3700 : */
3701 : Local<Array> AsArray() const;
3702 :
3703 : /**
3704 : * Creates a new empty Map.
3705 : */
3706 : static Local<Map> New(Isolate* isolate);
3707 :
3708 : V8_INLINE static Map* Cast(Value* obj);
3709 :
3710 : private:
3711 : Map();
3712 : static void CheckCast(Value* obj);
3713 : };
3714 :
3715 :
3716 : /**
3717 : * An instance of the built-in Set constructor (ECMA-262, 6th Edition, 23.2.1).
3718 : */
3719 : class V8_EXPORT Set : public Object {
3720 : public:
3721 : size_t Size() const;
3722 : void Clear();
3723 : V8_WARN_UNUSED_RESULT MaybeLocal<Set> Add(Local<Context> context,
3724 : Local<Value> key);
3725 : V8_WARN_UNUSED_RESULT Maybe<bool> Has(Local<Context> context,
3726 : Local<Value> key);
3727 : V8_WARN_UNUSED_RESULT Maybe<bool> Delete(Local<Context> context,
3728 : Local<Value> key);
3729 :
3730 : /**
3731 : * Returns an array of the keys in this Set.
3732 : */
3733 : Local<Array> AsArray() const;
3734 :
3735 : /**
3736 : * Creates a new empty Set.
3737 : */
3738 : static Local<Set> New(Isolate* isolate);
3739 :
3740 : V8_INLINE static Set* Cast(Value* obj);
3741 :
3742 : private:
3743 : Set();
3744 : static void CheckCast(Value* obj);
3745 : };
3746 :
3747 :
3748 : template<typename T>
3749 : class ReturnValue {
3750 : public:
3751 : template <class S> V8_INLINE ReturnValue(const ReturnValue<S>& that)
3752 : : value_(that.value_) {
3753 : TYPE_CHECK(T, S);
3754 : }
3755 : // Local setters
3756 : template <typename S>
3757 : V8_INLINE V8_DEPRECATED("Use Global<> instead",
3758 : void Set(const Persistent<S>& handle));
3759 : template <typename S>
3760 : V8_INLINE void Set(const Global<S>& handle);
3761 : template <typename S>
3762 : V8_INLINE void Set(const Local<S> handle);
3763 : // Fast primitive setters
3764 : V8_INLINE void Set(bool value);
3765 : V8_INLINE void Set(double i);
3766 : V8_INLINE void Set(int32_t i);
3767 : V8_INLINE void Set(uint32_t i);
3768 : // Fast JS primitive setters
3769 : V8_INLINE void SetNull();
3770 : V8_INLINE void SetUndefined();
3771 : V8_INLINE void SetEmptyString();
3772 : // Convenience getter for Isolate
3773 : V8_INLINE Isolate* GetIsolate() const;
3774 :
3775 : // Pointer setter: Uncompilable to prevent inadvertent misuse.
3776 : template <typename S>
3777 : V8_INLINE void Set(S* whatever);
3778 :
3779 : // Getter. Creates a new Local<> so it comes with a certain performance
3780 : // hit. If the ReturnValue was not yet set, this will return the undefined
3781 : // value.
3782 : V8_INLINE Local<Value> Get() const;
3783 :
3784 : private:
3785 : template<class F> friend class ReturnValue;
3786 : template<class F> friend class FunctionCallbackInfo;
3787 : template<class F> friend class PropertyCallbackInfo;
3788 : template <class F, class G, class H>
3789 : friend class PersistentValueMapBase;
3790 : V8_INLINE void SetInternal(internal::Address value) { *value_ = value; }
3791 : V8_INLINE internal::Address GetDefaultValue();
3792 : V8_INLINE explicit ReturnValue(internal::Address* slot);
3793 : internal::Address* value_;
3794 : };
3795 :
3796 :
3797 : /**
3798 : * The argument information given to function call callbacks. This
3799 : * class provides access to information about the context of the call,
3800 : * including the receiver, the number and values of arguments, and
3801 : * the holder of the function.
3802 : */
3803 : template<typename T>
3804 : class FunctionCallbackInfo {
3805 : public:
3806 : /** The number of available arguments. */
3807 : V8_INLINE int Length() const;
3808 : /** Accessor for the available arguments. */
3809 : V8_INLINE Local<Value> operator[](int i) const;
3810 : /** Returns the receiver. This corresponds to the "this" value. */
3811 : V8_INLINE Local<Object> This() const;
3812 : /**
3813 : * If the callback was created without a Signature, this is the same
3814 : * value as This(). If there is a signature, and the signature didn't match
3815 : * This() but one of its hidden prototypes, this will be the respective
3816 : * hidden prototype.
3817 : *
3818 : * Note that this is not the prototype of This() on which the accessor
3819 : * referencing this callback was found (which in V8 internally is often
3820 : * referred to as holder [sic]).
3821 : */
3822 : V8_INLINE Local<Object> Holder() const;
3823 : /** For construct calls, this returns the "new.target" value. */
3824 : V8_INLINE Local<Value> NewTarget() const;
3825 : /** Indicates whether this is a regular call or a construct call. */
3826 : V8_INLINE bool IsConstructCall() const;
3827 : /** The data argument specified when creating the callback. */
3828 : V8_INLINE Local<Value> Data() const;
3829 : /** The current Isolate. */
3830 : V8_INLINE Isolate* GetIsolate() const;
3831 : /** The ReturnValue for the call. */
3832 : V8_INLINE ReturnValue<T> GetReturnValue() const;
3833 : // This shouldn't be public, but the arm compiler needs it.
3834 : static const int kArgsLength = 6;
3835 :
3836 : protected:
3837 : friend class internal::FunctionCallbackArguments;
3838 : friend class internal::CustomArguments<FunctionCallbackInfo>;
3839 : friend class debug::ConsoleCallArguments;
3840 : static const int kHolderIndex = 0;
3841 : static const int kIsolateIndex = 1;
3842 : static const int kReturnValueDefaultValueIndex = 2;
3843 : static const int kReturnValueIndex = 3;
3844 : static const int kDataIndex = 4;
3845 : static const int kNewTargetIndex = 5;
3846 :
3847 : V8_INLINE FunctionCallbackInfo(internal::Address* implicit_args,
3848 : internal::Address* values, int length);
3849 : internal::Address* implicit_args_;
3850 : internal::Address* values_;
3851 : int length_;
3852 : };
3853 :
3854 :
3855 : /**
3856 : * The information passed to a property callback about the context
3857 : * of the property access.
3858 : */
3859 : template<typename T>
3860 : class PropertyCallbackInfo {
3861 : public:
3862 : /**
3863 : * \return The isolate of the property access.
3864 : */
3865 : V8_INLINE Isolate* GetIsolate() const;
3866 :
3867 : /**
3868 : * \return The data set in the configuration, i.e., in
3869 : * `NamedPropertyHandlerConfiguration` or
3870 : * `IndexedPropertyHandlerConfiguration.`
3871 : */
3872 : V8_INLINE Local<Value> Data() const;
3873 :
3874 : /**
3875 : * \return The receiver. In many cases, this is the object on which the
3876 : * property access was intercepted. When using
3877 : * `Reflect.get`, `Function.prototype.call`, or similar functions, it is the
3878 : * object passed in as receiver or thisArg.
3879 : *
3880 : * \code
3881 : * void GetterCallback(Local<Name> name,
3882 : * const v8::PropertyCallbackInfo<v8::Value>& info) {
3883 : * auto context = info.GetIsolate()->GetCurrentContext();
3884 : *
3885 : * v8::Local<v8::Value> a_this =
3886 : * info.This()
3887 : * ->GetRealNamedProperty(context, v8_str("a"))
3888 : * .ToLocalChecked();
3889 : * v8::Local<v8::Value> a_holder =
3890 : * info.Holder()
3891 : * ->GetRealNamedProperty(context, v8_str("a"))
3892 : * .ToLocalChecked();
3893 : *
3894 : * CHECK(v8_str("r")->Equals(context, a_this).FromJust());
3895 : * CHECK(v8_str("obj")->Equals(context, a_holder).FromJust());
3896 : *
3897 : * info.GetReturnValue().Set(name);
3898 : * }
3899 : *
3900 : * v8::Local<v8::FunctionTemplate> templ =
3901 : * v8::FunctionTemplate::New(isolate);
3902 : * templ->InstanceTemplate()->SetHandler(
3903 : * v8::NamedPropertyHandlerConfiguration(GetterCallback));
3904 : * LocalContext env;
3905 : * env->Global()
3906 : * ->Set(env.local(), v8_str("obj"), templ->GetFunction(env.local())
3907 : * .ToLocalChecked()
3908 : * ->NewInstance(env.local())
3909 : * .ToLocalChecked())
3910 : * .FromJust();
3911 : *
3912 : * CompileRun("obj.a = 'obj'; var r = {a: 'r'}; Reflect.get(obj, 'x', r)");
3913 : * \endcode
3914 : */
3915 : V8_INLINE Local<Object> This() const;
3916 :
3917 : /**
3918 : * \return The object in the prototype chain of the receiver that has the
3919 : * interceptor. Suppose you have `x` and its prototype is `y`, and `y`
3920 : * has an interceptor. Then `info.This()` is `x` and `info.Holder()` is `y`.
3921 : * The Holder() could be a hidden object (the global object, rather
3922 : * than the global proxy).
3923 : *
3924 : * \note For security reasons, do not pass the object back into the runtime.
3925 : */
3926 : V8_INLINE Local<Object> Holder() const;
3927 :
3928 : /**
3929 : * \return The return value of the callback.
3930 : * Can be changed by calling Set().
3931 : * \code
3932 : * info.GetReturnValue().Set(...)
3933 : * \endcode
3934 : *
3935 : */
3936 : V8_INLINE ReturnValue<T> GetReturnValue() const;
3937 :
3938 : /**
3939 : * \return True if the intercepted function should throw if an error occurs.
3940 : * Usually, `true` corresponds to `'use strict'`.
3941 : *
3942 : * \note Always `false` when intercepting `Reflect.set()`
3943 : * independent of the language mode.
3944 : */
3945 : V8_INLINE bool ShouldThrowOnError() const;
3946 :
3947 : // This shouldn't be public, but the arm compiler needs it.
3948 : static const int kArgsLength = 7;
3949 :
3950 : protected:
3951 : friend class MacroAssembler;
3952 : friend class internal::PropertyCallbackArguments;
3953 : friend class internal::CustomArguments<PropertyCallbackInfo>;
3954 : static const int kShouldThrowOnErrorIndex = 0;
3955 : static const int kHolderIndex = 1;
3956 : static const int kIsolateIndex = 2;
3957 : static const int kReturnValueDefaultValueIndex = 3;
3958 : static const int kReturnValueIndex = 4;
3959 : static const int kDataIndex = 5;
3960 : static const int kThisIndex = 6;
3961 :
3962 2619814 : V8_INLINE PropertyCallbackInfo(internal::Address* args) : args_(args) {}
3963 : internal::Address* args_;
3964 : };
3965 :
3966 :
3967 : typedef void (*FunctionCallback)(const FunctionCallbackInfo<Value>& info);
3968 :
3969 : enum class ConstructorBehavior { kThrow, kAllow };
3970 :
3971 : /**
3972 : * A JavaScript function object (ECMA-262, 15.3).
3973 : */
3974 : class V8_EXPORT Function : public Object {
3975 : public:
3976 : /**
3977 : * Create a function in the current execution context
3978 : * for a given FunctionCallback.
3979 : */
3980 : static MaybeLocal<Function> New(
3981 : Local<Context> context, FunctionCallback callback,
3982 : Local<Value> data = Local<Value>(), int length = 0,
3983 : ConstructorBehavior behavior = ConstructorBehavior::kAllow,
3984 : SideEffectType side_effect_type = SideEffectType::kHasSideEffect);
3985 : static V8_DEPRECATED("Use maybe version",
3986 : Local<Function> New(Isolate* isolate,
3987 : FunctionCallback callback,
3988 : Local<Value> data = Local<Value>(),
3989 : int length = 0));
3990 :
3991 : V8_WARN_UNUSED_RESULT MaybeLocal<Object> NewInstance(
3992 : Local<Context> context, int argc, Local<Value> argv[]) const;
3993 :
3994 9 : V8_WARN_UNUSED_RESULT MaybeLocal<Object> NewInstance(
3995 : Local<Context> context) const {
3996 877 : return NewInstance(context, 0, nullptr);
3997 : }
3998 :
3999 : /**
4000 : * When side effect checks are enabled, passing kHasNoSideEffect allows the
4001 : * constructor to be invoked without throwing. Calls made within the
4002 : * constructor are still checked.
4003 : */
4004 : V8_WARN_UNUSED_RESULT MaybeLocal<Object> NewInstanceWithSideEffectType(
4005 : Local<Context> context, int argc, Local<Value> argv[],
4006 : SideEffectType side_effect_type = SideEffectType::kHasSideEffect) const;
4007 :
4008 : V8_DEPRECATED("Use maybe version",
4009 : Local<Value> Call(Local<Value> recv, int argc,
4010 : Local<Value> argv[]));
4011 : V8_WARN_UNUSED_RESULT MaybeLocal<Value> Call(Local<Context> context,
4012 : Local<Value> recv, int argc,
4013 : Local<Value> argv[]);
4014 :
4015 : void SetName(Local<String> name);
4016 : Local<Value> GetName() const;
4017 :
4018 : /**
4019 : * Name inferred from variable or property assignment of this function.
4020 : * Used to facilitate debugging and profiling of JavaScript code written
4021 : * in an OO style, where many functions are anonymous but are assigned
4022 : * to object properties.
4023 : */
4024 : Local<Value> GetInferredName() const;
4025 :
4026 : /**
4027 : * displayName if it is set, otherwise name if it is configured, otherwise
4028 : * function name, otherwise inferred name.
4029 : */
4030 : Local<Value> GetDebugName() const;
4031 :
4032 : /**
4033 : * User-defined name assigned to the "displayName" property of this function.
4034 : * Used to facilitate debugging and profiling of JavaScript code.
4035 : */
4036 : Local<Value> GetDisplayName() const;
4037 :
4038 : /**
4039 : * Returns zero based line number of function body and
4040 : * kLineOffsetNotFound if no information available.
4041 : */
4042 : int GetScriptLineNumber() const;
4043 : /**
4044 : * Returns zero based column number of function body and
4045 : * kLineOffsetNotFound if no information available.
4046 : */
4047 : int GetScriptColumnNumber() const;
4048 :
4049 : /**
4050 : * Returns scriptId.
4051 : */
4052 : int ScriptId() const;
4053 :
4054 : /**
4055 : * Returns the original function if this function is bound, else returns
4056 : * v8::Undefined.
4057 : */
4058 : Local<Value> GetBoundFunction() const;
4059 :
4060 : ScriptOrigin GetScriptOrigin() const;
4061 : V8_INLINE static Function* Cast(Value* obj);
4062 : static const int kLineOffsetNotFound;
4063 :
4064 : private:
4065 : Function();
4066 : static void CheckCast(Value* obj);
4067 : };
4068 :
4069 : #ifndef V8_PROMISE_INTERNAL_FIELD_COUNT
4070 : // The number of required internal fields can be defined by embedder.
4071 : #define V8_PROMISE_INTERNAL_FIELD_COUNT 0
4072 : #endif
4073 :
4074 : /**
4075 : * An instance of the built-in Promise constructor (ES6 draft).
4076 : */
4077 : class V8_EXPORT Promise : public Object {
4078 : public:
4079 : /**
4080 : * State of the promise. Each value corresponds to one of the possible values
4081 : * of the [[PromiseState]] field.
4082 : */
4083 : enum PromiseState { kPending, kFulfilled, kRejected };
4084 :
4085 : class V8_EXPORT Resolver : public Object {
4086 : public:
4087 : /**
4088 : * Create a new resolver, along with an associated promise in pending state.
4089 : */
4090 : static V8_WARN_UNUSED_RESULT MaybeLocal<Resolver> New(
4091 : Local<Context> context);
4092 :
4093 : /**
4094 : * Extract the associated promise.
4095 : */
4096 : Local<Promise> GetPromise();
4097 :
4098 : /**
4099 : * Resolve/reject the associated promise with a given value.
4100 : * Ignored if the promise is no longer pending.
4101 : */
4102 : V8_WARN_UNUSED_RESULT Maybe<bool> Resolve(Local<Context> context,
4103 : Local<Value> value);
4104 :
4105 : V8_WARN_UNUSED_RESULT Maybe<bool> Reject(Local<Context> context,
4106 : Local<Value> value);
4107 :
4108 : V8_INLINE static Resolver* Cast(Value* obj);
4109 :
4110 : private:
4111 : Resolver();
4112 : static void CheckCast(Value* obj);
4113 : };
4114 :
4115 : /**
4116 : * Register a resolution/rejection handler with a promise.
4117 : * The handler is given the respective resolution/rejection value as
4118 : * an argument. If the promise is already resolved/rejected, the handler is
4119 : * invoked at the end of turn.
4120 : */
4121 : V8_WARN_UNUSED_RESULT MaybeLocal<Promise> Catch(Local<Context> context,
4122 : Local<Function> handler);
4123 :
4124 : V8_WARN_UNUSED_RESULT MaybeLocal<Promise> Then(Local<Context> context,
4125 : Local<Function> handler);
4126 :
4127 : V8_WARN_UNUSED_RESULT MaybeLocal<Promise> Then(Local<Context> context,
4128 : Local<Function> on_fulfilled,
4129 : Local<Function> on_rejected);
4130 :
4131 : /**
4132 : * Returns true if the promise has at least one derived promise, and
4133 : * therefore resolve/reject handlers (including default handler).
4134 : */
4135 : bool HasHandler();
4136 :
4137 : /**
4138 : * Returns the content of the [[PromiseResult]] field. The Promise must not
4139 : * be pending.
4140 : */
4141 : Local<Value> Result();
4142 :
4143 : /**
4144 : * Returns the value of the [[PromiseState]] field.
4145 : */
4146 : PromiseState State();
4147 :
4148 : /**
4149 : * Marks this promise as handled to avoid reporting unhandled rejections.
4150 : */
4151 : void MarkAsHandled();
4152 :
4153 : V8_INLINE static Promise* Cast(Value* obj);
4154 :
4155 : static const int kEmbedderFieldCount = V8_PROMISE_INTERNAL_FIELD_COUNT;
4156 :
4157 : private:
4158 : Promise();
4159 : static void CheckCast(Value* obj);
4160 : };
4161 :
4162 : /**
4163 : * An instance of a Property Descriptor, see Ecma-262 6.2.4.
4164 : *
4165 : * Properties in a descriptor are present or absent. If you do not set
4166 : * `enumerable`, `configurable`, and `writable`, they are absent. If `value`,
4167 : * `get`, or `set` are absent, but you must specify them in the constructor, use
4168 : * empty handles.
4169 : *
4170 : * Accessors `get` and `set` must be callable or undefined if they are present.
4171 : *
4172 : * \note Only query properties if they are present, i.e., call `x()` only if
4173 : * `has_x()` returns true.
4174 : *
4175 : * \code
4176 : * // var desc = {writable: false}
4177 : * v8::PropertyDescriptor d(Local<Value>()), false);
4178 : * d.value(); // error, value not set
4179 : * if (d.has_writable()) {
4180 : * d.writable(); // false
4181 : * }
4182 : *
4183 : * // var desc = {value: undefined}
4184 : * v8::PropertyDescriptor d(v8::Undefined(isolate));
4185 : *
4186 : * // var desc = {get: undefined}
4187 : * v8::PropertyDescriptor d(v8::Undefined(isolate), Local<Value>()));
4188 : * \endcode
4189 : */
4190 : class V8_EXPORT PropertyDescriptor {
4191 : public:
4192 : // GenericDescriptor
4193 : PropertyDescriptor();
4194 :
4195 : // DataDescriptor (implicit / DEPRECATED)
4196 : // Templatized such that the explicit constructor is chosen first.
4197 : // TODO(clemensh): Remove after 7.3 branch.
4198 : template <std::nullptr_t = nullptr>
4199 : V8_DEPRECATED(
4200 : "Use explicit constructor",
4201 : PropertyDescriptor(Local<Value> value)); // NOLINT(runtime/explicit)
4202 :
4203 : // DataDescriptor
4204 : explicit PropertyDescriptor(Local<Value> value);
4205 :
4206 : // DataDescriptor with writable property
4207 : PropertyDescriptor(Local<Value> value, bool writable);
4208 :
4209 : // AccessorDescriptor
4210 : PropertyDescriptor(Local<Value> get, Local<Value> set);
4211 :
4212 : ~PropertyDescriptor();
4213 :
4214 : Local<Value> value() const;
4215 : bool has_value() const;
4216 :
4217 : Local<Value> get() const;
4218 : bool has_get() const;
4219 : Local<Value> set() const;
4220 : bool has_set() const;
4221 :
4222 : void set_enumerable(bool enumerable);
4223 : bool enumerable() const;
4224 : bool has_enumerable() const;
4225 :
4226 : void set_configurable(bool configurable);
4227 : bool configurable() const;
4228 : bool has_configurable() const;
4229 :
4230 : bool writable() const;
4231 : bool has_writable() const;
4232 :
4233 : struct PrivateData;
4234 126 : PrivateData* get_private() const { return private_; }
4235 :
4236 : PropertyDescriptor(const PropertyDescriptor&) = delete;
4237 : void operator=(const PropertyDescriptor&) = delete;
4238 :
4239 : private:
4240 : PrivateData* private_;
4241 : };
4242 :
4243 : // TODO(clemensh): Remove after 7.3 branch.
4244 : template <std::nullptr_t>
4245 : PropertyDescriptor::PropertyDescriptor(Local<Value> value)
4246 : : PropertyDescriptor(value) {}
4247 :
4248 : /**
4249 : * An instance of the built-in Proxy constructor (ECMA-262, 6th Edition,
4250 : * 26.2.1).
4251 : */
4252 : class V8_EXPORT Proxy : public Object {
4253 : public:
4254 : Local<Value> GetTarget();
4255 : Local<Value> GetHandler();
4256 : bool IsRevoked();
4257 : void Revoke();
4258 :
4259 : /**
4260 : * Creates a new Proxy for the target object.
4261 : */
4262 : static MaybeLocal<Proxy> New(Local<Context> context,
4263 : Local<Object> local_target,
4264 : Local<Object> local_handler);
4265 :
4266 : V8_INLINE static Proxy* Cast(Value* obj);
4267 :
4268 : private:
4269 : Proxy();
4270 : static void CheckCast(Value* obj);
4271 : };
4272 :
4273 : /**
4274 : * Points to an unowned continous buffer holding a known number of elements.
4275 : *
4276 : * This is similar to std::span (under consideration for C++20), but does not
4277 : * require advanced C++ support. In the (far) future, this may be replaced with
4278 : * or aliased to std::span.
4279 : *
4280 : * To facilitate future migration, this class exposes a subset of the interface
4281 : * implemented by std::span.
4282 : */
4283 : template <typename T>
4284 : class V8_EXPORT MemorySpan {
4285 : public:
4286 : /** The default constructor creates an empty span. */
4287 : constexpr MemorySpan() = default;
4288 :
4289 47 : constexpr MemorySpan(T* data, size_t size) : data_(data), size_(size) {}
4290 :
4291 : /** Returns a pointer to the beginning of the buffer. */
4292 : constexpr T* data() const { return data_; }
4293 : /** Returns the number of elements that the buffer holds. */
4294 : constexpr size_t size() const { return size_; }
4295 :
4296 : private:
4297 : T* data_ = nullptr;
4298 : size_t size_ = 0;
4299 : };
4300 :
4301 : /**
4302 : * An owned byte buffer with associated size.
4303 : */
4304 307 : struct OwnedBuffer {
4305 : std::unique_ptr<const uint8_t[]> buffer;
4306 : size_t size = 0;
4307 : OwnedBuffer(std::unique_ptr<const uint8_t[]> buffer, size_t size)
4308 255 : : buffer(std::move(buffer)), size(size) {}
4309 : OwnedBuffer() = default;
4310 : };
4311 :
4312 : // Wrapper around a compiled WebAssembly module, which is potentially shared by
4313 : // different WasmModuleObjects.
4314 : class V8_EXPORT CompiledWasmModule {
4315 : public:
4316 : /**
4317 : * Serialize the compiled module. The serialized data does not include the
4318 : * wire bytes.
4319 : */
4320 : OwnedBuffer Serialize();
4321 :
4322 : /**
4323 : * Get the (wasm-encoded) wire bytes that were used to compile this module.
4324 : */
4325 : MemorySpan<const uint8_t> GetWireBytesRef();
4326 :
4327 : private:
4328 : explicit CompiledWasmModule(std::shared_ptr<internal::wasm::NativeModule>);
4329 : friend class Utils;
4330 :
4331 : const std::shared_ptr<internal::wasm::NativeModule> native_module_;
4332 : };
4333 :
4334 : // An instance of WebAssembly.Module.
4335 : class V8_EXPORT WasmModuleObject : public Object {
4336 : public:
4337 : // TODO(clemensh): Remove after 7.3 branch.
4338 : V8_DEPRECATED("Use OwnedBuffer", typedef)
4339 : std::pair<std::unique_ptr<const uint8_t[]>, size_t> SerializedModule;
4340 :
4341 : /**
4342 : * A unowned reference to a byte buffer.
4343 : * TODO(clemensh): Remove after 7.3 branch.
4344 : */
4345 : V8_DEPRECATED("Use MemorySpan<const uint8_t>", struct) BufferReference {
4346 : const uint8_t* start;
4347 : size_t size;
4348 : BufferReference(const uint8_t* start, size_t size)
4349 : : start(start), size(size) {}
4350 :
4351 : // Implicit conversion to and from MemorySpan<const uint8_t>.
4352 : BufferReference(MemorySpan<const uint8_t> span) // NOLINT(runtime/explicit)
4353 : : start(span.data()), size(span.size()) {}
4354 : operator MemorySpan<const uint8_t>() const {
4355 : return MemorySpan<const uint8_t>{start, size};
4356 : }
4357 : };
4358 :
4359 : /**
4360 : * An opaque, native heap object for transferring wasm modules. It
4361 : * supports move semantics, and does not support copy semantics.
4362 : * TODO(wasm): Merge this with CompiledWasmModule once code sharing is always
4363 : * enabled.
4364 : */
4365 462 : class TransferrableModule final {
4366 : public:
4367 : TransferrableModule(TransferrableModule&& src) = default;
4368 : TransferrableModule(const TransferrableModule& src) = delete;
4369 :
4370 : TransferrableModule& operator=(TransferrableModule&& src) = default;
4371 : TransferrableModule& operator=(const TransferrableModule& src) = delete;
4372 :
4373 : private:
4374 : typedef std::shared_ptr<internal::wasm::NativeModule> SharedModule;
4375 : friend class WasmModuleObject;
4376 : explicit TransferrableModule(SharedModule shared_module)
4377 : : shared_module_(std::move(shared_module)) {}
4378 : TransferrableModule(OwnedBuffer serialized, OwnedBuffer bytes)
4379 5 : : serialized_(std::move(serialized)), wire_bytes_(std::move(bytes)) {}
4380 :
4381 : SharedModule shared_module_;
4382 : OwnedBuffer serialized_ = {nullptr, 0};
4383 : OwnedBuffer wire_bytes_ = {nullptr, 0};
4384 : };
4385 :
4386 : /**
4387 : * Get an in-memory, non-persistable, and context-independent (meaning,
4388 : * suitable for transfer to another Isolate and Context) representation
4389 : * of this wasm compiled module.
4390 : */
4391 : TransferrableModule GetTransferrableModule();
4392 :
4393 : /**
4394 : * Efficiently re-create a WasmModuleObject, without recompiling, from
4395 : * a TransferrableModule.
4396 : */
4397 : static MaybeLocal<WasmModuleObject> FromTransferrableModule(
4398 : Isolate* isolate, const TransferrableModule&);
4399 :
4400 : /**
4401 : * Get the wasm-encoded bytes that were used to compile this module.
4402 : */
4403 : V8_DEPRECATED("Use CompiledWasmModule::GetWireBytesRef()",
4404 : BufferReference GetWasmWireBytesRef());
4405 :
4406 : /**
4407 : * Get the compiled module for this module object. The compiled module can be
4408 : * shared by several module objects.
4409 : */
4410 : CompiledWasmModule GetCompiledModule();
4411 :
4412 : /**
4413 : * Serialize the compiled module. The serialized data does not include the
4414 : * uncompiled bytes.
4415 : */
4416 : V8_DEPRECATED("Use CompiledWasmModule::Serialize()",
4417 : SerializedModule Serialize());
4418 :
4419 : /**
4420 : * If possible, deserialize the module, otherwise compile it from the provided
4421 : * uncompiled bytes.
4422 : */
4423 : static MaybeLocal<WasmModuleObject> DeserializeOrCompile(
4424 : Isolate* isolate, MemorySpan<const uint8_t> serialized_module,
4425 : MemorySpan<const uint8_t> wire_bytes);
4426 : V8_INLINE static WasmModuleObject* Cast(Value* obj);
4427 :
4428 : private:
4429 : static MaybeLocal<WasmModuleObject> Deserialize(
4430 : Isolate* isolate, MemorySpan<const uint8_t> serialized_module,
4431 : MemorySpan<const uint8_t> wire_bytes);
4432 : static MaybeLocal<WasmModuleObject> Compile(Isolate* isolate,
4433 : const uint8_t* start,
4434 : size_t length);
4435 : static MemorySpan<const uint8_t> AsReference(const OwnedBuffer& buff) {
4436 10 : return {buff.buffer.get(), buff.size};
4437 : }
4438 :
4439 : WasmModuleObject();
4440 : static void CheckCast(Value* obj);
4441 : };
4442 :
4443 : V8_DEPRECATED("Use WasmModuleObject",
4444 : typedef WasmModuleObject WasmCompiledModule);
4445 :
4446 : /**
4447 : * The V8 interface for WebAssembly streaming compilation. When streaming
4448 : * compilation is initiated, V8 passes a {WasmStreaming} object to the embedder
4449 : * such that the embedder can pass the input bytes for streaming compilation to
4450 : * V8.
4451 : */
4452 0 : class V8_EXPORT WasmStreaming final {
4453 : public:
4454 : class WasmStreamingImpl;
4455 :
4456 : /**
4457 : * Client to receive streaming event notifications.
4458 : */
4459 : class Client {
4460 : public:
4461 : virtual ~Client() = default;
4462 : /**
4463 : * Passes the fully compiled module to the client. This can be used to
4464 : * implement code caching.
4465 : */
4466 : virtual void OnModuleCompiled(CompiledWasmModule compiled_module) = 0;
4467 : };
4468 :
4469 : explicit WasmStreaming(std::unique_ptr<WasmStreamingImpl> impl);
4470 :
4471 : ~WasmStreaming();
4472 :
4473 : /**
4474 : * Pass a new chunk of bytes to WebAssembly streaming compilation.
4475 : * The buffer passed into {OnBytesReceived} is owned by the caller.
4476 : */
4477 : void OnBytesReceived(const uint8_t* bytes, size_t size);
4478 :
4479 : /**
4480 : * {Finish} should be called after all received bytes where passed to
4481 : * {OnBytesReceived} to tell V8 that there will be no more bytes. {Finish}
4482 : * does not have to be called after {Abort} has been called already.
4483 : */
4484 : void Finish();
4485 :
4486 : /**
4487 : * Abort streaming compilation. If {exception} has a value, then the promise
4488 : * associated with streaming compilation is rejected with that value. If
4489 : * {exception} does not have value, the promise does not get rejected.
4490 : */
4491 : void Abort(MaybeLocal<Value> exception);
4492 :
4493 : /**
4494 : * Passes previously compiled module bytes. This must be called before
4495 : * {OnBytesReceived}, {Finish}, or {Abort}. Returns true if the module bytes
4496 : * can be used, false otherwise. The buffer passed via {bytes} and {size}
4497 : * is owned by the caller. If {SetCompiledModuleBytes} returns true, the
4498 : * buffer must remain valid until either {Finish} or {Abort} completes.
4499 : */
4500 : bool SetCompiledModuleBytes(const uint8_t* bytes, size_t size);
4501 :
4502 : /**
4503 : * Sets the client object that will receive streaming event notifications.
4504 : * This must be called before {OnBytesReceived}, {Finish}, or {Abort}.
4505 : */
4506 : void SetClient(std::shared_ptr<Client> client);
4507 :
4508 : /**
4509 : * Unpacks a {WasmStreaming} object wrapped in a {Managed} for the embedder.
4510 : * Since the embedder is on the other side of the API, it cannot unpack the
4511 : * {Managed} itself.
4512 : */
4513 : static std::shared_ptr<WasmStreaming> Unpack(Isolate* isolate,
4514 : Local<Value> value);
4515 :
4516 : private:
4517 : std::unique_ptr<WasmStreamingImpl> impl_;
4518 : };
4519 :
4520 : // TODO(mtrofin): when streaming compilation is done, we can rename this
4521 : // to simply WasmModuleObjectBuilder
4522 : class V8_EXPORT WasmModuleObjectBuilderStreaming final {
4523 : public:
4524 : explicit WasmModuleObjectBuilderStreaming(Isolate* isolate);
4525 : /**
4526 : * The buffer passed into OnBytesReceived is owned by the caller.
4527 : */
4528 : void OnBytesReceived(const uint8_t*, size_t size);
4529 : void Finish();
4530 : /**
4531 : * Abort streaming compilation. If {exception} has a value, then the promise
4532 : * associated with streaming compilation is rejected with that value. If
4533 : * {exception} does not have value, the promise does not get rejected.
4534 : */
4535 : void Abort(MaybeLocal<Value> exception);
4536 : Local<Promise> GetPromise();
4537 :
4538 : ~WasmModuleObjectBuilderStreaming() = default;
4539 :
4540 : private:
4541 : WasmModuleObjectBuilderStreaming(const WasmModuleObjectBuilderStreaming&) =
4542 : delete;
4543 : WasmModuleObjectBuilderStreaming(WasmModuleObjectBuilderStreaming&&) =
4544 : default;
4545 : WasmModuleObjectBuilderStreaming& operator=(
4546 : const WasmModuleObjectBuilderStreaming&) = delete;
4547 : WasmModuleObjectBuilderStreaming& operator=(
4548 : WasmModuleObjectBuilderStreaming&&) = default;
4549 : Isolate* isolate_ = nullptr;
4550 :
4551 : #if V8_CC_MSVC
4552 : /**
4553 : * We don't need the static Copy API, so the default
4554 : * NonCopyablePersistentTraits would be sufficient, however,
4555 : * MSVC eagerly instantiates the Copy.
4556 : * We ensure we don't use Copy, however, by compiling with the
4557 : * defaults everywhere else.
4558 : */
4559 : Persistent<Promise, CopyablePersistentTraits<Promise>> promise_;
4560 : #else
4561 : Persistent<Promise> promise_;
4562 : #endif
4563 : std::shared_ptr<internal::wasm::StreamingDecoder> streaming_decoder_;
4564 : };
4565 :
4566 : #ifndef V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT
4567 : // The number of required internal fields can be defined by embedder.
4568 : #define V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT 2
4569 : #endif
4570 :
4571 :
4572 : enum class ArrayBufferCreationMode { kInternalized, kExternalized };
4573 :
4574 :
4575 : /**
4576 : * An instance of the built-in ArrayBuffer constructor (ES6 draft 15.13.5).
4577 : */
4578 : class V8_EXPORT ArrayBuffer : public Object {
4579 : public:
4580 : /**
4581 : * A thread-safe allocator that V8 uses to allocate |ArrayBuffer|'s memory.
4582 : * The allocator is a global V8 setting. It has to be set via
4583 : * Isolate::CreateParams.
4584 : *
4585 : * Memory allocated through this allocator by V8 is accounted for as external
4586 : * memory by V8. Note that V8 keeps track of the memory for all internalized
4587 : * |ArrayBuffer|s. Responsibility for tracking external memory (using
4588 : * Isolate::AdjustAmountOfExternalAllocatedMemory) is handed over to the
4589 : * embedder upon externalization and taken over upon internalization (creating
4590 : * an internalized buffer from an existing buffer).
4591 : *
4592 : * Note that it is unsafe to call back into V8 from any of the allocator
4593 : * functions.
4594 : */
4595 204489 : class V8_EXPORT Allocator { // NOLINT
4596 : public:
4597 174108 : virtual ~Allocator() = default;
4598 :
4599 : /**
4600 : * Allocate |length| bytes. Return NULL if allocation is not successful.
4601 : * Memory should be initialized to zeroes.
4602 : */
4603 : virtual void* Allocate(size_t length) = 0;
4604 :
4605 : /**
4606 : * Allocate |length| bytes. Return NULL if allocation is not successful.
4607 : * Memory does not have to be initialized.
4608 : */
4609 : virtual void* AllocateUninitialized(size_t length) = 0;
4610 :
4611 : /**
4612 : * Free the memory block of size |length|, pointed to by |data|.
4613 : * That memory is guaranteed to be previously allocated by |Allocate|.
4614 : */
4615 : virtual void Free(void* data, size_t length) = 0;
4616 :
4617 : /**
4618 : * ArrayBuffer allocation mode. kNormal is a malloc/free style allocation,
4619 : * while kReservation is for larger allocations with the ability to set
4620 : * access permissions.
4621 : */
4622 : enum class AllocationMode { kNormal, kReservation };
4623 :
4624 : /**
4625 : * malloc/free based convenience allocator.
4626 : *
4627 : * Caller takes ownership, i.e. the returned object needs to be freed using
4628 : * |delete allocator| once it is no longer in use.
4629 : */
4630 : static Allocator* NewDefaultAllocator();
4631 : };
4632 :
4633 : /**
4634 : * The contents of an |ArrayBuffer|. Externalization of |ArrayBuffer|
4635 : * returns an instance of this class, populated, with a pointer to data
4636 : * and byte length.
4637 : *
4638 : * The Data pointer of ArrayBuffer::Contents must be freed using the provided
4639 : * deleter, which will call ArrayBuffer::Allocator::Free if the buffer
4640 : * was allocated with ArraryBuffer::Allocator::Allocate.
4641 : */
4642 : class V8_EXPORT Contents { // NOLINT
4643 : public:
4644 : using DeleterCallback = void (*)(void* buffer, size_t length, void* info);
4645 :
4646 : Contents()
4647 : : data_(nullptr),
4648 : byte_length_(0),
4649 : allocation_base_(nullptr),
4650 : allocation_length_(0),
4651 : allocation_mode_(Allocator::AllocationMode::kNormal),
4652 : deleter_(nullptr),
4653 : deleter_data_(nullptr) {}
4654 :
4655 : void* AllocationBase() const { return allocation_base_; }
4656 : size_t AllocationLength() const { return allocation_length_; }
4657 : Allocator::AllocationMode AllocationMode() const {
4658 : return allocation_mode_;
4659 : }
4660 :
4661 : void* Data() const { return data_; }
4662 : size_t ByteLength() const { return byte_length_; }
4663 : DeleterCallback Deleter() const { return deleter_; }
4664 : void* DeleterData() const { return deleter_data_; }
4665 :
4666 : private:
4667 : Contents(void* data, size_t byte_length, void* allocation_base,
4668 : size_t allocation_length,
4669 : Allocator::AllocationMode allocation_mode, DeleterCallback deleter,
4670 : void* deleter_data);
4671 :
4672 : void* data_;
4673 : size_t byte_length_;
4674 : void* allocation_base_;
4675 : size_t allocation_length_;
4676 : Allocator::AllocationMode allocation_mode_;
4677 : DeleterCallback deleter_;
4678 : void* deleter_data_;
4679 :
4680 : friend class ArrayBuffer;
4681 : };
4682 :
4683 :
4684 : /**
4685 : * Data length in bytes.
4686 : */
4687 : size_t ByteLength() const;
4688 :
4689 : /**
4690 : * Create a new ArrayBuffer. Allocate |byte_length| bytes.
4691 : * Allocated memory will be owned by a created ArrayBuffer and
4692 : * will be deallocated when it is garbage-collected,
4693 : * unless the object is externalized.
4694 : */
4695 : static Local<ArrayBuffer> New(Isolate* isolate, size_t byte_length);
4696 :
4697 : /**
4698 : * Create a new ArrayBuffer over an existing memory block.
4699 : * The created array buffer is by default immediately in externalized state.
4700 : * In externalized state, the memory block will not be reclaimed when a
4701 : * created ArrayBuffer is garbage-collected.
4702 : * In internalized state, the memory block will be released using
4703 : * |Allocator::Free| once all ArrayBuffers referencing it are collected by
4704 : * the garbage collector.
4705 : */
4706 : static Local<ArrayBuffer> New(
4707 : Isolate* isolate, void* data, size_t byte_length,
4708 : ArrayBufferCreationMode mode = ArrayBufferCreationMode::kExternalized);
4709 :
4710 : /**
4711 : * Returns true if ArrayBuffer is externalized, that is, does not
4712 : * own its memory block.
4713 : */
4714 : bool IsExternal() const;
4715 :
4716 : /**
4717 : * Returns true if this ArrayBuffer may be detached.
4718 : */
4719 : bool IsDetachable() const;
4720 :
4721 : // TODO(913887): fix the use of 'neuter' in the API.
4722 : V8_DEPRECATE_SOON("Use IsDetachable() instead.",
4723 : inline bool IsNeuterable() const) {
4724 : return IsDetachable();
4725 : }
4726 :
4727 : /**
4728 : * Detaches this ArrayBuffer and all its views (typed arrays).
4729 : * Detaching sets the byte length of the buffer and all typed arrays to zero,
4730 : * preventing JavaScript from ever accessing underlying backing store.
4731 : * ArrayBuffer should have been externalized and must be detachable.
4732 : */
4733 : void Detach();
4734 :
4735 : // TODO(913887): fix the use of 'neuter' in the API.
4736 : V8_DEPRECATE_SOON("Use Detach() instead.", inline void Neuter()) { Detach(); }
4737 :
4738 : /**
4739 : * Make this ArrayBuffer external. The pointer to underlying memory block
4740 : * and byte length are returned as |Contents| structure. After ArrayBuffer
4741 : * had been externalized, it does no longer own the memory block. The caller
4742 : * should take steps to free memory when it is no longer needed.
4743 : *
4744 : * The Data pointer of ArrayBuffer::Contents must be freed using the provided
4745 : * deleter, which will call ArrayBuffer::Allocator::Free if the buffer
4746 : * was allocated with ArraryBuffer::Allocator::Allocate.
4747 : */
4748 : Contents Externalize();
4749 :
4750 : /**
4751 : * Get a pointer to the ArrayBuffer's underlying memory block without
4752 : * externalizing it. If the ArrayBuffer is not externalized, this pointer
4753 : * will become invalid as soon as the ArrayBuffer gets garbage collected.
4754 : *
4755 : * The embedder should make sure to hold a strong reference to the
4756 : * ArrayBuffer while accessing this pointer.
4757 : */
4758 : Contents GetContents();
4759 :
4760 : V8_INLINE static ArrayBuffer* Cast(Value* obj);
4761 :
4762 : static const int kInternalFieldCount = V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT;
4763 : static const int kEmbedderFieldCount = V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT;
4764 :
4765 : private:
4766 : ArrayBuffer();
4767 : static void CheckCast(Value* obj);
4768 : };
4769 :
4770 :
4771 : #ifndef V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT
4772 : // The number of required internal fields can be defined by embedder.
4773 : #define V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT 2
4774 : #endif
4775 :
4776 :
4777 : /**
4778 : * A base class for an instance of one of "views" over ArrayBuffer,
4779 : * including TypedArrays and DataView (ES6 draft 15.13).
4780 : */
4781 : class V8_EXPORT ArrayBufferView : public Object {
4782 : public:
4783 : /**
4784 : * Returns underlying ArrayBuffer.
4785 : */
4786 : Local<ArrayBuffer> Buffer();
4787 : /**
4788 : * Byte offset in |Buffer|.
4789 : */
4790 : size_t ByteOffset();
4791 : /**
4792 : * Size of a view in bytes.
4793 : */
4794 : size_t ByteLength();
4795 :
4796 : /**
4797 : * Copy the contents of the ArrayBufferView's buffer to an embedder defined
4798 : * memory without additional overhead that calling ArrayBufferView::Buffer
4799 : * might incur.
4800 : *
4801 : * Will write at most min(|byte_length|, ByteLength) bytes starting at
4802 : * ByteOffset of the underlying buffer to the memory starting at |dest|.
4803 : * Returns the number of bytes actually written.
4804 : */
4805 : size_t CopyContents(void* dest, size_t byte_length);
4806 :
4807 : /**
4808 : * Returns true if ArrayBufferView's backing ArrayBuffer has already been
4809 : * allocated.
4810 : */
4811 : bool HasBuffer() const;
4812 :
4813 : V8_INLINE static ArrayBufferView* Cast(Value* obj);
4814 :
4815 : static const int kInternalFieldCount =
4816 : V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT;
4817 : static const int kEmbedderFieldCount =
4818 : V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT;
4819 :
4820 : private:
4821 : ArrayBufferView();
4822 : static void CheckCast(Value* obj);
4823 : };
4824 :
4825 :
4826 : /**
4827 : * A base class for an instance of TypedArray series of constructors
4828 : * (ES6 draft 15.13.6).
4829 : */
4830 : class V8_EXPORT TypedArray : public ArrayBufferView {
4831 : public:
4832 : /*
4833 : * The largest typed array size that can be constructed using New.
4834 : */
4835 : static constexpr size_t kMaxLength = internal::kSmiMaxValue;
4836 :
4837 : /**
4838 : * Number of elements in this typed array
4839 : * (e.g. for Int16Array, |ByteLength|/2).
4840 : */
4841 : size_t Length();
4842 :
4843 : V8_INLINE static TypedArray* Cast(Value* obj);
4844 :
4845 : private:
4846 : TypedArray();
4847 : static void CheckCast(Value* obj);
4848 : };
4849 :
4850 :
4851 : /**
4852 : * An instance of Uint8Array constructor (ES6 draft 15.13.6).
4853 : */
4854 : class V8_EXPORT Uint8Array : public TypedArray {
4855 : public:
4856 : static Local<Uint8Array> New(Local<ArrayBuffer> array_buffer,
4857 : size_t byte_offset, size_t length);
4858 : static Local<Uint8Array> New(Local<SharedArrayBuffer> shared_array_buffer,
4859 : size_t byte_offset, size_t length);
4860 : V8_INLINE static Uint8Array* Cast(Value* obj);
4861 :
4862 : private:
4863 : Uint8Array();
4864 : static void CheckCast(Value* obj);
4865 : };
4866 :
4867 :
4868 : /**
4869 : * An instance of Uint8ClampedArray constructor (ES6 draft 15.13.6).
4870 : */
4871 : class V8_EXPORT Uint8ClampedArray : public TypedArray {
4872 : public:
4873 : static Local<Uint8ClampedArray> New(Local<ArrayBuffer> array_buffer,
4874 : size_t byte_offset, size_t length);
4875 : static Local<Uint8ClampedArray> New(
4876 : Local<SharedArrayBuffer> shared_array_buffer, size_t byte_offset,
4877 : size_t length);
4878 : V8_INLINE static Uint8ClampedArray* Cast(Value* obj);
4879 :
4880 : private:
4881 : Uint8ClampedArray();
4882 : static void CheckCast(Value* obj);
4883 : };
4884 :
4885 : /**
4886 : * An instance of Int8Array constructor (ES6 draft 15.13.6).
4887 : */
4888 : class V8_EXPORT Int8Array : public TypedArray {
4889 : public:
4890 : static Local<Int8Array> New(Local<ArrayBuffer> array_buffer,
4891 : size_t byte_offset, size_t length);
4892 : static Local<Int8Array> New(Local<SharedArrayBuffer> shared_array_buffer,
4893 : size_t byte_offset, size_t length);
4894 : V8_INLINE static Int8Array* Cast(Value* obj);
4895 :
4896 : private:
4897 : Int8Array();
4898 : static void CheckCast(Value* obj);
4899 : };
4900 :
4901 :
4902 : /**
4903 : * An instance of Uint16Array constructor (ES6 draft 15.13.6).
4904 : */
4905 : class V8_EXPORT Uint16Array : public TypedArray {
4906 : public:
4907 : static Local<Uint16Array> New(Local<ArrayBuffer> array_buffer,
4908 : size_t byte_offset, size_t length);
4909 : static Local<Uint16Array> New(Local<SharedArrayBuffer> shared_array_buffer,
4910 : size_t byte_offset, size_t length);
4911 : V8_INLINE static Uint16Array* Cast(Value* obj);
4912 :
4913 : private:
4914 : Uint16Array();
4915 : static void CheckCast(Value* obj);
4916 : };
4917 :
4918 :
4919 : /**
4920 : * An instance of Int16Array constructor (ES6 draft 15.13.6).
4921 : */
4922 : class V8_EXPORT Int16Array : public TypedArray {
4923 : public:
4924 : static Local<Int16Array> New(Local<ArrayBuffer> array_buffer,
4925 : size_t byte_offset, size_t length);
4926 : static Local<Int16Array> New(Local<SharedArrayBuffer> shared_array_buffer,
4927 : size_t byte_offset, size_t length);
4928 : V8_INLINE static Int16Array* Cast(Value* obj);
4929 :
4930 : private:
4931 : Int16Array();
4932 : static void CheckCast(Value* obj);
4933 : };
4934 :
4935 :
4936 : /**
4937 : * An instance of Uint32Array constructor (ES6 draft 15.13.6).
4938 : */
4939 : class V8_EXPORT Uint32Array : public TypedArray {
4940 : public:
4941 : static Local<Uint32Array> New(Local<ArrayBuffer> array_buffer,
4942 : size_t byte_offset, size_t length);
4943 : static Local<Uint32Array> New(Local<SharedArrayBuffer> shared_array_buffer,
4944 : size_t byte_offset, size_t length);
4945 : V8_INLINE static Uint32Array* Cast(Value* obj);
4946 :
4947 : private:
4948 : Uint32Array();
4949 : static void CheckCast(Value* obj);
4950 : };
4951 :
4952 :
4953 : /**
4954 : * An instance of Int32Array constructor (ES6 draft 15.13.6).
4955 : */
4956 : class V8_EXPORT Int32Array : public TypedArray {
4957 : public:
4958 : static Local<Int32Array> New(Local<ArrayBuffer> array_buffer,
4959 : size_t byte_offset, size_t length);
4960 : static Local<Int32Array> New(Local<SharedArrayBuffer> shared_array_buffer,
4961 : size_t byte_offset, size_t length);
4962 : V8_INLINE static Int32Array* Cast(Value* obj);
4963 :
4964 : private:
4965 : Int32Array();
4966 : static void CheckCast(Value* obj);
4967 : };
4968 :
4969 :
4970 : /**
4971 : * An instance of Float32Array constructor (ES6 draft 15.13.6).
4972 : */
4973 : class V8_EXPORT Float32Array : public TypedArray {
4974 : public:
4975 : static Local<Float32Array> New(Local<ArrayBuffer> array_buffer,
4976 : size_t byte_offset, size_t length);
4977 : static Local<Float32Array> New(Local<SharedArrayBuffer> shared_array_buffer,
4978 : size_t byte_offset, size_t length);
4979 : V8_INLINE static Float32Array* Cast(Value* obj);
4980 :
4981 : private:
4982 : Float32Array();
4983 : static void CheckCast(Value* obj);
4984 : };
4985 :
4986 :
4987 : /**
4988 : * An instance of Float64Array constructor (ES6 draft 15.13.6).
4989 : */
4990 : class V8_EXPORT Float64Array : public TypedArray {
4991 : public:
4992 : static Local<Float64Array> New(Local<ArrayBuffer> array_buffer,
4993 : size_t byte_offset, size_t length);
4994 : static Local<Float64Array> New(Local<SharedArrayBuffer> shared_array_buffer,
4995 : size_t byte_offset, size_t length);
4996 : V8_INLINE static Float64Array* Cast(Value* obj);
4997 :
4998 : private:
4999 : Float64Array();
5000 : static void CheckCast(Value* obj);
5001 : };
5002 :
5003 : /**
5004 : * An instance of BigInt64Array constructor.
5005 : */
5006 : class V8_EXPORT BigInt64Array : public TypedArray {
5007 : public:
5008 : static Local<BigInt64Array> New(Local<ArrayBuffer> array_buffer,
5009 : size_t byte_offset, size_t length);
5010 : static Local<BigInt64Array> New(Local<SharedArrayBuffer> shared_array_buffer,
5011 : size_t byte_offset, size_t length);
5012 : V8_INLINE static BigInt64Array* Cast(Value* obj);
5013 :
5014 : private:
5015 : BigInt64Array();
5016 : static void CheckCast(Value* obj);
5017 : };
5018 :
5019 : /**
5020 : * An instance of BigUint64Array constructor.
5021 : */
5022 : class V8_EXPORT BigUint64Array : public TypedArray {
5023 : public:
5024 : static Local<BigUint64Array> New(Local<ArrayBuffer> array_buffer,
5025 : size_t byte_offset, size_t length);
5026 : static Local<BigUint64Array> New(Local<SharedArrayBuffer> shared_array_buffer,
5027 : size_t byte_offset, size_t length);
5028 : V8_INLINE static BigUint64Array* Cast(Value* obj);
5029 :
5030 : private:
5031 : BigUint64Array();
5032 : static void CheckCast(Value* obj);
5033 : };
5034 :
5035 : /**
5036 : * An instance of DataView constructor (ES6 draft 15.13.7).
5037 : */
5038 : class V8_EXPORT DataView : public ArrayBufferView {
5039 : public:
5040 : static Local<DataView> New(Local<ArrayBuffer> array_buffer,
5041 : size_t byte_offset, size_t length);
5042 : static Local<DataView> New(Local<SharedArrayBuffer> shared_array_buffer,
5043 : size_t byte_offset, size_t length);
5044 : V8_INLINE static DataView* Cast(Value* obj);
5045 :
5046 : private:
5047 : DataView();
5048 : static void CheckCast(Value* obj);
5049 : };
5050 :
5051 :
5052 : /**
5053 : * An instance of the built-in SharedArrayBuffer constructor.
5054 : * This API is experimental and may change significantly.
5055 : */
5056 : class V8_EXPORT SharedArrayBuffer : public Object {
5057 : public:
5058 : /**
5059 : * The contents of an |SharedArrayBuffer|. Externalization of
5060 : * |SharedArrayBuffer| returns an instance of this class, populated, with a
5061 : * pointer to data and byte length.
5062 : *
5063 : * The Data pointer of ArrayBuffer::Contents must be freed using the provided
5064 : * deleter, which will call ArrayBuffer::Allocator::Free if the buffer
5065 : * was allocated with ArraryBuffer::Allocator::Allocate.
5066 : *
5067 : * This API is experimental and may change significantly.
5068 : */
5069 : class V8_EXPORT Contents { // NOLINT
5070 : public:
5071 : using Allocator = v8::ArrayBuffer::Allocator;
5072 : using DeleterCallback = void (*)(void* buffer, size_t length, void* info);
5073 :
5074 : Contents()
5075 : : data_(nullptr),
5076 : byte_length_(0),
5077 : allocation_base_(nullptr),
5078 : allocation_length_(0),
5079 : allocation_mode_(Allocator::AllocationMode::kNormal),
5080 : deleter_(nullptr),
5081 : deleter_data_(nullptr) {}
5082 :
5083 : void* AllocationBase() const { return allocation_base_; }
5084 : size_t AllocationLength() const { return allocation_length_; }
5085 : Allocator::AllocationMode AllocationMode() const {
5086 : return allocation_mode_;
5087 : }
5088 :
5089 : void* Data() const { return data_; }
5090 : size_t ByteLength() const { return byte_length_; }
5091 : DeleterCallback Deleter() const { return deleter_; }
5092 : void* DeleterData() const { return deleter_data_; }
5093 :
5094 : private:
5095 : Contents(void* data, size_t byte_length, void* allocation_base,
5096 : size_t allocation_length,
5097 : Allocator::AllocationMode allocation_mode, DeleterCallback deleter,
5098 : void* deleter_data);
5099 :
5100 : void* data_;
5101 : size_t byte_length_;
5102 : void* allocation_base_;
5103 : size_t allocation_length_;
5104 : Allocator::AllocationMode allocation_mode_;
5105 : DeleterCallback deleter_;
5106 : void* deleter_data_;
5107 :
5108 : friend class SharedArrayBuffer;
5109 : };
5110 :
5111 : /**
5112 : * Data length in bytes.
5113 : */
5114 : size_t ByteLength() const;
5115 :
5116 : /**
5117 : * Create a new SharedArrayBuffer. Allocate |byte_length| bytes.
5118 : * Allocated memory will be owned by a created SharedArrayBuffer and
5119 : * will be deallocated when it is garbage-collected,
5120 : * unless the object is externalized.
5121 : */
5122 : static Local<SharedArrayBuffer> New(Isolate* isolate, size_t byte_length);
5123 :
5124 : /**
5125 : * Create a new SharedArrayBuffer over an existing memory block. The created
5126 : * array buffer is immediately in externalized state unless otherwise
5127 : * specified. The memory block will not be reclaimed when a created
5128 : * SharedArrayBuffer is garbage-collected.
5129 : */
5130 : static Local<SharedArrayBuffer> New(
5131 : Isolate* isolate, void* data, size_t byte_length,
5132 : ArrayBufferCreationMode mode = ArrayBufferCreationMode::kExternalized);
5133 :
5134 : /**
5135 : * Returns true if SharedArrayBuffer is externalized, that is, does not
5136 : * own its memory block.
5137 : */
5138 : bool IsExternal() const;
5139 :
5140 : /**
5141 : * Make this SharedArrayBuffer external. The pointer to underlying memory
5142 : * block and byte length are returned as |Contents| structure. After
5143 : * SharedArrayBuffer had been externalized, it does no longer own the memory
5144 : * block. The caller should take steps to free memory when it is no longer
5145 : * needed.
5146 : *
5147 : * The memory block is guaranteed to be allocated with |Allocator::Allocate|
5148 : * by the allocator specified in
5149 : * v8::Isolate::CreateParams::array_buffer_allocator.
5150 : *
5151 : */
5152 : Contents Externalize();
5153 :
5154 : /**
5155 : * Get a pointer to the ArrayBuffer's underlying memory block without
5156 : * externalizing it. If the ArrayBuffer is not externalized, this pointer
5157 : * will become invalid as soon as the ArrayBuffer became garbage collected.
5158 : *
5159 : * The embedder should make sure to hold a strong reference to the
5160 : * ArrayBuffer while accessing this pointer.
5161 : *
5162 : * The memory block is guaranteed to be allocated with |Allocator::Allocate|
5163 : * by the allocator specified in
5164 : * v8::Isolate::CreateParams::array_buffer_allocator.
5165 : */
5166 : Contents GetContents();
5167 :
5168 : V8_INLINE static SharedArrayBuffer* Cast(Value* obj);
5169 :
5170 : static const int kInternalFieldCount = V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT;
5171 :
5172 : private:
5173 : SharedArrayBuffer();
5174 : static void CheckCast(Value* obj);
5175 : };
5176 :
5177 :
5178 : /**
5179 : * An instance of the built-in Date constructor (ECMA-262, 15.9).
5180 : */
5181 : class V8_EXPORT Date : public Object {
5182 : public:
5183 : static V8_WARN_UNUSED_RESULT MaybeLocal<Value> New(Local<Context> context,
5184 : double time);
5185 :
5186 : /**
5187 : * A specialization of Value::NumberValue that is more efficient
5188 : * because we know the structure of this object.
5189 : */
5190 : double ValueOf() const;
5191 :
5192 : V8_INLINE static Date* Cast(Value* obj);
5193 :
5194 : /**
5195 : * Notification that the embedder has changed the time zone,
5196 : * daylight savings time, or other date / time configuration
5197 : * parameters. V8 keeps a cache of various values used for
5198 : * date / time computation. This notification will reset
5199 : * those cached values for the current context so that date /
5200 : * time configuration changes would be reflected in the Date
5201 : * object.
5202 : *
5203 : * This API should not be called more than needed as it will
5204 : * negatively impact the performance of date operations.
5205 : */
5206 : static void DateTimeConfigurationChangeNotification(Isolate* isolate);
5207 :
5208 : private:
5209 : static void CheckCast(Value* obj);
5210 : };
5211 :
5212 :
5213 : /**
5214 : * A Number object (ECMA-262, 4.3.21).
5215 : */
5216 : class V8_EXPORT NumberObject : public Object {
5217 : public:
5218 : static Local<Value> New(Isolate* isolate, double value);
5219 :
5220 : double ValueOf() const;
5221 :
5222 : V8_INLINE static NumberObject* Cast(Value* obj);
5223 :
5224 : private:
5225 : static void CheckCast(Value* obj);
5226 : };
5227 :
5228 : /**
5229 : * A BigInt object (https://tc39.github.io/proposal-bigint)
5230 : */
5231 : class V8_EXPORT BigIntObject : public Object {
5232 : public:
5233 : static Local<Value> New(Isolate* isolate, int64_t value);
5234 :
5235 : Local<BigInt> ValueOf() const;
5236 :
5237 : V8_INLINE static BigIntObject* Cast(Value* obj);
5238 :
5239 : private:
5240 : static void CheckCast(Value* obj);
5241 : };
5242 :
5243 : /**
5244 : * A Boolean object (ECMA-262, 4.3.15).
5245 : */
5246 : class V8_EXPORT BooleanObject : public Object {
5247 : public:
5248 : static Local<Value> New(Isolate* isolate, bool value);
5249 :
5250 : bool ValueOf() const;
5251 :
5252 : V8_INLINE static BooleanObject* Cast(Value* obj);
5253 :
5254 : private:
5255 : static void CheckCast(Value* obj);
5256 : };
5257 :
5258 :
5259 : /**
5260 : * A String object (ECMA-262, 4.3.18).
5261 : */
5262 : class V8_EXPORT StringObject : public Object {
5263 : public:
5264 : static Local<Value> New(Isolate* isolate, Local<String> value);
5265 :
5266 : Local<String> ValueOf() const;
5267 :
5268 : V8_INLINE static StringObject* Cast(Value* obj);
5269 :
5270 : private:
5271 : static void CheckCast(Value* obj);
5272 : };
5273 :
5274 :
5275 : /**
5276 : * A Symbol object (ECMA-262 edition 6).
5277 : */
5278 : class V8_EXPORT SymbolObject : public Object {
5279 : public:
5280 : static Local<Value> New(Isolate* isolate, Local<Symbol> value);
5281 :
5282 : Local<Symbol> ValueOf() const;
5283 :
5284 : V8_INLINE static SymbolObject* Cast(Value* obj);
5285 :
5286 : private:
5287 : static void CheckCast(Value* obj);
5288 : };
5289 :
5290 :
5291 : /**
5292 : * An instance of the built-in RegExp constructor (ECMA-262, 15.10).
5293 : */
5294 : class V8_EXPORT RegExp : public Object {
5295 : public:
5296 : /**
5297 : * Regular expression flag bits. They can be or'ed to enable a set
5298 : * of flags.
5299 : */
5300 : enum Flags {
5301 : kNone = 0,
5302 : kGlobal = 1 << 0,
5303 : kIgnoreCase = 1 << 1,
5304 : kMultiline = 1 << 2,
5305 : kSticky = 1 << 3,
5306 : kUnicode = 1 << 4,
5307 : kDotAll = 1 << 5,
5308 : };
5309 :
5310 : /**
5311 : * Creates a regular expression from the given pattern string and
5312 : * the flags bit field. May throw a JavaScript exception as
5313 : * described in ECMA-262, 15.10.4.1.
5314 : *
5315 : * For example,
5316 : * RegExp::New(v8::String::New("foo"),
5317 : * static_cast<RegExp::Flags>(kGlobal | kMultiline))
5318 : * is equivalent to evaluating "/foo/gm".
5319 : */
5320 : static V8_WARN_UNUSED_RESULT MaybeLocal<RegExp> New(Local<Context> context,
5321 : Local<String> pattern,
5322 : Flags flags);
5323 :
5324 : /**
5325 : * Returns the value of the source property: a string representing
5326 : * the regular expression.
5327 : */
5328 : Local<String> GetSource() const;
5329 :
5330 : /**
5331 : * Returns the flags bit field.
5332 : */
5333 : Flags GetFlags() const;
5334 :
5335 : V8_INLINE static RegExp* Cast(Value* obj);
5336 :
5337 : private:
5338 : static void CheckCast(Value* obj);
5339 : };
5340 :
5341 :
5342 : /**
5343 : * A JavaScript value that wraps a C++ void*. This type of value is mainly used
5344 : * to associate C++ data structures with JavaScript objects.
5345 : */
5346 : class V8_EXPORT External : public Value {
5347 : public:
5348 : static Local<External> New(Isolate* isolate, void* value);
5349 : V8_INLINE static External* Cast(Value* obj);
5350 : void* Value() const;
5351 : private:
5352 : static void CheckCast(v8::Value* obj);
5353 : };
5354 :
5355 : #define V8_INTRINSICS_LIST(F) \
5356 : F(ArrayProto_entries, array_entries_iterator) \
5357 : F(ArrayProto_forEach, array_for_each_iterator) \
5358 : F(ArrayProto_keys, array_keys_iterator) \
5359 : F(ArrayProto_values, array_values_iterator) \
5360 : F(ErrorPrototype, initial_error_prototype) \
5361 : F(IteratorPrototype, initial_iterator_prototype)
5362 :
5363 : enum Intrinsic {
5364 : #define V8_DECL_INTRINSIC(name, iname) k##name,
5365 : V8_INTRINSICS_LIST(V8_DECL_INTRINSIC)
5366 : #undef V8_DECL_INTRINSIC
5367 : };
5368 :
5369 :
5370 : // --- Templates ---
5371 :
5372 :
5373 : /**
5374 : * The superclass of object and function templates.
5375 : */
5376 : class V8_EXPORT Template : public Data {
5377 : public:
5378 : /**
5379 : * Adds a property to each instance created by this template.
5380 : *
5381 : * The property must be defined either as a primitive value, or a template.
5382 : */
5383 : void Set(Local<Name> name, Local<Data> value,
5384 : PropertyAttribute attributes = None);
5385 : void SetPrivate(Local<Private> name, Local<Data> value,
5386 : PropertyAttribute attributes = None);
5387 : V8_INLINE void Set(Isolate* isolate, const char* name, Local<Data> value);
5388 :
5389 : void SetAccessorProperty(
5390 : Local<Name> name,
5391 : Local<FunctionTemplate> getter = Local<FunctionTemplate>(),
5392 : Local<FunctionTemplate> setter = Local<FunctionTemplate>(),
5393 : PropertyAttribute attribute = None,
5394 : AccessControl settings = DEFAULT);
5395 :
5396 : /**
5397 : * Whenever the property with the given name is accessed on objects
5398 : * created from this Template the getter and setter callbacks
5399 : * are called instead of getting and setting the property directly
5400 : * on the JavaScript object.
5401 : *
5402 : * \param name The name of the property for which an accessor is added.
5403 : * \param getter The callback to invoke when getting the property.
5404 : * \param setter The callback to invoke when setting the property.
5405 : * \param data A piece of data that will be passed to the getter and setter
5406 : * callbacks whenever they are invoked.
5407 : * \param settings Access control settings for the accessor. This is a bit
5408 : * field consisting of one of more of
5409 : * DEFAULT = 0, ALL_CAN_READ = 1, or ALL_CAN_WRITE = 2.
5410 : * The default is to not allow cross-context access.
5411 : * ALL_CAN_READ means that all cross-context reads are allowed.
5412 : * ALL_CAN_WRITE means that all cross-context writes are allowed.
5413 : * The combination ALL_CAN_READ | ALL_CAN_WRITE can be used to allow all
5414 : * cross-context access.
5415 : * \param attribute The attributes of the property for which an accessor
5416 : * is added.
5417 : * \param signature The signature describes valid receivers for the accessor
5418 : * and is used to perform implicit instance checks against them. If the
5419 : * receiver is incompatible (i.e. is not an instance of the constructor as
5420 : * defined by FunctionTemplate::HasInstance()), an implicit TypeError is
5421 : * thrown and no callback is invoked.
5422 : */
5423 : void SetNativeDataProperty(
5424 : Local<String> name, AccessorGetterCallback getter,
5425 : AccessorSetterCallback setter = nullptr,
5426 : // TODO(dcarney): gcc can't handle Local below
5427 : Local<Value> data = Local<Value>(), PropertyAttribute attribute = None,
5428 : Local<AccessorSignature> signature = Local<AccessorSignature>(),
5429 : AccessControl settings = DEFAULT,
5430 : SideEffectType getter_side_effect_type = SideEffectType::kHasSideEffect,
5431 : SideEffectType setter_side_effect_type = SideEffectType::kHasSideEffect);
5432 : void SetNativeDataProperty(
5433 : Local<Name> name, AccessorNameGetterCallback getter,
5434 : AccessorNameSetterCallback setter = nullptr,
5435 : // TODO(dcarney): gcc can't handle Local below
5436 : Local<Value> data = Local<Value>(), PropertyAttribute attribute = None,
5437 : Local<AccessorSignature> signature = Local<AccessorSignature>(),
5438 : AccessControl settings = DEFAULT,
5439 : SideEffectType getter_side_effect_type = SideEffectType::kHasSideEffect,
5440 : SideEffectType setter_side_effect_type = SideEffectType::kHasSideEffect);
5441 :
5442 : /**
5443 : * Like SetNativeDataProperty, but V8 will replace the native data property
5444 : * with a real data property on first access.
5445 : */
5446 : void SetLazyDataProperty(
5447 : Local<Name> name, AccessorNameGetterCallback getter,
5448 : Local<Value> data = Local<Value>(), PropertyAttribute attribute = None,
5449 : SideEffectType getter_side_effect_type = SideEffectType::kHasSideEffect,
5450 : SideEffectType setter_side_effect_type = SideEffectType::kHasSideEffect);
5451 :
5452 : /**
5453 : * During template instantiation, sets the value with the intrinsic property
5454 : * from the correct context.
5455 : */
5456 : void SetIntrinsicDataProperty(Local<Name> name, Intrinsic intrinsic,
5457 : PropertyAttribute attribute = None);
5458 :
5459 : private:
5460 : Template();
5461 :
5462 : friend class ObjectTemplate;
5463 : friend class FunctionTemplate;
5464 : };
5465 :
5466 : // TODO(dcarney): Replace GenericNamedPropertyFooCallback with just
5467 : // NamedPropertyFooCallback.
5468 :
5469 : /**
5470 : * Interceptor for get requests on an object.
5471 : *
5472 : * Use `info.GetReturnValue().Set()` to set the return value of the
5473 : * intercepted get request.
5474 : *
5475 : * \param property The name of the property for which the request was
5476 : * intercepted.
5477 : * \param info Information about the intercepted request, such as
5478 : * isolate, receiver, return value, or whether running in `'use strict`' mode.
5479 : * See `PropertyCallbackInfo`.
5480 : *
5481 : * \code
5482 : * void GetterCallback(
5483 : * Local<Name> name,
5484 : * const v8::PropertyCallbackInfo<v8::Value>& info) {
5485 : * info.GetReturnValue().Set(v8_num(42));
5486 : * }
5487 : *
5488 : * v8::Local<v8::FunctionTemplate> templ =
5489 : * v8::FunctionTemplate::New(isolate);
5490 : * templ->InstanceTemplate()->SetHandler(
5491 : * v8::NamedPropertyHandlerConfiguration(GetterCallback));
5492 : * LocalContext env;
5493 : * env->Global()
5494 : * ->Set(env.local(), v8_str("obj"), templ->GetFunction(env.local())
5495 : * .ToLocalChecked()
5496 : * ->NewInstance(env.local())
5497 : * .ToLocalChecked())
5498 : * .FromJust();
5499 : * v8::Local<v8::Value> result = CompileRun("obj.a = 17; obj.a");
5500 : * CHECK(v8_num(42)->Equals(env.local(), result).FromJust());
5501 : * \endcode
5502 : *
5503 : * See also `ObjectTemplate::SetHandler`.
5504 : */
5505 : typedef void (*GenericNamedPropertyGetterCallback)(
5506 : Local<Name> property, const PropertyCallbackInfo<Value>& info);
5507 :
5508 : /**
5509 : * Interceptor for set requests on an object.
5510 : *
5511 : * Use `info.GetReturnValue()` to indicate whether the request was intercepted
5512 : * or not. If the setter successfully intercepts the request, i.e., if the
5513 : * request should not be further executed, call
5514 : * `info.GetReturnValue().Set(value)`. If the setter
5515 : * did not intercept the request, i.e., if the request should be handled as
5516 : * if no interceptor is present, do not not call `Set()`.
5517 : *
5518 : * \param property The name of the property for which the request was
5519 : * intercepted.
5520 : * \param value The value which the property will have if the request
5521 : * is not intercepted.
5522 : * \param info Information about the intercepted request, such as
5523 : * isolate, receiver, return value, or whether running in `'use strict'` mode.
5524 : * See `PropertyCallbackInfo`.
5525 : *
5526 : * See also
5527 : * `ObjectTemplate::SetHandler.`
5528 : */
5529 : typedef void (*GenericNamedPropertySetterCallback)(
5530 : Local<Name> property, Local<Value> value,
5531 : const PropertyCallbackInfo<Value>& info);
5532 :
5533 : /**
5534 : * Intercepts all requests that query the attributes of the
5535 : * property, e.g., getOwnPropertyDescriptor(), propertyIsEnumerable(), and
5536 : * defineProperty().
5537 : *
5538 : * Use `info.GetReturnValue().Set(value)` to set the property attributes. The
5539 : * value is an integer encoding a `v8::PropertyAttribute`.
5540 : *
5541 : * \param property The name of the property for which the request was
5542 : * intercepted.
5543 : * \param info Information about the intercepted request, such as
5544 : * isolate, receiver, return value, or whether running in `'use strict'` mode.
5545 : * See `PropertyCallbackInfo`.
5546 : *
5547 : * \note Some functions query the property attributes internally, even though
5548 : * they do not return the attributes. For example, `hasOwnProperty()` can
5549 : * trigger this interceptor depending on the state of the object.
5550 : *
5551 : * See also
5552 : * `ObjectTemplate::SetHandler.`
5553 : */
5554 : typedef void (*GenericNamedPropertyQueryCallback)(
5555 : Local<Name> property, const PropertyCallbackInfo<Integer>& info);
5556 :
5557 : /**
5558 : * Interceptor for delete requests on an object.
5559 : *
5560 : * Use `info.GetReturnValue()` to indicate whether the request was intercepted
5561 : * or not. If the deleter successfully intercepts the request, i.e., if the
5562 : * request should not be further executed, call
5563 : * `info.GetReturnValue().Set(value)` with a boolean `value`. The `value` is
5564 : * used as the return value of `delete`.
5565 : *
5566 : * \param property The name of the property for which the request was
5567 : * intercepted.
5568 : * \param info Information about the intercepted request, such as
5569 : * isolate, receiver, return value, or whether running in `'use strict'` mode.
5570 : * See `PropertyCallbackInfo`.
5571 : *
5572 : * \note If you need to mimic the behavior of `delete`, i.e., throw in strict
5573 : * mode instead of returning false, use `info.ShouldThrowOnError()` to determine
5574 : * if you are in strict mode.
5575 : *
5576 : * See also `ObjectTemplate::SetHandler.`
5577 : */
5578 : typedef void (*GenericNamedPropertyDeleterCallback)(
5579 : Local<Name> property, const PropertyCallbackInfo<Boolean>& info);
5580 :
5581 : /**
5582 : * Returns an array containing the names of the properties the named
5583 : * property getter intercepts.
5584 : *
5585 : * Note: The values in the array must be of type v8::Name.
5586 : */
5587 : typedef void (*GenericNamedPropertyEnumeratorCallback)(
5588 : const PropertyCallbackInfo<Array>& info);
5589 :
5590 : /**
5591 : * Interceptor for defineProperty requests on an object.
5592 : *
5593 : * Use `info.GetReturnValue()` to indicate whether the request was intercepted
5594 : * or not. If the definer successfully intercepts the request, i.e., if the
5595 : * request should not be further executed, call
5596 : * `info.GetReturnValue().Set(value)`. If the definer
5597 : * did not intercept the request, i.e., if the request should be handled as
5598 : * if no interceptor is present, do not not call `Set()`.
5599 : *
5600 : * \param property The name of the property for which the request was
5601 : * intercepted.
5602 : * \param desc The property descriptor which is used to define the
5603 : * property if the request is not intercepted.
5604 : * \param info Information about the intercepted request, such as
5605 : * isolate, receiver, return value, or whether running in `'use strict'` mode.
5606 : * See `PropertyCallbackInfo`.
5607 : *
5608 : * See also `ObjectTemplate::SetHandler`.
5609 : */
5610 : typedef void (*GenericNamedPropertyDefinerCallback)(
5611 : Local<Name> property, const PropertyDescriptor& desc,
5612 : const PropertyCallbackInfo<Value>& info);
5613 :
5614 : /**
5615 : * Interceptor for getOwnPropertyDescriptor requests on an object.
5616 : *
5617 : * Use `info.GetReturnValue().Set()` to set the return value of the
5618 : * intercepted request. The return value must be an object that
5619 : * can be converted to a PropertyDescriptor, e.g., a `v8::value` returned from
5620 : * `v8::Object::getOwnPropertyDescriptor`.
5621 : *
5622 : * \param property The name of the property for which the request was
5623 : * intercepted.
5624 : * \info Information about the intercepted request, such as
5625 : * isolate, receiver, return value, or whether running in `'use strict'` mode.
5626 : * See `PropertyCallbackInfo`.
5627 : *
5628 : * \note If GetOwnPropertyDescriptor is intercepted, it will
5629 : * always return true, i.e., indicate that the property was found.
5630 : *
5631 : * See also `ObjectTemplate::SetHandler`.
5632 : */
5633 : typedef void (*GenericNamedPropertyDescriptorCallback)(
5634 : Local<Name> property, const PropertyCallbackInfo<Value>& info);
5635 :
5636 : /**
5637 : * See `v8::GenericNamedPropertyGetterCallback`.
5638 : */
5639 : typedef void (*IndexedPropertyGetterCallback)(
5640 : uint32_t index,
5641 : const PropertyCallbackInfo<Value>& info);
5642 :
5643 : /**
5644 : * See `v8::GenericNamedPropertySetterCallback`.
5645 : */
5646 : typedef void (*IndexedPropertySetterCallback)(
5647 : uint32_t index,
5648 : Local<Value> value,
5649 : const PropertyCallbackInfo<Value>& info);
5650 :
5651 : /**
5652 : * See `v8::GenericNamedPropertyQueryCallback`.
5653 : */
5654 : typedef void (*IndexedPropertyQueryCallback)(
5655 : uint32_t index,
5656 : const PropertyCallbackInfo<Integer>& info);
5657 :
5658 : /**
5659 : * See `v8::GenericNamedPropertyDeleterCallback`.
5660 : */
5661 : typedef void (*IndexedPropertyDeleterCallback)(
5662 : uint32_t index,
5663 : const PropertyCallbackInfo<Boolean>& info);
5664 :
5665 : /**
5666 : * Returns an array containing the indices of the properties the indexed
5667 : * property getter intercepts.
5668 : *
5669 : * Note: The values in the array must be uint32_t.
5670 : */
5671 : typedef void (*IndexedPropertyEnumeratorCallback)(
5672 : const PropertyCallbackInfo<Array>& info);
5673 :
5674 : /**
5675 : * See `v8::GenericNamedPropertyDefinerCallback`.
5676 : */
5677 : typedef void (*IndexedPropertyDefinerCallback)(
5678 : uint32_t index, const PropertyDescriptor& desc,
5679 : const PropertyCallbackInfo<Value>& info);
5680 :
5681 : /**
5682 : * See `v8::GenericNamedPropertyDescriptorCallback`.
5683 : */
5684 : typedef void (*IndexedPropertyDescriptorCallback)(
5685 : uint32_t index, const PropertyCallbackInfo<Value>& info);
5686 :
5687 : /**
5688 : * Access type specification.
5689 : */
5690 : enum AccessType {
5691 : ACCESS_GET,
5692 : ACCESS_SET,
5693 : ACCESS_HAS,
5694 : ACCESS_DELETE,
5695 : ACCESS_KEYS
5696 : };
5697 :
5698 :
5699 : /**
5700 : * Returns true if the given context should be allowed to access the given
5701 : * object.
5702 : */
5703 : typedef bool (*AccessCheckCallback)(Local<Context> accessing_context,
5704 : Local<Object> accessed_object,
5705 : Local<Value> data);
5706 :
5707 : /**
5708 : * A FunctionTemplate is used to create functions at runtime. There
5709 : * can only be one function created from a FunctionTemplate in a
5710 : * context. The lifetime of the created function is equal to the
5711 : * lifetime of the context. So in case the embedder needs to create
5712 : * temporary functions that can be collected using Scripts is
5713 : * preferred.
5714 : *
5715 : * Any modification of a FunctionTemplate after first instantiation will trigger
5716 : * a crash.
5717 : *
5718 : * A FunctionTemplate can have properties, these properties are added to the
5719 : * function object when it is created.
5720 : *
5721 : * A FunctionTemplate has a corresponding instance template which is
5722 : * used to create object instances when the function is used as a
5723 : * constructor. Properties added to the instance template are added to
5724 : * each object instance.
5725 : *
5726 : * A FunctionTemplate can have a prototype template. The prototype template
5727 : * is used to create the prototype object of the function.
5728 : *
5729 : * The following example shows how to use a FunctionTemplate:
5730 : *
5731 : * \code
5732 : * v8::Local<v8::FunctionTemplate> t = v8::FunctionTemplate::New(isolate);
5733 : * t->Set(isolate, "func_property", v8::Number::New(isolate, 1));
5734 : *
5735 : * v8::Local<v8::Template> proto_t = t->PrototypeTemplate();
5736 : * proto_t->Set(isolate,
5737 : * "proto_method",
5738 : * v8::FunctionTemplate::New(isolate, InvokeCallback));
5739 : * proto_t->Set(isolate, "proto_const", v8::Number::New(isolate, 2));
5740 : *
5741 : * v8::Local<v8::ObjectTemplate> instance_t = t->InstanceTemplate();
5742 : * instance_t->SetAccessor(String::NewFromUtf8(isolate, "instance_accessor"),
5743 : * InstanceAccessorCallback);
5744 : * instance_t->SetHandler(
5745 : * NamedPropertyHandlerConfiguration(PropertyHandlerCallback));
5746 : * instance_t->Set(String::NewFromUtf8(isolate, "instance_property"),
5747 : * Number::New(isolate, 3));
5748 : *
5749 : * v8::Local<v8::Function> function = t->GetFunction();
5750 : * v8::Local<v8::Object> instance = function->NewInstance();
5751 : * \endcode
5752 : *
5753 : * Let's use "function" as the JS variable name of the function object
5754 : * and "instance" for the instance object created above. The function
5755 : * and the instance will have the following properties:
5756 : *
5757 : * \code
5758 : * func_property in function == true;
5759 : * function.func_property == 1;
5760 : *
5761 : * function.prototype.proto_method() invokes 'InvokeCallback'
5762 : * function.prototype.proto_const == 2;
5763 : *
5764 : * instance instanceof function == true;
5765 : * instance.instance_accessor calls 'InstanceAccessorCallback'
5766 : * instance.instance_property == 3;
5767 : * \endcode
5768 : *
5769 : * A FunctionTemplate can inherit from another one by calling the
5770 : * FunctionTemplate::Inherit method. The following graph illustrates
5771 : * the semantics of inheritance:
5772 : *
5773 : * \code
5774 : * FunctionTemplate Parent -> Parent() . prototype -> { }
5775 : * ^ ^
5776 : * | Inherit(Parent) | .__proto__
5777 : * | |
5778 : * FunctionTemplate Child -> Child() . prototype -> { }
5779 : * \endcode
5780 : *
5781 : * A FunctionTemplate 'Child' inherits from 'Parent', the prototype
5782 : * object of the Child() function has __proto__ pointing to the
5783 : * Parent() function's prototype object. An instance of the Child
5784 : * function has all properties on Parent's instance templates.
5785 : *
5786 : * Let Parent be the FunctionTemplate initialized in the previous
5787 : * section and create a Child FunctionTemplate by:
5788 : *
5789 : * \code
5790 : * Local<FunctionTemplate> parent = t;
5791 : * Local<FunctionTemplate> child = FunctionTemplate::New();
5792 : * child->Inherit(parent);
5793 : *
5794 : * Local<Function> child_function = child->GetFunction();
5795 : * Local<Object> child_instance = child_function->NewInstance();
5796 : * \endcode
5797 : *
5798 : * The Child function and Child instance will have the following
5799 : * properties:
5800 : *
5801 : * \code
5802 : * child_func.prototype.__proto__ == function.prototype;
5803 : * child_instance.instance_accessor calls 'InstanceAccessorCallback'
5804 : * child_instance.instance_property == 3;
5805 : * \endcode
5806 : */
5807 : class V8_EXPORT FunctionTemplate : public Template {
5808 : public:
5809 : /** Creates a function template.*/
5810 : static Local<FunctionTemplate> New(
5811 : Isolate* isolate, FunctionCallback callback = nullptr,
5812 : Local<Value> data = Local<Value>(),
5813 : Local<Signature> signature = Local<Signature>(), int length = 0,
5814 : ConstructorBehavior behavior = ConstructorBehavior::kAllow,
5815 : SideEffectType side_effect_type = SideEffectType::kHasSideEffect);
5816 :
5817 : /** Get a template included in the snapshot by index. */
5818 : static MaybeLocal<FunctionTemplate> FromSnapshot(Isolate* isolate,
5819 : size_t index);
5820 :
5821 : /**
5822 : * Creates a function template backed/cached by a private property.
5823 : */
5824 : static Local<FunctionTemplate> NewWithCache(
5825 : Isolate* isolate, FunctionCallback callback,
5826 : Local<Private> cache_property, Local<Value> data = Local<Value>(),
5827 : Local<Signature> signature = Local<Signature>(), int length = 0,
5828 : SideEffectType side_effect_type = SideEffectType::kHasSideEffect);
5829 :
5830 : /** Returns the unique function instance in the current execution context.*/
5831 : V8_DEPRECATED("Use maybe version", Local<Function> GetFunction());
5832 : V8_WARN_UNUSED_RESULT MaybeLocal<Function> GetFunction(
5833 : Local<Context> context);
5834 :
5835 : /**
5836 : * Similar to Context::NewRemoteContext, this creates an instance that
5837 : * isn't backed by an actual object.
5838 : *
5839 : * The InstanceTemplate of this FunctionTemplate must have access checks with
5840 : * handlers installed.
5841 : */
5842 : V8_WARN_UNUSED_RESULT MaybeLocal<Object> NewRemoteInstance();
5843 :
5844 : /**
5845 : * Set the call-handler callback for a FunctionTemplate. This
5846 : * callback is called whenever the function created from this
5847 : * FunctionTemplate is called.
5848 : */
5849 : void SetCallHandler(
5850 : FunctionCallback callback, Local<Value> data = Local<Value>(),
5851 : SideEffectType side_effect_type = SideEffectType::kHasSideEffect);
5852 :
5853 : /** Set the predefined length property for the FunctionTemplate. */
5854 : void SetLength(int length);
5855 :
5856 : /** Get the InstanceTemplate. */
5857 : Local<ObjectTemplate> InstanceTemplate();
5858 :
5859 : /**
5860 : * Causes the function template to inherit from a parent function template.
5861 : * This means the function's prototype.__proto__ is set to the parent
5862 : * function's prototype.
5863 : **/
5864 : void Inherit(Local<FunctionTemplate> parent);
5865 :
5866 : /**
5867 : * A PrototypeTemplate is the template used to create the prototype object
5868 : * of the function created by this template.
5869 : */
5870 : Local<ObjectTemplate> PrototypeTemplate();
5871 :
5872 : /**
5873 : * A PrototypeProviderTemplate is another function template whose prototype
5874 : * property is used for this template. This is mutually exclusive with setting
5875 : * a prototype template indirectly by calling PrototypeTemplate() or using
5876 : * Inherit().
5877 : **/
5878 : void SetPrototypeProviderTemplate(Local<FunctionTemplate> prototype_provider);
5879 :
5880 : /**
5881 : * Set the class name of the FunctionTemplate. This is used for
5882 : * printing objects created with the function created from the
5883 : * FunctionTemplate as its constructor.
5884 : */
5885 : void SetClassName(Local<String> name);
5886 :
5887 :
5888 : /**
5889 : * When set to true, no access check will be performed on the receiver of a
5890 : * function call. Currently defaults to true, but this is subject to change.
5891 : */
5892 : void SetAcceptAnyReceiver(bool value);
5893 :
5894 : /**
5895 : * Determines whether the __proto__ accessor ignores instances of
5896 : * the function template. If instances of the function template are
5897 : * ignored, __proto__ skips all instances and instead returns the
5898 : * next object in the prototype chain.
5899 : *
5900 : * Call with a value of true to make the __proto__ accessor ignore
5901 : * instances of the function template. Call with a value of false
5902 : * to make the __proto__ accessor not ignore instances of the
5903 : * function template. By default, instances of a function template
5904 : * are not ignored.
5905 : */
5906 : void SetHiddenPrototype(bool value);
5907 :
5908 : /**
5909 : * Sets the ReadOnly flag in the attributes of the 'prototype' property
5910 : * of functions created from this FunctionTemplate to true.
5911 : */
5912 : void ReadOnlyPrototype();
5913 :
5914 : /**
5915 : * Removes the prototype property from functions created from this
5916 : * FunctionTemplate.
5917 : */
5918 : void RemovePrototype();
5919 :
5920 : /**
5921 : * Returns true if the given object is an instance of this function
5922 : * template.
5923 : */
5924 : bool HasInstance(Local<Value> object);
5925 :
5926 : V8_INLINE static FunctionTemplate* Cast(Data* data);
5927 :
5928 : private:
5929 : FunctionTemplate();
5930 :
5931 : static void CheckCast(Data* that);
5932 : friend class Context;
5933 : friend class ObjectTemplate;
5934 : };
5935 :
5936 : /**
5937 : * Configuration flags for v8::NamedPropertyHandlerConfiguration or
5938 : * v8::IndexedPropertyHandlerConfiguration.
5939 : */
5940 : enum class PropertyHandlerFlags {
5941 : /**
5942 : * None.
5943 : */
5944 : kNone = 0,
5945 :
5946 : /**
5947 : * See ALL_CAN_READ above.
5948 : */
5949 : kAllCanRead = 1,
5950 :
5951 : /** Will not call into interceptor for properties on the receiver or prototype
5952 : * chain, i.e., only call into interceptor for properties that do not exist.
5953 : * Currently only valid for named interceptors.
5954 : */
5955 : kNonMasking = 1 << 1,
5956 :
5957 : /**
5958 : * Will not call into interceptor for symbol lookup. Only meaningful for
5959 : * named interceptors.
5960 : */
5961 : kOnlyInterceptStrings = 1 << 2,
5962 :
5963 : /**
5964 : * The getter, query, enumerator callbacks do not produce side effects.
5965 : */
5966 : kHasNoSideEffect = 1 << 3,
5967 : };
5968 :
5969 : struct NamedPropertyHandlerConfiguration {
5970 : NamedPropertyHandlerConfiguration(
5971 : GenericNamedPropertyGetterCallback getter,
5972 : GenericNamedPropertySetterCallback setter,
5973 : GenericNamedPropertyQueryCallback query,
5974 : GenericNamedPropertyDeleterCallback deleter,
5975 : GenericNamedPropertyEnumeratorCallback enumerator,
5976 : GenericNamedPropertyDefinerCallback definer,
5977 : GenericNamedPropertyDescriptorCallback descriptor,
5978 : Local<Value> data = Local<Value>(),
5979 : PropertyHandlerFlags flags = PropertyHandlerFlags::kNone)
5980 : : getter(getter),
5981 : setter(setter),
5982 : query(query),
5983 : deleter(deleter),
5984 : enumerator(enumerator),
5985 : definer(definer),
5986 : descriptor(descriptor),
5987 : data(data),
5988 1 : flags(flags) {}
5989 :
5990 : NamedPropertyHandlerConfiguration(
5991 : /** Note: getter is required */
5992 : GenericNamedPropertyGetterCallback getter = nullptr,
5993 : GenericNamedPropertySetterCallback setter = nullptr,
5994 : GenericNamedPropertyQueryCallback query = nullptr,
5995 : GenericNamedPropertyDeleterCallback deleter = nullptr,
5996 : GenericNamedPropertyEnumeratorCallback enumerator = nullptr,
5997 : Local<Value> data = Local<Value>(),
5998 : PropertyHandlerFlags flags = PropertyHandlerFlags::kNone)
5999 : : getter(getter),
6000 : setter(setter),
6001 : query(query),
6002 : deleter(deleter),
6003 : enumerator(enumerator),
6004 : definer(nullptr),
6005 : descriptor(nullptr),
6006 : data(data),
6007 915 : flags(flags) {}
6008 :
6009 : NamedPropertyHandlerConfiguration(
6010 : GenericNamedPropertyGetterCallback getter,
6011 : GenericNamedPropertySetterCallback setter,
6012 : GenericNamedPropertyDescriptorCallback descriptor,
6013 : GenericNamedPropertyDeleterCallback deleter,
6014 : GenericNamedPropertyEnumeratorCallback enumerator,
6015 : GenericNamedPropertyDefinerCallback definer,
6016 : Local<Value> data = Local<Value>(),
6017 : PropertyHandlerFlags flags = PropertyHandlerFlags::kNone)
6018 : : getter(getter),
6019 : setter(setter),
6020 : query(nullptr),
6021 : deleter(deleter),
6022 : enumerator(enumerator),
6023 : definer(definer),
6024 : descriptor(descriptor),
6025 : data(data),
6026 83 : flags(flags) {}
6027 :
6028 : GenericNamedPropertyGetterCallback getter;
6029 : GenericNamedPropertySetterCallback setter;
6030 : GenericNamedPropertyQueryCallback query;
6031 : GenericNamedPropertyDeleterCallback deleter;
6032 : GenericNamedPropertyEnumeratorCallback enumerator;
6033 : GenericNamedPropertyDefinerCallback definer;
6034 : GenericNamedPropertyDescriptorCallback descriptor;
6035 : Local<Value> data;
6036 : PropertyHandlerFlags flags;
6037 : };
6038 :
6039 :
6040 : struct IndexedPropertyHandlerConfiguration {
6041 : IndexedPropertyHandlerConfiguration(
6042 : IndexedPropertyGetterCallback getter,
6043 : IndexedPropertySetterCallback setter, IndexedPropertyQueryCallback query,
6044 : IndexedPropertyDeleterCallback deleter,
6045 : IndexedPropertyEnumeratorCallback enumerator,
6046 : IndexedPropertyDefinerCallback definer,
6047 : IndexedPropertyDescriptorCallback descriptor,
6048 : Local<Value> data = Local<Value>(),
6049 : PropertyHandlerFlags flags = PropertyHandlerFlags::kNone)
6050 : : getter(getter),
6051 : setter(setter),
6052 : query(query),
6053 : deleter(deleter),
6054 : enumerator(enumerator),
6055 : definer(definer),
6056 : descriptor(descriptor),
6057 : data(data),
6058 1 : flags(flags) {}
6059 :
6060 : IndexedPropertyHandlerConfiguration(
6061 : /** Note: getter is required */
6062 : IndexedPropertyGetterCallback getter = nullptr,
6063 : IndexedPropertySetterCallback setter = nullptr,
6064 : IndexedPropertyQueryCallback query = nullptr,
6065 : IndexedPropertyDeleterCallback deleter = nullptr,
6066 : IndexedPropertyEnumeratorCallback enumerator = nullptr,
6067 : Local<Value> data = Local<Value>(),
6068 : PropertyHandlerFlags flags = PropertyHandlerFlags::kNone)
6069 : : getter(getter),
6070 : setter(setter),
6071 : query(query),
6072 : deleter(deleter),
6073 : enumerator(enumerator),
6074 : definer(nullptr),
6075 : descriptor(nullptr),
6076 : data(data),
6077 188 : flags(flags) {}
6078 :
6079 : IndexedPropertyHandlerConfiguration(
6080 : IndexedPropertyGetterCallback getter,
6081 : IndexedPropertySetterCallback setter,
6082 : IndexedPropertyDescriptorCallback descriptor,
6083 : IndexedPropertyDeleterCallback deleter,
6084 : IndexedPropertyEnumeratorCallback enumerator,
6085 : IndexedPropertyDefinerCallback definer,
6086 : Local<Value> data = Local<Value>(),
6087 : PropertyHandlerFlags flags = PropertyHandlerFlags::kNone)
6088 : : getter(getter),
6089 : setter(setter),
6090 : query(nullptr),
6091 : deleter(deleter),
6092 : enumerator(enumerator),
6093 : definer(definer),
6094 : descriptor(descriptor),
6095 : data(data),
6096 23 : flags(flags) {}
6097 :
6098 : IndexedPropertyGetterCallback getter;
6099 : IndexedPropertySetterCallback setter;
6100 : IndexedPropertyQueryCallback query;
6101 : IndexedPropertyDeleterCallback deleter;
6102 : IndexedPropertyEnumeratorCallback enumerator;
6103 : IndexedPropertyDefinerCallback definer;
6104 : IndexedPropertyDescriptorCallback descriptor;
6105 : Local<Value> data;
6106 : PropertyHandlerFlags flags;
6107 : };
6108 :
6109 :
6110 : /**
6111 : * An ObjectTemplate is used to create objects at runtime.
6112 : *
6113 : * Properties added to an ObjectTemplate are added to each object
6114 : * created from the ObjectTemplate.
6115 : */
6116 : class V8_EXPORT ObjectTemplate : public Template {
6117 : public:
6118 : /** Creates an ObjectTemplate. */
6119 : static Local<ObjectTemplate> New(
6120 : Isolate* isolate,
6121 : Local<FunctionTemplate> constructor = Local<FunctionTemplate>());
6122 :
6123 : /** Get a template included in the snapshot by index. */
6124 : static MaybeLocal<ObjectTemplate> FromSnapshot(Isolate* isolate,
6125 : size_t index);
6126 :
6127 : /** Creates a new instance of this template.*/
6128 : V8_DEPRECATED("Use maybe version", Local<Object> NewInstance());
6129 : V8_WARN_UNUSED_RESULT MaybeLocal<Object> NewInstance(Local<Context> context);
6130 :
6131 : /**
6132 : * Sets an accessor on the object template.
6133 : *
6134 : * Whenever the property with the given name is accessed on objects
6135 : * created from this ObjectTemplate the getter and setter callbacks
6136 : * are called instead of getting and setting the property directly
6137 : * on the JavaScript object.
6138 : *
6139 : * \param name The name of the property for which an accessor is added.
6140 : * \param getter The callback to invoke when getting the property.
6141 : * \param setter The callback to invoke when setting the property.
6142 : * \param data A piece of data that will be passed to the getter and setter
6143 : * callbacks whenever they are invoked.
6144 : * \param settings Access control settings for the accessor. This is a bit
6145 : * field consisting of one of more of
6146 : * DEFAULT = 0, ALL_CAN_READ = 1, or ALL_CAN_WRITE = 2.
6147 : * The default is to not allow cross-context access.
6148 : * ALL_CAN_READ means that all cross-context reads are allowed.
6149 : * ALL_CAN_WRITE means that all cross-context writes are allowed.
6150 : * The combination ALL_CAN_READ | ALL_CAN_WRITE can be used to allow all
6151 : * cross-context access.
6152 : * \param attribute The attributes of the property for which an accessor
6153 : * is added.
6154 : * \param signature The signature describes valid receivers for the accessor
6155 : * and is used to perform implicit instance checks against them. If the
6156 : * receiver is incompatible (i.e. is not an instance of the constructor as
6157 : * defined by FunctionTemplate::HasInstance()), an implicit TypeError is
6158 : * thrown and no callback is invoked.
6159 : */
6160 : void SetAccessor(
6161 : Local<String> name, AccessorGetterCallback getter,
6162 : AccessorSetterCallback setter = nullptr,
6163 : Local<Value> data = Local<Value>(), AccessControl settings = DEFAULT,
6164 : PropertyAttribute attribute = None,
6165 : Local<AccessorSignature> signature = Local<AccessorSignature>(),
6166 : SideEffectType getter_side_effect_type = SideEffectType::kHasSideEffect,
6167 : SideEffectType setter_side_effect_type = SideEffectType::kHasSideEffect);
6168 : void SetAccessor(
6169 : Local<Name> name, AccessorNameGetterCallback getter,
6170 : AccessorNameSetterCallback setter = nullptr,
6171 : Local<Value> data = Local<Value>(), AccessControl settings = DEFAULT,
6172 : PropertyAttribute attribute = None,
6173 : Local<AccessorSignature> signature = Local<AccessorSignature>(),
6174 : SideEffectType getter_side_effect_type = SideEffectType::kHasSideEffect,
6175 : SideEffectType setter_side_effect_type = SideEffectType::kHasSideEffect);
6176 :
6177 : /**
6178 : * Sets a named property handler on the object template.
6179 : *
6180 : * Whenever a property whose name is a string or a symbol is accessed on
6181 : * objects created from this object template, the provided callback is
6182 : * invoked instead of accessing the property directly on the JavaScript
6183 : * object.
6184 : *
6185 : * @param configuration The NamedPropertyHandlerConfiguration that defines the
6186 : * callbacks to invoke when accessing a property.
6187 : */
6188 : void SetHandler(const NamedPropertyHandlerConfiguration& configuration);
6189 :
6190 : /**
6191 : * Sets an indexed property handler on the object template.
6192 : *
6193 : * Whenever an indexed property is accessed on objects created from
6194 : * this object template, the provided callback is invoked instead of
6195 : * accessing the property directly on the JavaScript object.
6196 : *
6197 : * \param getter The callback to invoke when getting a property.
6198 : * \param setter The callback to invoke when setting a property.
6199 : * \param query The callback to invoke to check if an object has a property.
6200 : * \param deleter The callback to invoke when deleting a property.
6201 : * \param enumerator The callback to invoke to enumerate all the indexed
6202 : * properties of an object.
6203 : * \param data A piece of data that will be passed to the callbacks
6204 : * whenever they are invoked.
6205 : */
6206 : // TODO(dcarney): deprecate
6207 : void SetIndexedPropertyHandler(
6208 : IndexedPropertyGetterCallback getter,
6209 : IndexedPropertySetterCallback setter = nullptr,
6210 : IndexedPropertyQueryCallback query = nullptr,
6211 : IndexedPropertyDeleterCallback deleter = nullptr,
6212 : IndexedPropertyEnumeratorCallback enumerator = nullptr,
6213 : Local<Value> data = Local<Value>()) {
6214 : SetHandler(IndexedPropertyHandlerConfiguration(getter, setter, query,
6215 : deleter, enumerator, data));
6216 : }
6217 :
6218 : /**
6219 : * Sets an indexed property handler on the object template.
6220 : *
6221 : * Whenever an indexed property is accessed on objects created from
6222 : * this object template, the provided callback is invoked instead of
6223 : * accessing the property directly on the JavaScript object.
6224 : *
6225 : * @param configuration The IndexedPropertyHandlerConfiguration that defines
6226 : * the callbacks to invoke when accessing a property.
6227 : */
6228 : void SetHandler(const IndexedPropertyHandlerConfiguration& configuration);
6229 :
6230 : /**
6231 : * Sets the callback to be used when calling instances created from
6232 : * this template as a function. If no callback is set, instances
6233 : * behave like normal JavaScript objects that cannot be called as a
6234 : * function.
6235 : */
6236 : void SetCallAsFunctionHandler(FunctionCallback callback,
6237 : Local<Value> data = Local<Value>());
6238 :
6239 : /**
6240 : * Mark object instances of the template as undetectable.
6241 : *
6242 : * In many ways, undetectable objects behave as though they are not
6243 : * there. They behave like 'undefined' in conditionals and when
6244 : * printed. However, properties can be accessed and called as on
6245 : * normal objects.
6246 : */
6247 : void MarkAsUndetectable();
6248 :
6249 : /**
6250 : * Sets access check callback on the object template and enables access
6251 : * checks.
6252 : *
6253 : * When accessing properties on instances of this object template,
6254 : * the access check callback will be called to determine whether or
6255 : * not to allow cross-context access to the properties.
6256 : */
6257 : void SetAccessCheckCallback(AccessCheckCallback callback,
6258 : Local<Value> data = Local<Value>());
6259 :
6260 : /**
6261 : * Like SetAccessCheckCallback but invokes an interceptor on failed access
6262 : * checks instead of looking up all-can-read properties. You can only use
6263 : * either this method or SetAccessCheckCallback, but not both at the same
6264 : * time.
6265 : */
6266 : void SetAccessCheckCallbackAndHandler(
6267 : AccessCheckCallback callback,
6268 : const NamedPropertyHandlerConfiguration& named_handler,
6269 : const IndexedPropertyHandlerConfiguration& indexed_handler,
6270 : Local<Value> data = Local<Value>());
6271 :
6272 : /**
6273 : * Gets the number of internal fields for objects generated from
6274 : * this template.
6275 : */
6276 : int InternalFieldCount();
6277 :
6278 : /**
6279 : * Sets the number of internal fields for objects generated from
6280 : * this template.
6281 : */
6282 : void SetInternalFieldCount(int value);
6283 :
6284 : /**
6285 : * Returns true if the object will be an immutable prototype exotic object.
6286 : */
6287 : bool IsImmutableProto();
6288 :
6289 : /**
6290 : * Makes the ObjectTemplate for an immutable prototype exotic object, with an
6291 : * immutable __proto__.
6292 : */
6293 : void SetImmutableProto();
6294 :
6295 : V8_INLINE static ObjectTemplate* Cast(Data* data);
6296 :
6297 : private:
6298 : ObjectTemplate();
6299 : static Local<ObjectTemplate> New(internal::Isolate* isolate,
6300 : Local<FunctionTemplate> constructor);
6301 : static void CheckCast(Data* that);
6302 : friend class FunctionTemplate;
6303 : };
6304 :
6305 : /**
6306 : * A Signature specifies which receiver is valid for a function.
6307 : *
6308 : * A receiver matches a given signature if the receiver (or any of its
6309 : * hidden prototypes) was created from the signature's FunctionTemplate, or
6310 : * from a FunctionTemplate that inherits directly or indirectly from the
6311 : * signature's FunctionTemplate.
6312 : */
6313 : class V8_EXPORT Signature : public Data {
6314 : public:
6315 : static Local<Signature> New(
6316 : Isolate* isolate,
6317 : Local<FunctionTemplate> receiver = Local<FunctionTemplate>());
6318 :
6319 : V8_INLINE static Signature* Cast(Data* data);
6320 :
6321 : private:
6322 : Signature();
6323 :
6324 : static void CheckCast(Data* that);
6325 : };
6326 :
6327 :
6328 : /**
6329 : * An AccessorSignature specifies which receivers are valid parameters
6330 : * to an accessor callback.
6331 : */
6332 : class V8_EXPORT AccessorSignature : public Data {
6333 : public:
6334 : static Local<AccessorSignature> New(
6335 : Isolate* isolate,
6336 : Local<FunctionTemplate> receiver = Local<FunctionTemplate>());
6337 :
6338 : V8_INLINE static AccessorSignature* Cast(Data* data);
6339 :
6340 : private:
6341 : AccessorSignature();
6342 :
6343 : static void CheckCast(Data* that);
6344 : };
6345 :
6346 :
6347 : // --- Extensions ---
6348 : V8_DEPRECATED("Implementation detail", class)
6349 0 : V8_EXPORT ExternalOneByteStringResourceImpl
6350 : : public String::ExternalOneByteStringResource {
6351 : public:
6352 : ExternalOneByteStringResourceImpl() : data_(nullptr), length_(0) {}
6353 : ExternalOneByteStringResourceImpl(const char* data, size_t length)
6354 : : data_(data), length_(length) {}
6355 0 : const char* data() const override { return data_; }
6356 0 : size_t length() const override { return length_; }
6357 :
6358 : private:
6359 : const char* data_;
6360 : size_t length_;
6361 : };
6362 :
6363 : /**
6364 : * Ignore
6365 : */
6366 : class V8_EXPORT Extension { // NOLINT
6367 : public:
6368 : // Note that the strings passed into this constructor must live as long
6369 : // as the Extension itself.
6370 : Extension(const char* name, const char* source = nullptr, int dep_count = 0,
6371 : const char** deps = nullptr, int source_length = -1);
6372 275994 : virtual ~Extension() { delete source_; }
6373 0 : virtual Local<FunctionTemplate> GetNativeFunctionTemplate(
6374 : Isolate* isolate, Local<String> name) {
6375 0 : return Local<FunctionTemplate>();
6376 : }
6377 :
6378 : const char* name() const { return name_; }
6379 : size_t source_length() const { return source_length_; }
6380 : const String::ExternalOneByteStringResource* source() const {
6381 : return source_;
6382 : }
6383 : int dependency_count() { return dep_count_; }
6384 : const char** dependencies() { return deps_; }
6385 10 : void set_auto_enable(bool value) { auto_enable_ = value; }
6386 : bool auto_enable() { return auto_enable_; }
6387 :
6388 : // Disallow copying and assigning.
6389 : Extension(const Extension&) = delete;
6390 : void operator=(const Extension&) = delete;
6391 :
6392 : private:
6393 : const char* name_;
6394 : size_t source_length_; // expected to initialize before source_
6395 : String::ExternalOneByteStringResource* source_;
6396 : int dep_count_;
6397 : const char** deps_;
6398 : bool auto_enable_;
6399 : };
6400 :
6401 :
6402 : void V8_EXPORT RegisterExtension(Extension* extension);
6403 :
6404 :
6405 : // --- Statics ---
6406 :
6407 : V8_INLINE Local<Primitive> Undefined(Isolate* isolate);
6408 : V8_INLINE Local<Primitive> Null(Isolate* isolate);
6409 : V8_INLINE Local<Boolean> True(Isolate* isolate);
6410 : V8_INLINE Local<Boolean> False(Isolate* isolate);
6411 :
6412 : /**
6413 : * A set of constraints that specifies the limits of the runtime's memory use.
6414 : * You must set the heap size before initializing the VM - the size cannot be
6415 : * adjusted after the VM is initialized.
6416 : *
6417 : * If you are using threads then you should hold the V8::Locker lock while
6418 : * setting the stack limit and you must set a non-default stack limit separately
6419 : * for each thread.
6420 : *
6421 : * The arguments for set_max_semi_space_size, set_max_old_space_size,
6422 : * set_max_executable_size, set_code_range_size specify limits in MB.
6423 : *
6424 : * The argument for set_max_semi_space_size_in_kb is in KB.
6425 : */
6426 : class V8_EXPORT ResourceConstraints {
6427 : public:
6428 : ResourceConstraints();
6429 :
6430 : /**
6431 : * Configures the constraints with reasonable default values based on the
6432 : * capabilities of the current device the VM is running on.
6433 : *
6434 : * \param physical_memory The total amount of physical memory on the current
6435 : * device, in bytes.
6436 : * \param virtual_memory_limit The amount of virtual memory on the current
6437 : * device, in bytes, or zero, if there is no limit.
6438 : */
6439 : void ConfigureDefaults(uint64_t physical_memory,
6440 : uint64_t virtual_memory_limit);
6441 :
6442 : // Returns the max semi-space size in KB.
6443 : size_t max_semi_space_size_in_kb() const {
6444 : return max_semi_space_size_in_kb_;
6445 : }
6446 :
6447 : // Sets the max semi-space size in KB.
6448 : void set_max_semi_space_size_in_kb(size_t limit_in_kb) {
6449 28784 : max_semi_space_size_in_kb_ = limit_in_kb;
6450 : }
6451 :
6452 : size_t max_old_space_size() const { return max_old_space_size_; }
6453 : void set_max_old_space_size(size_t limit_in_mb) {
6454 28788 : max_old_space_size_ = limit_in_mb;
6455 : }
6456 : uint32_t* stack_limit() const { return stack_limit_; }
6457 : // Sets an address beyond which the VM's stack may not grow.
6458 : void set_stack_limit(uint32_t* value) { stack_limit_ = value; }
6459 : size_t code_range_size() const { return code_range_size_; }
6460 : void set_code_range_size(size_t limit_in_mb) {
6461 0 : code_range_size_ = limit_in_mb;
6462 : }
6463 : size_t max_zone_pool_size() const { return max_zone_pool_size_; }
6464 28773 : void set_max_zone_pool_size(size_t bytes) { max_zone_pool_size_ = bytes; }
6465 :
6466 : private:
6467 : // max_semi_space_size_ is in KB
6468 : size_t max_semi_space_size_in_kb_;
6469 :
6470 : // The remaining limits are in MB
6471 : size_t max_old_space_size_;
6472 : uint32_t* stack_limit_;
6473 : size_t code_range_size_;
6474 : size_t max_zone_pool_size_;
6475 : };
6476 :
6477 :
6478 : // --- Exceptions ---
6479 :
6480 :
6481 : typedef void (*FatalErrorCallback)(const char* location, const char* message);
6482 :
6483 : typedef void (*OOMErrorCallback)(const char* location, bool is_heap_oom);
6484 :
6485 : typedef void (*DcheckErrorCallback)(const char* file, int line,
6486 : const char* message);
6487 :
6488 : typedef void (*MessageCallback)(Local<Message> message, Local<Value> data);
6489 :
6490 : // --- Tracing ---
6491 :
6492 : typedef void (*LogEventCallback)(const char* name, int event);
6493 :
6494 : /**
6495 : * Create new error objects by calling the corresponding error object
6496 : * constructor with the message.
6497 : */
6498 : class V8_EXPORT Exception {
6499 : public:
6500 : static Local<Value> RangeError(Local<String> message);
6501 : static Local<Value> ReferenceError(Local<String> message);
6502 : static Local<Value> SyntaxError(Local<String> message);
6503 : static Local<Value> TypeError(Local<String> message);
6504 : static Local<Value> Error(Local<String> message);
6505 :
6506 : /**
6507 : * Creates an error message for the given exception.
6508 : * Will try to reconstruct the original stack trace from the exception value,
6509 : * or capture the current stack trace if not available.
6510 : */
6511 : static Local<Message> CreateMessage(Isolate* isolate, Local<Value> exception);
6512 :
6513 : /**
6514 : * Returns the original stack trace that was captured at the creation time
6515 : * of a given exception, or an empty handle if not available.
6516 : */
6517 : static Local<StackTrace> GetStackTrace(Local<Value> exception);
6518 : };
6519 :
6520 :
6521 : // --- Counters Callbacks ---
6522 :
6523 : typedef int* (*CounterLookupCallback)(const char* name);
6524 :
6525 : typedef void* (*CreateHistogramCallback)(const char* name,
6526 : int min,
6527 : int max,
6528 : size_t buckets);
6529 :
6530 : typedef void (*AddHistogramSampleCallback)(void* histogram, int sample);
6531 :
6532 : // --- Enter/Leave Script Callback ---
6533 : typedef void (*BeforeCallEnteredCallback)(Isolate*);
6534 : typedef void (*CallCompletedCallback)(Isolate*);
6535 :
6536 : /**
6537 : * HostImportModuleDynamicallyCallback is called when we require the
6538 : * embedder to load a module. This is used as part of the dynamic
6539 : * import syntax.
6540 : *
6541 : * The referrer contains metadata about the script/module that calls
6542 : * import.
6543 : *
6544 : * The specifier is the name of the module that should be imported.
6545 : *
6546 : * The embedder must compile, instantiate, evaluate the Module, and
6547 : * obtain it's namespace object.
6548 : *
6549 : * The Promise returned from this function is forwarded to userland
6550 : * JavaScript. The embedder must resolve this promise with the module
6551 : * namespace object. In case of an exception, the embedder must reject
6552 : * this promise with the exception. If the promise creation itself
6553 : * fails (e.g. due to stack overflow), the embedder must propagate
6554 : * that exception by returning an empty MaybeLocal.
6555 : */
6556 : typedef MaybeLocal<Promise> (*HostImportModuleDynamicallyCallback)(
6557 : Local<Context> context, Local<ScriptOrModule> referrer,
6558 : Local<String> specifier);
6559 :
6560 : /**
6561 : * HostInitializeImportMetaObjectCallback is called the first time import.meta
6562 : * is accessed for a module. Subsequent access will reuse the same value.
6563 : *
6564 : * The method combines two implementation-defined abstract operations into one:
6565 : * HostGetImportMetaProperties and HostFinalizeImportMeta.
6566 : *
6567 : * The embedder should use v8::Object::CreateDataProperty to add properties on
6568 : * the meta object.
6569 : */
6570 : typedef void (*HostInitializeImportMetaObjectCallback)(Local<Context> context,
6571 : Local<Module> module,
6572 : Local<Object> meta);
6573 :
6574 : /**
6575 : * PrepareStackTraceCallback is called when the stack property of an error is
6576 : * first accessed. The return value will be used as the stack value. If this
6577 : * callback is registed, the |Error.prepareStackTrace| API will be disabled.
6578 : * |sites| is an array of call sites, specified in
6579 : * https://github.com/v8/v8/wiki/Stack-Trace-API
6580 : */
6581 : typedef MaybeLocal<Value> (*PrepareStackTraceCallback)(Local<Context> context,
6582 : Local<Value> error,
6583 : Local<Array> sites);
6584 :
6585 : /**
6586 : * PromiseHook with type kInit is called when a new promise is
6587 : * created. When a new promise is created as part of the chain in the
6588 : * case of Promise.then or in the intermediate promises created by
6589 : * Promise.{race, all}/AsyncFunctionAwait, we pass the parent promise
6590 : * otherwise we pass undefined.
6591 : *
6592 : * PromiseHook with type kResolve is called at the beginning of
6593 : * resolve or reject function defined by CreateResolvingFunctions.
6594 : *
6595 : * PromiseHook with type kBefore is called at the beginning of the
6596 : * PromiseReactionJob.
6597 : *
6598 : * PromiseHook with type kAfter is called right at the end of the
6599 : * PromiseReactionJob.
6600 : */
6601 : enum class PromiseHookType { kInit, kResolve, kBefore, kAfter };
6602 :
6603 : typedef void (*PromiseHook)(PromiseHookType type, Local<Promise> promise,
6604 : Local<Value> parent);
6605 :
6606 : // --- Promise Reject Callback ---
6607 : enum PromiseRejectEvent {
6608 : kPromiseRejectWithNoHandler = 0,
6609 : kPromiseHandlerAddedAfterReject = 1,
6610 : kPromiseRejectAfterResolved = 2,
6611 : kPromiseResolveAfterResolved = 3,
6612 : };
6613 :
6614 : class PromiseRejectMessage {
6615 : public:
6616 : PromiseRejectMessage(Local<Promise> promise, PromiseRejectEvent event,
6617 : Local<Value> value, Local<StackTrace> stack_trace)
6618 : : promise_(promise),
6619 : event_(event),
6620 : value_(value),
6621 490 : stack_trace_(stack_trace) {}
6622 :
6623 : V8_INLINE Local<Promise> GetPromise() const { return promise_; }
6624 : V8_INLINE PromiseRejectEvent GetEvent() const { return event_; }
6625 : V8_INLINE Local<Value> GetValue() const { return value_; }
6626 :
6627 : private:
6628 : Local<Promise> promise_;
6629 : PromiseRejectEvent event_;
6630 : Local<Value> value_;
6631 : Local<StackTrace> stack_trace_;
6632 : };
6633 :
6634 : typedef void (*PromiseRejectCallback)(PromiseRejectMessage message);
6635 :
6636 : // --- Microtasks Callbacks ---
6637 : typedef void (*MicrotasksCompletedCallback)(Isolate*);
6638 : typedef void (*MicrotaskCallback)(void* data);
6639 :
6640 :
6641 : /**
6642 : * Policy for running microtasks:
6643 : * - explicit: microtasks are invoked with Isolate::RunMicrotasks() method;
6644 : * - scoped: microtasks invocation is controlled by MicrotasksScope objects;
6645 : * - auto: microtasks are invoked when the script call depth decrements
6646 : * to zero.
6647 : */
6648 : enum class MicrotasksPolicy { kExplicit, kScoped, kAuto };
6649 :
6650 :
6651 : /**
6652 : * This scope is used to control microtasks when kScopeMicrotasksInvocation
6653 : * is used on Isolate. In this mode every non-primitive call to V8 should be
6654 : * done inside some MicrotasksScope.
6655 : * Microtasks are executed when topmost MicrotasksScope marked as kRunMicrotasks
6656 : * exits.
6657 : * kDoNotRunMicrotasks should be used to annotate calls not intended to trigger
6658 : * microtasks.
6659 : */
6660 : class V8_EXPORT MicrotasksScope {
6661 : public:
6662 : enum Type { kRunMicrotasks, kDoNotRunMicrotasks };
6663 :
6664 : MicrotasksScope(Isolate* isolate, Type type);
6665 : ~MicrotasksScope();
6666 :
6667 : /**
6668 : * Runs microtasks if no kRunMicrotasks scope is currently active.
6669 : */
6670 : static void PerformCheckpoint(Isolate* isolate);
6671 :
6672 : /**
6673 : * Returns current depth of nested kRunMicrotasks scopes.
6674 : */
6675 : static int GetCurrentDepth(Isolate* isolate);
6676 :
6677 : /**
6678 : * Returns true while microtasks are being executed.
6679 : */
6680 : static bool IsRunningMicrotasks(Isolate* isolate);
6681 :
6682 : // Prevent copying.
6683 : MicrotasksScope(const MicrotasksScope&) = delete;
6684 : MicrotasksScope& operator=(const MicrotasksScope&) = delete;
6685 :
6686 : private:
6687 : internal::Isolate* const isolate_;
6688 : bool run_;
6689 : };
6690 :
6691 :
6692 : // --- Failed Access Check Callback ---
6693 : typedef void (*FailedAccessCheckCallback)(Local<Object> target,
6694 : AccessType type,
6695 : Local<Value> data);
6696 :
6697 : // --- AllowCodeGenerationFromStrings callbacks ---
6698 :
6699 : /**
6700 : * Callback to check if code generation from strings is allowed. See
6701 : * Context::AllowCodeGenerationFromStrings.
6702 : */
6703 : typedef bool (*AllowCodeGenerationFromStringsCallback)(Local<Context> context,
6704 : Local<String> source);
6705 :
6706 : // --- WebAssembly compilation callbacks ---
6707 : typedef bool (*ExtensionCallback)(const FunctionCallbackInfo<Value>&);
6708 :
6709 : typedef bool (*AllowWasmCodeGenerationCallback)(Local<Context> context,
6710 : Local<String> source);
6711 :
6712 : // --- Callback for APIs defined on v8-supported objects, but implemented
6713 : // by the embedder. Example: WebAssembly.{compile|instantiate}Streaming ---
6714 : typedef void (*ApiImplementationCallback)(const FunctionCallbackInfo<Value>&);
6715 :
6716 : // --- Callback for WebAssembly.compileStreaming ---
6717 : typedef void (*WasmStreamingCallback)(const FunctionCallbackInfo<Value>&);
6718 :
6719 : // --- Callback for checking if WebAssembly threads are enabled ---
6720 : typedef bool (*WasmThreadsEnabledCallback)(Local<Context> context);
6721 :
6722 : // --- Garbage Collection Callbacks ---
6723 :
6724 : /**
6725 : * Applications can register callback functions which will be called before and
6726 : * after certain garbage collection operations. Allocations are not allowed in
6727 : * the callback functions, you therefore cannot manipulate objects (set or
6728 : * delete properties for example) since it is possible such operations will
6729 : * result in the allocation of objects.
6730 : */
6731 : enum GCType {
6732 : kGCTypeScavenge = 1 << 0,
6733 : kGCTypeMarkSweepCompact = 1 << 1,
6734 : kGCTypeIncrementalMarking = 1 << 2,
6735 : kGCTypeProcessWeakCallbacks = 1 << 3,
6736 : kGCTypeAll = kGCTypeScavenge | kGCTypeMarkSweepCompact |
6737 : kGCTypeIncrementalMarking | kGCTypeProcessWeakCallbacks
6738 : };
6739 :
6740 : /**
6741 : * GCCallbackFlags is used to notify additional information about the GC
6742 : * callback.
6743 : * - kGCCallbackFlagConstructRetainedObjectInfos: The GC callback is for
6744 : * constructing retained object infos.
6745 : * - kGCCallbackFlagForced: The GC callback is for a forced GC for testing.
6746 : * - kGCCallbackFlagSynchronousPhantomCallbackProcessing: The GC callback
6747 : * is called synchronously without getting posted to an idle task.
6748 : * - kGCCallbackFlagCollectAllAvailableGarbage: The GC callback is called
6749 : * in a phase where V8 is trying to collect all available garbage
6750 : * (e.g., handling a low memory notification).
6751 : * - kGCCallbackScheduleIdleGarbageCollection: The GC callback is called to
6752 : * trigger an idle garbage collection.
6753 : */
6754 : enum GCCallbackFlags {
6755 : kNoGCCallbackFlags = 0,
6756 : kGCCallbackFlagConstructRetainedObjectInfos = 1 << 1,
6757 : kGCCallbackFlagForced = 1 << 2,
6758 : kGCCallbackFlagSynchronousPhantomCallbackProcessing = 1 << 3,
6759 : kGCCallbackFlagCollectAllAvailableGarbage = 1 << 4,
6760 : kGCCallbackFlagCollectAllExternalMemory = 1 << 5,
6761 : kGCCallbackScheduleIdleGarbageCollection = 1 << 6,
6762 : };
6763 :
6764 : typedef void (*GCCallback)(GCType type, GCCallbackFlags flags);
6765 :
6766 : typedef void (*InterruptCallback)(Isolate* isolate, void* data);
6767 :
6768 : /**
6769 : * This callback is invoked when the heap size is close to the heap limit and
6770 : * V8 is likely to abort with out-of-memory error.
6771 : * The callback can extend the heap limit by returning a value that is greater
6772 : * than the current_heap_limit. The initial heap limit is the limit that was
6773 : * set after heap setup.
6774 : */
6775 : typedef size_t (*NearHeapLimitCallback)(void* data, size_t current_heap_limit,
6776 : size_t initial_heap_limit);
6777 :
6778 : /**
6779 : * Collection of V8 heap information.
6780 : *
6781 : * Instances of this class can be passed to v8::V8::HeapStatistics to
6782 : * get heap statistics from V8.
6783 : */
6784 : class V8_EXPORT HeapStatistics {
6785 : public:
6786 : HeapStatistics();
6787 : size_t total_heap_size() { return total_heap_size_; }
6788 : size_t total_heap_size_executable() { return total_heap_size_executable_; }
6789 : size_t total_physical_size() { return total_physical_size_; }
6790 : size_t total_available_size() { return total_available_size_; }
6791 : size_t used_heap_size() { return used_heap_size_; }
6792 : size_t heap_size_limit() { return heap_size_limit_; }
6793 : size_t malloced_memory() { return malloced_memory_; }
6794 : size_t external_memory() { return external_memory_; }
6795 : size_t peak_malloced_memory() { return peak_malloced_memory_; }
6796 : size_t number_of_native_contexts() { return number_of_native_contexts_; }
6797 : size_t number_of_detached_contexts() { return number_of_detached_contexts_; }
6798 :
6799 : /**
6800 : * Returns a 0/1 boolean, which signifies whether the V8 overwrite heap
6801 : * garbage with a bit pattern.
6802 : */
6803 : size_t does_zap_garbage() { return does_zap_garbage_; }
6804 :
6805 : private:
6806 : size_t total_heap_size_;
6807 : size_t total_heap_size_executable_;
6808 : size_t total_physical_size_;
6809 : size_t total_available_size_;
6810 : size_t used_heap_size_;
6811 : size_t heap_size_limit_;
6812 : size_t malloced_memory_;
6813 : size_t external_memory_;
6814 : size_t peak_malloced_memory_;
6815 : bool does_zap_garbage_;
6816 : size_t number_of_native_contexts_;
6817 : size_t number_of_detached_contexts_;
6818 :
6819 : friend class V8;
6820 : friend class Isolate;
6821 : };
6822 :
6823 :
6824 : class V8_EXPORT HeapSpaceStatistics {
6825 : public:
6826 : HeapSpaceStatistics();
6827 : const char* space_name() { return space_name_; }
6828 : size_t space_size() { return space_size_; }
6829 : size_t space_used_size() { return space_used_size_; }
6830 : size_t space_available_size() { return space_available_size_; }
6831 : size_t physical_space_size() { return physical_space_size_; }
6832 :
6833 : private:
6834 : const char* space_name_;
6835 : size_t space_size_;
6836 : size_t space_used_size_;
6837 : size_t space_available_size_;
6838 : size_t physical_space_size_;
6839 :
6840 : friend class Isolate;
6841 : };
6842 :
6843 :
6844 : class V8_EXPORT HeapObjectStatistics {
6845 : public:
6846 : HeapObjectStatistics();
6847 : const char* object_type() { return object_type_; }
6848 : const char* object_sub_type() { return object_sub_type_; }
6849 : size_t object_count() { return object_count_; }
6850 : size_t object_size() { return object_size_; }
6851 :
6852 : private:
6853 : const char* object_type_;
6854 : const char* object_sub_type_;
6855 : size_t object_count_;
6856 : size_t object_size_;
6857 :
6858 : friend class Isolate;
6859 : };
6860 :
6861 : class V8_EXPORT HeapCodeStatistics {
6862 : public:
6863 : HeapCodeStatistics();
6864 : size_t code_and_metadata_size() { return code_and_metadata_size_; }
6865 : size_t bytecode_and_metadata_size() { return bytecode_and_metadata_size_; }
6866 : size_t external_script_source_size() { return external_script_source_size_; }
6867 :
6868 : private:
6869 : size_t code_and_metadata_size_;
6870 : size_t bytecode_and_metadata_size_;
6871 : size_t external_script_source_size_;
6872 :
6873 : friend class Isolate;
6874 : };
6875 :
6876 : class RetainedObjectInfo;
6877 :
6878 : /**
6879 : * A JIT code event is issued each time code is added, moved or removed.
6880 : *
6881 : * \note removal events are not currently issued.
6882 : */
6883 : struct JitCodeEvent {
6884 : enum EventType {
6885 : CODE_ADDED,
6886 : CODE_MOVED,
6887 : CODE_REMOVED,
6888 : CODE_ADD_LINE_POS_INFO,
6889 : CODE_START_LINE_INFO_RECORDING,
6890 : CODE_END_LINE_INFO_RECORDING
6891 : };
6892 : // Definition of the code position type. The "POSITION" type means the place
6893 : // in the source code which are of interest when making stack traces to
6894 : // pin-point the source location of a stack frame as close as possible.
6895 : // The "STATEMENT_POSITION" means the place at the beginning of each
6896 : // statement, and is used to indicate possible break locations.
6897 : enum PositionType { POSITION, STATEMENT_POSITION };
6898 :
6899 : // There are two different kinds of JitCodeEvents, one for JIT code generated
6900 : // by the optimizing compiler, and one for byte code generated for the
6901 : // interpreter. For JIT_CODE events, the |code_start| member of the event
6902 : // points to the beginning of jitted assembly code, while for BYTE_CODE
6903 : // events, |code_start| points to the first bytecode of the interpreted
6904 : // function.
6905 : enum CodeType { BYTE_CODE, JIT_CODE };
6906 :
6907 : // Type of event.
6908 : EventType type;
6909 : CodeType code_type;
6910 : // Start of the instructions.
6911 : void* code_start;
6912 : // Size of the instructions.
6913 : size_t code_len;
6914 : // Script info for CODE_ADDED event.
6915 : Local<UnboundScript> script;
6916 : // User-defined data for *_LINE_INFO_* event. It's used to hold the source
6917 : // code line information which is returned from the
6918 : // CODE_START_LINE_INFO_RECORDING event. And it's passed to subsequent
6919 : // CODE_ADD_LINE_POS_INFO and CODE_END_LINE_INFO_RECORDING events.
6920 : void* user_data;
6921 :
6922 : struct name_t {
6923 : // Name of the object associated with the code, note that the string is not
6924 : // zero-terminated.
6925 : const char* str;
6926 : // Number of chars in str.
6927 : size_t len;
6928 : };
6929 :
6930 : struct line_info_t {
6931 : // PC offset
6932 : size_t offset;
6933 : // Code position
6934 : size_t pos;
6935 : // The position type.
6936 : PositionType position_type;
6937 : };
6938 :
6939 : union {
6940 : // Only valid for CODE_ADDED.
6941 : struct name_t name;
6942 :
6943 : // Only valid for CODE_ADD_LINE_POS_INFO
6944 : struct line_info_t line_info;
6945 :
6946 : // New location of instructions. Only valid for CODE_MOVED.
6947 : void* new_code_start;
6948 : };
6949 :
6950 : Isolate* isolate;
6951 : };
6952 :
6953 : /**
6954 : * Option flags passed to the SetRAILMode function.
6955 : * See documentation https://developers.google.com/web/tools/chrome-devtools/
6956 : * profile/evaluate-performance/rail
6957 : */
6958 : enum RAILMode {
6959 : // Response performance mode: In this mode very low virtual machine latency
6960 : // is provided. V8 will try to avoid JavaScript execution interruptions.
6961 : // Throughput may be throttled.
6962 : PERFORMANCE_RESPONSE,
6963 : // Animation performance mode: In this mode low virtual machine latency is
6964 : // provided. V8 will try to avoid as many JavaScript execution interruptions
6965 : // as possible. Throughput may be throttled. This is the default mode.
6966 : PERFORMANCE_ANIMATION,
6967 : // Idle performance mode: The embedder is idle. V8 can complete deferred work
6968 : // in this mode.
6969 : PERFORMANCE_IDLE,
6970 : // Load performance mode: In this mode high throughput is provided. V8 may
6971 : // turn off latency optimizations.
6972 : PERFORMANCE_LOAD
6973 : };
6974 :
6975 : /**
6976 : * Option flags passed to the SetJitCodeEventHandler function.
6977 : */
6978 : enum JitCodeEventOptions {
6979 : kJitCodeEventDefault = 0,
6980 : // Generate callbacks for already existent code.
6981 : kJitCodeEventEnumExisting = 1
6982 : };
6983 :
6984 :
6985 : /**
6986 : * Callback function passed to SetJitCodeEventHandler.
6987 : *
6988 : * \param event code add, move or removal event.
6989 : */
6990 : typedef void (*JitCodeEventHandler)(const JitCodeEvent* event);
6991 :
6992 :
6993 : /**
6994 : * Interface for iterating through all external resources in the heap.
6995 : */
6996 5 : class V8_EXPORT ExternalResourceVisitor { // NOLINT
6997 : public:
6998 5 : virtual ~ExternalResourceVisitor() = default;
6999 0 : virtual void VisitExternalString(Local<String> string) {}
7000 : };
7001 :
7002 :
7003 : /**
7004 : * Interface for iterating through all the persistent handles in the heap.
7005 : */
7006 379 : class V8_EXPORT PersistentHandleVisitor { // NOLINT
7007 : public:
7008 374 : virtual ~PersistentHandleVisitor() = default;
7009 0 : virtual void VisitPersistentHandle(Persistent<Value>* value,
7010 0 : uint16_t class_id) {}
7011 : };
7012 :
7013 : /**
7014 : * Memory pressure level for the MemoryPressureNotification.
7015 : * kNone hints V8 that there is no memory pressure.
7016 : * kModerate hints V8 to speed up incremental garbage collection at the cost of
7017 : * of higher latency due to garbage collection pauses.
7018 : * kCritical hints V8 to free memory as soon as possible. Garbage collection
7019 : * pauses at this level will be large.
7020 : */
7021 : enum class MemoryPressureLevel { kNone, kModerate, kCritical };
7022 :
7023 : /**
7024 : * Interface for tracing through the embedder heap. During a V8 garbage
7025 : * collection, V8 collects hidden fields of all potential wrappers, and at the
7026 : * end of its marking phase iterates the collection and asks the embedder to
7027 : * trace through its heap and use reporter to report each JavaScript object
7028 : * reachable from any of the given wrappers.
7029 : */
7030 49 : class V8_EXPORT EmbedderHeapTracer {
7031 : public:
7032 : // Indicator for the stack state of the embedder.
7033 : enum EmbedderStackState {
7034 : kUnknown,
7035 : kNonEmpty,
7036 : kEmpty,
7037 : };
7038 :
7039 49 : virtual ~EmbedderHeapTracer() = default;
7040 :
7041 : /**
7042 : * Called by v8 to register internal fields of found wrappers.
7043 : *
7044 : * The embedder is expected to store them somewhere and trace reachable
7045 : * wrappers from them when called through |AdvanceTracing|.
7046 : */
7047 : virtual void RegisterV8References(
7048 : const std::vector<std::pair<void*, void*> >& embedder_fields) = 0;
7049 :
7050 : /**
7051 : * Called at the beginning of a GC cycle.
7052 : */
7053 : virtual void TracePrologue() = 0;
7054 :
7055 : /**
7056 : * Called to advance tracing in the embedder.
7057 : *
7058 : * The embedder is expected to trace its heap starting from wrappers reported
7059 : * by RegisterV8References method, and report back all reachable wrappers.
7060 : * Furthermore, the embedder is expected to stop tracing by the given
7061 : * deadline. A deadline of infinity means that tracing should be finished.
7062 : *
7063 : * Returns |true| if tracing is done, and false otherwise.
7064 : */
7065 : virtual bool AdvanceTracing(double deadline_in_ms) = 0;
7066 :
7067 : /*
7068 : * Returns true if there no more tracing work to be done (see AdvanceTracing)
7069 : * and false otherwise.
7070 : */
7071 : virtual bool IsTracingDone() = 0;
7072 :
7073 : /**
7074 : * Called at the end of a GC cycle.
7075 : *
7076 : * Note that allocation is *not* allowed within |TraceEpilogue|.
7077 : */
7078 : virtual void TraceEpilogue() = 0;
7079 :
7080 : /**
7081 : * Called upon entering the final marking pause. No more incremental marking
7082 : * steps will follow this call.
7083 : */
7084 : virtual void EnterFinalPause(EmbedderStackState stack_state) = 0;
7085 :
7086 : /**
7087 : * Called when tracing is aborted.
7088 : *
7089 : * The embedder is expected to throw away all intermediate data and reset to
7090 : * the initial state.
7091 : */
7092 0 : V8_DEPRECATED("Obsolete as V8 will not abort tracing anymore.",
7093 0 : virtual void AbortTracing()) {}
7094 :
7095 : /*
7096 : * Called by the embedder to request immediate finalization of the currently
7097 : * running tracing phase that has been started with TracePrologue and not
7098 : * yet finished with TraceEpilogue.
7099 : *
7100 : * Will be a noop when currently not in tracing.
7101 : *
7102 : * This is an experimental feature.
7103 : */
7104 : void FinalizeTracing();
7105 :
7106 : /*
7107 : * Called by the embedder to immediately perform a full garbage collection.
7108 : *
7109 : * Should only be used in testing code.
7110 : */
7111 : void GarbageCollectionForTesting(EmbedderStackState stack_state);
7112 :
7113 : /*
7114 : * Returns the v8::Isolate this tracer is attached too and |nullptr| if it
7115 : * is not attached to any v8::Isolate.
7116 : */
7117 : v8::Isolate* isolate() const { return isolate_; }
7118 :
7119 : protected:
7120 : v8::Isolate* isolate_ = nullptr;
7121 :
7122 : friend class internal::LocalEmbedderHeapTracer;
7123 : };
7124 :
7125 : /**
7126 : * Callback and supporting data used in SnapshotCreator to implement embedder
7127 : * logic to serialize internal fields.
7128 : * Internal fields that directly reference V8 objects are serialized without
7129 : * calling this callback. Internal fields that contain aligned pointers are
7130 : * serialized by this callback if it returns non-zero result. Otherwise it is
7131 : * serialized verbatim.
7132 : */
7133 : struct SerializeInternalFieldsCallback {
7134 : typedef StartupData (*CallbackFunction)(Local<Object> holder, int index,
7135 : void* data);
7136 : SerializeInternalFieldsCallback(CallbackFunction function = nullptr,
7137 : void* data_arg = nullptr)
7138 412 : : callback(function), data(data_arg) {}
7139 : CallbackFunction callback;
7140 : void* data;
7141 : };
7142 : // Note that these fields are called "internal fields" in the API and called
7143 : // "embedder fields" within V8.
7144 : typedef SerializeInternalFieldsCallback SerializeEmbedderFieldsCallback;
7145 :
7146 : /**
7147 : * Callback and supporting data used to implement embedder logic to deserialize
7148 : * internal fields.
7149 : */
7150 : struct DeserializeInternalFieldsCallback {
7151 : typedef void (*CallbackFunction)(Local<Object> holder, int index,
7152 : StartupData payload, void* data);
7153 : DeserializeInternalFieldsCallback(CallbackFunction function = nullptr,
7154 : void* data_arg = nullptr)
7155 89586 : : callback(function), data(data_arg) {}
7156 : void (*callback)(Local<Object> holder, int index, StartupData payload,
7157 : void* data);
7158 : void* data;
7159 : };
7160 : typedef DeserializeInternalFieldsCallback DeserializeEmbedderFieldsCallback;
7161 :
7162 : /**
7163 : * Isolate represents an isolated instance of the V8 engine. V8 isolates have
7164 : * completely separate states. Objects from one isolate must not be used in
7165 : * other isolates. The embedder can create multiple isolates and use them in
7166 : * parallel in multiple threads. An isolate can be entered by at most one
7167 : * thread at any given time. The Locker/Unlocker API must be used to
7168 : * synchronize.
7169 : */
7170 : class V8_EXPORT Isolate {
7171 : public:
7172 : /**
7173 : * Initial configuration parameters for a new Isolate.
7174 : */
7175 : struct CreateParams {
7176 : CreateParams()
7177 : : code_event_handler(nullptr),
7178 : snapshot_blob(nullptr),
7179 : counter_lookup_callback(nullptr),
7180 : create_histogram_callback(nullptr),
7181 : add_histogram_sample_callback(nullptr),
7182 : array_buffer_allocator(nullptr),
7183 : external_references(nullptr),
7184 : allow_atomics_wait(true),
7185 60029 : only_terminate_in_safe_scope(false) {}
7186 :
7187 : /**
7188 : * Allows the host application to provide the address of a function that is
7189 : * notified each time code is added, moved or removed.
7190 : */
7191 : JitCodeEventHandler code_event_handler;
7192 :
7193 : /**
7194 : * ResourceConstraints to use for the new Isolate.
7195 : */
7196 : ResourceConstraints constraints;
7197 :
7198 : /**
7199 : * Explicitly specify a startup snapshot blob. The embedder owns the blob.
7200 : */
7201 : StartupData* snapshot_blob;
7202 :
7203 :
7204 : /**
7205 : * Enables the host application to provide a mechanism for recording
7206 : * statistics counters.
7207 : */
7208 : CounterLookupCallback counter_lookup_callback;
7209 :
7210 : /**
7211 : * Enables the host application to provide a mechanism for recording
7212 : * histograms. The CreateHistogram function returns a
7213 : * histogram which will later be passed to the AddHistogramSample
7214 : * function.
7215 : */
7216 : CreateHistogramCallback create_histogram_callback;
7217 : AddHistogramSampleCallback add_histogram_sample_callback;
7218 :
7219 : /**
7220 : * The ArrayBuffer::Allocator to use for allocating and freeing the backing
7221 : * store of ArrayBuffers.
7222 : */
7223 : ArrayBuffer::Allocator* array_buffer_allocator;
7224 :
7225 : /**
7226 : * Specifies an optional nullptr-terminated array of raw addresses in the
7227 : * embedder that V8 can match against during serialization and use for
7228 : * deserialization. This array and its content must stay valid for the
7229 : * entire lifetime of the isolate.
7230 : */
7231 : const intptr_t* external_references;
7232 :
7233 : /**
7234 : * Whether calling Atomics.wait (a function that may block) is allowed in
7235 : * this isolate. This can also be configured via SetAllowAtomicsWait.
7236 : */
7237 : bool allow_atomics_wait;
7238 :
7239 : /**
7240 : * Termination is postponed when there is no active SafeForTerminationScope.
7241 : */
7242 : bool only_terminate_in_safe_scope;
7243 : };
7244 :
7245 :
7246 : /**
7247 : * Stack-allocated class which sets the isolate for all operations
7248 : * executed within a local scope.
7249 : */
7250 : class V8_EXPORT Scope {
7251 : public:
7252 1308 : explicit Scope(Isolate* isolate) : isolate_(isolate) {
7253 38474 : isolate->Enter();
7254 : }
7255 :
7256 38476 : ~Scope() { isolate_->Exit(); }
7257 :
7258 : // Prevent copying of Scope objects.
7259 : Scope(const Scope&) = delete;
7260 : Scope& operator=(const Scope&) = delete;
7261 :
7262 : private:
7263 : Isolate* const isolate_;
7264 : };
7265 :
7266 :
7267 : /**
7268 : * Assert that no Javascript code is invoked.
7269 : */
7270 : class V8_EXPORT DisallowJavascriptExecutionScope {
7271 : public:
7272 : enum OnFailure { CRASH_ON_FAILURE, THROW_ON_FAILURE, DUMP_ON_FAILURE };
7273 :
7274 : DisallowJavascriptExecutionScope(Isolate* isolate, OnFailure on_failure);
7275 : ~DisallowJavascriptExecutionScope();
7276 :
7277 : // Prevent copying of Scope objects.
7278 : DisallowJavascriptExecutionScope(const DisallowJavascriptExecutionScope&) =
7279 : delete;
7280 : DisallowJavascriptExecutionScope& operator=(
7281 : const DisallowJavascriptExecutionScope&) = delete;
7282 :
7283 : private:
7284 : OnFailure on_failure_;
7285 : void* internal_;
7286 : };
7287 :
7288 :
7289 : /**
7290 : * Introduce exception to DisallowJavascriptExecutionScope.
7291 : */
7292 : class V8_EXPORT AllowJavascriptExecutionScope {
7293 : public:
7294 : explicit AllowJavascriptExecutionScope(Isolate* isolate);
7295 : ~AllowJavascriptExecutionScope();
7296 :
7297 : // Prevent copying of Scope objects.
7298 : AllowJavascriptExecutionScope(const AllowJavascriptExecutionScope&) =
7299 : delete;
7300 : AllowJavascriptExecutionScope& operator=(
7301 : const AllowJavascriptExecutionScope&) = delete;
7302 :
7303 : private:
7304 : void* internal_throws_;
7305 : void* internal_assert_;
7306 : void* internal_dump_;
7307 : };
7308 :
7309 : /**
7310 : * Do not run microtasks while this scope is active, even if microtasks are
7311 : * automatically executed otherwise.
7312 : */
7313 : class V8_EXPORT SuppressMicrotaskExecutionScope {
7314 : public:
7315 : explicit SuppressMicrotaskExecutionScope(Isolate* isolate);
7316 : ~SuppressMicrotaskExecutionScope();
7317 :
7318 : // Prevent copying of Scope objects.
7319 : SuppressMicrotaskExecutionScope(const SuppressMicrotaskExecutionScope&) =
7320 : delete;
7321 : SuppressMicrotaskExecutionScope& operator=(
7322 : const SuppressMicrotaskExecutionScope&) = delete;
7323 :
7324 : private:
7325 : internal::Isolate* const isolate_;
7326 : };
7327 :
7328 : /**
7329 : * This scope allows terminations inside direct V8 API calls and forbid them
7330 : * inside any recursice API calls without explicit SafeForTerminationScope.
7331 : */
7332 : class V8_EXPORT SafeForTerminationScope {
7333 : public:
7334 : explicit SafeForTerminationScope(v8::Isolate* isolate);
7335 : ~SafeForTerminationScope();
7336 :
7337 : // Prevent copying of Scope objects.
7338 : SafeForTerminationScope(const SafeForTerminationScope&) = delete;
7339 : SafeForTerminationScope& operator=(const SafeForTerminationScope&) = delete;
7340 :
7341 : private:
7342 : internal::Isolate* isolate_;
7343 : bool prev_value_;
7344 : };
7345 :
7346 : /**
7347 : * Types of garbage collections that can be requested via
7348 : * RequestGarbageCollectionForTesting.
7349 : */
7350 : enum GarbageCollectionType {
7351 : kFullGarbageCollection,
7352 : kMinorGarbageCollection
7353 : };
7354 :
7355 : /**
7356 : * Features reported via the SetUseCounterCallback callback. Do not change
7357 : * assigned numbers of existing items; add new features to the end of this
7358 : * list.
7359 : */
7360 : enum UseCounterFeature {
7361 : kUseAsm = 0,
7362 : kBreakIterator = 1,
7363 : kLegacyConst = 2,
7364 : kMarkDequeOverflow = 3,
7365 : kStoreBufferOverflow = 4,
7366 : kSlotsBufferOverflow = 5,
7367 : kObjectObserve = 6,
7368 : kForcedGC = 7,
7369 : kSloppyMode = 8,
7370 : kStrictMode = 9,
7371 : kStrongMode = 10,
7372 : kRegExpPrototypeStickyGetter = 11,
7373 : kRegExpPrototypeToString = 12,
7374 : kRegExpPrototypeUnicodeGetter = 13,
7375 : kIntlV8Parse = 14,
7376 : kIntlPattern = 15,
7377 : kIntlResolved = 16,
7378 : kPromiseChain = 17,
7379 : kPromiseAccept = 18,
7380 : kPromiseDefer = 19,
7381 : kHtmlCommentInExternalScript = 20,
7382 : kHtmlComment = 21,
7383 : kSloppyModeBlockScopedFunctionRedefinition = 22,
7384 : kForInInitializer = 23,
7385 : kArrayProtectorDirtied = 24,
7386 : kArraySpeciesModified = 25,
7387 : kArrayPrototypeConstructorModified = 26,
7388 : kArrayInstanceProtoModified = 27,
7389 : kArrayInstanceConstructorModified = 28,
7390 : kLegacyFunctionDeclaration = 29,
7391 : kRegExpPrototypeSourceGetter = 30,
7392 : kRegExpPrototypeOldFlagGetter = 31,
7393 : kDecimalWithLeadingZeroInStrictMode = 32,
7394 : kLegacyDateParser = 33,
7395 : kDefineGetterOrSetterWouldThrow = 34,
7396 : kFunctionConstructorReturnedUndefined = 35,
7397 : kAssigmentExpressionLHSIsCallInSloppy = 36,
7398 : kAssigmentExpressionLHSIsCallInStrict = 37,
7399 : kPromiseConstructorReturnedUndefined = 38,
7400 : kConstructorNonUndefinedPrimitiveReturn = 39,
7401 : kLabeledExpressionStatement = 40,
7402 : kLineOrParagraphSeparatorAsLineTerminator = 41,
7403 : kIndexAccessor = 42,
7404 : kErrorCaptureStackTrace = 43,
7405 : kErrorPrepareStackTrace = 44,
7406 : kErrorStackTraceLimit = 45,
7407 : kWebAssemblyInstantiation = 46,
7408 : kDeoptimizerDisableSpeculation = 47,
7409 : kArrayPrototypeSortJSArrayModifiedPrototype = 48,
7410 : kFunctionTokenOffsetTooLongForToString = 49,
7411 : kWasmSharedMemory = 50,
7412 : kWasmThreadOpcodes = 51,
7413 : kAtomicsNotify = 52,
7414 : kAtomicsWake = 53,
7415 : kCollator = 54,
7416 : kNumberFormat = 55,
7417 : kDateTimeFormat = 56,
7418 : kPluralRules = 57,
7419 : kRelativeTimeFormat = 58,
7420 : kLocale = 59,
7421 : kListFormat = 60,
7422 : kSegmenter = 61,
7423 : kStringLocaleCompare = 62,
7424 : kStringToLocaleUpperCase = 63,
7425 : kStringToLocaleLowerCase = 64,
7426 : kNumberToLocaleString = 65,
7427 : kDateToLocaleString = 66,
7428 : kDateToLocaleDateString = 67,
7429 : kDateToLocaleTimeString = 68,
7430 : kAttemptOverrideReadOnlyOnPrototypeSloppy = 69,
7431 : kAttemptOverrideReadOnlyOnPrototypeStrict = 70,
7432 : kOptimizedFunctionWithOneShotBytecode = 71,
7433 : kRegExpMatchIsTrueishOnNonJSRegExp = 72,
7434 : kRegExpMatchIsFalseishOnJSRegExp = 73,
7435 : kDateGetTimezoneOffset = 74,
7436 :
7437 : // If you add new values here, you'll also need to update Chromium's:
7438 : // web_feature.mojom, UseCounterCallback.cpp, and enums.xml. V8 changes to
7439 : // this list need to be landed first, then changes on the Chromium side.
7440 : kUseCounterFeatureCount // This enum value must be last.
7441 : };
7442 :
7443 : enum MessageErrorLevel {
7444 : kMessageLog = (1 << 0),
7445 : kMessageDebug = (1 << 1),
7446 : kMessageInfo = (1 << 2),
7447 : kMessageError = (1 << 3),
7448 : kMessageWarning = (1 << 4),
7449 : kMessageAll = kMessageLog | kMessageDebug | kMessageInfo | kMessageError |
7450 : kMessageWarning,
7451 : };
7452 :
7453 : typedef void (*UseCounterCallback)(Isolate* isolate,
7454 : UseCounterFeature feature);
7455 :
7456 : /**
7457 : * Allocates a new isolate but does not initialize it. Does not change the
7458 : * currently entered isolate.
7459 : *
7460 : * Only Isolate::GetData() and Isolate::SetData(), which access the
7461 : * embedder-controlled parts of the isolate, are allowed to be called on the
7462 : * uninitialized isolate. To initialize the isolate, call
7463 : * Isolate::Initialize().
7464 : *
7465 : * When an isolate is no longer used its resources should be freed
7466 : * by calling Dispose(). Using the delete operator is not allowed.
7467 : *
7468 : * V8::Initialize() must have run prior to this.
7469 : */
7470 : static Isolate* Allocate();
7471 :
7472 : /**
7473 : * Initialize an Isolate previously allocated by Isolate::Allocate().
7474 : */
7475 : static void Initialize(Isolate* isolate, const CreateParams& params);
7476 :
7477 : /**
7478 : * Creates a new isolate. Does not change the currently entered
7479 : * isolate.
7480 : *
7481 : * When an isolate is no longer used its resources should be freed
7482 : * by calling Dispose(). Using the delete operator is not allowed.
7483 : *
7484 : * V8::Initialize() must have run prior to this.
7485 : */
7486 : static Isolate* New(const CreateParams& params);
7487 :
7488 : /**
7489 : * Returns the entered isolate for the current thread or NULL in
7490 : * case there is no current isolate.
7491 : *
7492 : * This method must not be invoked before V8::Initialize() was invoked.
7493 : */
7494 : static Isolate* GetCurrent();
7495 :
7496 : /**
7497 : * Custom callback used by embedders to help V8 determine if it should abort
7498 : * when it throws and no internal handler is predicted to catch the
7499 : * exception. If --abort-on-uncaught-exception is used on the command line,
7500 : * then V8 will abort if either:
7501 : * - no custom callback is set.
7502 : * - the custom callback set returns true.
7503 : * Otherwise, the custom callback will not be called and V8 will not abort.
7504 : */
7505 : typedef bool (*AbortOnUncaughtExceptionCallback)(Isolate*);
7506 : void SetAbortOnUncaughtExceptionCallback(
7507 : AbortOnUncaughtExceptionCallback callback);
7508 :
7509 : /**
7510 : * This specifies the callback called by the upcoming dynamic
7511 : * import() language feature to load modules.
7512 : */
7513 : void SetHostImportModuleDynamicallyCallback(
7514 : HostImportModuleDynamicallyCallback callback);
7515 :
7516 : /**
7517 : * This specifies the callback called by the upcoming importa.meta
7518 : * language feature to retrieve host-defined meta data for a module.
7519 : */
7520 : void SetHostInitializeImportMetaObjectCallback(
7521 : HostInitializeImportMetaObjectCallback callback);
7522 :
7523 : /**
7524 : * This specifies the callback called when the stack property of Error
7525 : * is accessed.
7526 : */
7527 : void SetPrepareStackTraceCallback(PrepareStackTraceCallback callback);
7528 :
7529 : /**
7530 : * Optional notification that the system is running low on memory.
7531 : * V8 uses these notifications to guide heuristics.
7532 : * It is allowed to call this function from another thread while
7533 : * the isolate is executing long running JavaScript code.
7534 : */
7535 : void MemoryPressureNotification(MemoryPressureLevel level);
7536 :
7537 : /**
7538 : * Methods below this point require holding a lock (using Locker) in
7539 : * a multi-threaded environment.
7540 : */
7541 :
7542 : /**
7543 : * Sets this isolate as the entered one for the current thread.
7544 : * Saves the previously entered one (if any), so that it can be
7545 : * restored when exiting. Re-entering an isolate is allowed.
7546 : */
7547 : void Enter();
7548 :
7549 : /**
7550 : * Exits this isolate by restoring the previously entered one in the
7551 : * current thread. The isolate may still stay the same, if it was
7552 : * entered more than once.
7553 : *
7554 : * Requires: this == Isolate::GetCurrent().
7555 : */
7556 : void Exit();
7557 :
7558 : /**
7559 : * Disposes the isolate. The isolate must not be entered by any
7560 : * thread to be disposable.
7561 : */
7562 : void Dispose();
7563 :
7564 : /**
7565 : * Dumps activated low-level V8 internal stats. This can be used instead
7566 : * of performing a full isolate disposal.
7567 : */
7568 : void DumpAndResetStats();
7569 :
7570 : /**
7571 : * Discards all V8 thread-specific data for the Isolate. Should be used
7572 : * if a thread is terminating and it has used an Isolate that will outlive
7573 : * the thread -- all thread-specific data for an Isolate is discarded when
7574 : * an Isolate is disposed so this call is pointless if an Isolate is about
7575 : * to be Disposed.
7576 : */
7577 : void DiscardThreadSpecificMetadata();
7578 :
7579 : /**
7580 : * Associate embedder-specific data with the isolate. |slot| has to be
7581 : * between 0 and GetNumberOfDataSlots() - 1.
7582 : */
7583 : V8_INLINE void SetData(uint32_t slot, void* data);
7584 :
7585 : /**
7586 : * Retrieve embedder-specific data from the isolate.
7587 : * Returns NULL if SetData has never been called for the given |slot|.
7588 : */
7589 : V8_INLINE void* GetData(uint32_t slot);
7590 :
7591 : /**
7592 : * Returns the maximum number of available embedder data slots. Valid slots
7593 : * are in the range of 0 - GetNumberOfDataSlots() - 1.
7594 : */
7595 : V8_INLINE static uint32_t GetNumberOfDataSlots();
7596 :
7597 : /**
7598 : * Return data that was previously attached to the isolate snapshot via
7599 : * SnapshotCreator, and removes the reference to it.
7600 : * Repeated call with the same index returns an empty MaybeLocal.
7601 : */
7602 : template <class T>
7603 : V8_INLINE MaybeLocal<T> GetDataFromSnapshotOnce(size_t index);
7604 :
7605 : /**
7606 : * Get statistics about the heap memory usage.
7607 : */
7608 : void GetHeapStatistics(HeapStatistics* heap_statistics);
7609 :
7610 : /**
7611 : * Returns the number of spaces in the heap.
7612 : */
7613 : size_t NumberOfHeapSpaces();
7614 :
7615 : /**
7616 : * Get the memory usage of a space in the heap.
7617 : *
7618 : * \param space_statistics The HeapSpaceStatistics object to fill in
7619 : * statistics.
7620 : * \param index The index of the space to get statistics from, which ranges
7621 : * from 0 to NumberOfHeapSpaces() - 1.
7622 : * \returns true on success.
7623 : */
7624 : bool GetHeapSpaceStatistics(HeapSpaceStatistics* space_statistics,
7625 : size_t index);
7626 :
7627 : /**
7628 : * Returns the number of types of objects tracked in the heap at GC.
7629 : */
7630 : size_t NumberOfTrackedHeapObjectTypes();
7631 :
7632 : /**
7633 : * Get statistics about objects in the heap.
7634 : *
7635 : * \param object_statistics The HeapObjectStatistics object to fill in
7636 : * statistics of objects of given type, which were live in the previous GC.
7637 : * \param type_index The index of the type of object to fill details about,
7638 : * which ranges from 0 to NumberOfTrackedHeapObjectTypes() - 1.
7639 : * \returns true on success.
7640 : */
7641 : bool GetHeapObjectStatisticsAtLastGC(HeapObjectStatistics* object_statistics,
7642 : size_t type_index);
7643 :
7644 : /**
7645 : * Get statistics about code and its metadata in the heap.
7646 : *
7647 : * \param object_statistics The HeapCodeStatistics object to fill in
7648 : * statistics of code, bytecode and their metadata.
7649 : * \returns true on success.
7650 : */
7651 : bool GetHeapCodeAndMetadataStatistics(HeapCodeStatistics* object_statistics);
7652 :
7653 : /**
7654 : * Get a call stack sample from the isolate.
7655 : * \param state Execution state.
7656 : * \param frames Caller allocated buffer to store stack frames.
7657 : * \param frames_limit Maximum number of frames to capture. The buffer must
7658 : * be large enough to hold the number of frames.
7659 : * \param sample_info The sample info is filled up by the function
7660 : * provides number of actual captured stack frames and
7661 : * the current VM state.
7662 : * \note GetStackSample should only be called when the JS thread is paused or
7663 : * interrupted. Otherwise the behavior is undefined.
7664 : */
7665 : void GetStackSample(const RegisterState& state, void** frames,
7666 : size_t frames_limit, SampleInfo* sample_info);
7667 :
7668 : /**
7669 : * Adjusts the amount of registered external memory. Used to give V8 an
7670 : * indication of the amount of externally allocated memory that is kept alive
7671 : * by JavaScript objects. V8 uses this to decide when to perform global
7672 : * garbage collections. Registering externally allocated memory will trigger
7673 : * global garbage collections more often than it would otherwise in an attempt
7674 : * to garbage collect the JavaScript objects that keep the externally
7675 : * allocated memory alive.
7676 : *
7677 : * \param change_in_bytes the change in externally allocated memory that is
7678 : * kept alive by JavaScript objects.
7679 : * \returns the adjusted value.
7680 : */
7681 : V8_INLINE int64_t
7682 : AdjustAmountOfExternalAllocatedMemory(int64_t change_in_bytes);
7683 :
7684 : /**
7685 : * Returns the number of phantom handles without callbacks that were reset
7686 : * by the garbage collector since the last call to this function.
7687 : */
7688 : size_t NumberOfPhantomHandleResetsSinceLastCall();
7689 :
7690 : /**
7691 : * Returns heap profiler for this isolate. Will return NULL until the isolate
7692 : * is initialized.
7693 : */
7694 : HeapProfiler* GetHeapProfiler();
7695 :
7696 : /**
7697 : * Tells the VM whether the embedder is idle or not.
7698 : */
7699 : void SetIdle(bool is_idle);
7700 :
7701 : /** Returns true if this isolate has a current context. */
7702 : bool InContext();
7703 :
7704 : /**
7705 : * Returns the context of the currently running JavaScript, or the context
7706 : * on the top of the stack if no JavaScript is running.
7707 : */
7708 : Local<Context> GetCurrentContext();
7709 :
7710 : /** Returns the last context entered through V8's C++ API. */
7711 : V8_DEPRECATED("Use GetEnteredOrMicrotaskContext().",
7712 : Local<Context> GetEnteredContext());
7713 :
7714 : /**
7715 : * Returns either the last context entered through V8's C++ API, or the
7716 : * context of the currently running microtask while processing microtasks.
7717 : * If a context is entered while executing a microtask, that context is
7718 : * returned.
7719 : */
7720 : Local<Context> GetEnteredOrMicrotaskContext();
7721 :
7722 : /**
7723 : * Returns the Context that corresponds to the Incumbent realm in HTML spec.
7724 : * https://html.spec.whatwg.org/multipage/webappapis.html#incumbent
7725 : */
7726 : Local<Context> GetIncumbentContext();
7727 :
7728 : /**
7729 : * Schedules an exception to be thrown when returning to JavaScript. When an
7730 : * exception has been scheduled it is illegal to invoke any JavaScript
7731 : * operation; the caller must return immediately and only after the exception
7732 : * has been handled does it become legal to invoke JavaScript operations.
7733 : */
7734 : Local<Value> ThrowException(Local<Value> exception);
7735 :
7736 : typedef void (*GCCallback)(Isolate* isolate, GCType type,
7737 : GCCallbackFlags flags);
7738 : typedef void (*GCCallbackWithData)(Isolate* isolate, GCType type,
7739 : GCCallbackFlags flags, void* data);
7740 :
7741 : /**
7742 : * Enables the host application to receive a notification before a
7743 : * garbage collection. Allocations are allowed in the callback function,
7744 : * but the callback is not re-entrant: if the allocation inside it will
7745 : * trigger the garbage collection, the callback won't be called again.
7746 : * It is possible to specify the GCType filter for your callback. But it is
7747 : * not possible to register the same callback function two times with
7748 : * different GCType filters.
7749 : */
7750 : void AddGCPrologueCallback(GCCallbackWithData callback, void* data = nullptr,
7751 : GCType gc_type_filter = kGCTypeAll);
7752 : void AddGCPrologueCallback(GCCallback callback,
7753 : GCType gc_type_filter = kGCTypeAll);
7754 :
7755 : /**
7756 : * This function removes callback which was installed by
7757 : * AddGCPrologueCallback function.
7758 : */
7759 : void RemoveGCPrologueCallback(GCCallbackWithData, void* data = nullptr);
7760 : void RemoveGCPrologueCallback(GCCallback callback);
7761 :
7762 : /**
7763 : * Sets the embedder heap tracer for the isolate.
7764 : */
7765 : void SetEmbedderHeapTracer(EmbedderHeapTracer* tracer);
7766 :
7767 : /*
7768 : * Gets the currently active heap tracer for the isolate.
7769 : */
7770 : EmbedderHeapTracer* GetEmbedderHeapTracer();
7771 :
7772 : /**
7773 : * Use for |AtomicsWaitCallback| to indicate the type of event it receives.
7774 : */
7775 : enum class AtomicsWaitEvent {
7776 : /** Indicates that this call is happening before waiting. */
7777 : kStartWait,
7778 : /** `Atomics.wait()` finished because of an `Atomics.wake()` call. */
7779 : kWokenUp,
7780 : /** `Atomics.wait()` finished because it timed out. */
7781 : kTimedOut,
7782 : /** `Atomics.wait()` was interrupted through |TerminateExecution()|. */
7783 : kTerminatedExecution,
7784 : /** `Atomics.wait()` was stopped through |AtomicsWaitWakeHandle|. */
7785 : kAPIStopped,
7786 : /** `Atomics.wait()` did not wait, as the initial condition was not met. */
7787 : kNotEqual
7788 : };
7789 :
7790 : /**
7791 : * Passed to |AtomicsWaitCallback| as a means of stopping an ongoing
7792 : * `Atomics.wait` call.
7793 : */
7794 : class V8_EXPORT AtomicsWaitWakeHandle {
7795 : public:
7796 : /**
7797 : * Stop this `Atomics.wait()` call and call the |AtomicsWaitCallback|
7798 : * with |kAPIStopped|.
7799 : *
7800 : * This function may be called from another thread. The caller has to ensure
7801 : * through proper synchronization that it is not called after
7802 : * the finishing |AtomicsWaitCallback|.
7803 : *
7804 : * Note that the ECMAScript specification does not plan for the possibility
7805 : * of wakeups that are neither coming from a timeout or an `Atomics.wake()`
7806 : * call, so this may invalidate assumptions made by existing code.
7807 : * The embedder may accordingly wish to schedule an exception in the
7808 : * finishing |AtomicsWaitCallback|.
7809 : */
7810 : void Wake();
7811 : };
7812 :
7813 : /**
7814 : * Embedder callback for `Atomics.wait()` that can be added through
7815 : * |SetAtomicsWaitCallback|.
7816 : *
7817 : * This will be called just before starting to wait with the |event| value
7818 : * |kStartWait| and after finishing waiting with one of the other
7819 : * values of |AtomicsWaitEvent| inside of an `Atomics.wait()` call.
7820 : *
7821 : * |array_buffer| will refer to the underlying SharedArrayBuffer,
7822 : * |offset_in_bytes| to the location of the waited-on memory address inside
7823 : * the SharedArrayBuffer.
7824 : *
7825 : * |value| and |timeout_in_ms| will be the values passed to
7826 : * the `Atomics.wait()` call. If no timeout was used, |timeout_in_ms|
7827 : * will be `INFINITY`.
7828 : *
7829 : * In the |kStartWait| callback, |stop_handle| will be an object that
7830 : * is only valid until the corresponding finishing callback and that
7831 : * can be used to stop the wait process while it is happening.
7832 : *
7833 : * This callback may schedule exceptions, *unless* |event| is equal to
7834 : * |kTerminatedExecution|.
7835 : */
7836 : typedef void (*AtomicsWaitCallback)(AtomicsWaitEvent event,
7837 : Local<SharedArrayBuffer> array_buffer,
7838 : size_t offset_in_bytes, int64_t value,
7839 : double timeout_in_ms,
7840 : AtomicsWaitWakeHandle* stop_handle,
7841 : void* data);
7842 :
7843 : /**
7844 : * Set a new |AtomicsWaitCallback|. This overrides an earlier
7845 : * |AtomicsWaitCallback|, if there was any. If |callback| is nullptr,
7846 : * this unsets the callback. |data| will be passed to the callback
7847 : * as its last parameter.
7848 : */
7849 : void SetAtomicsWaitCallback(AtomicsWaitCallback callback, void* data);
7850 :
7851 : /**
7852 : * Enables the host application to receive a notification after a
7853 : * garbage collection. Allocations are allowed in the callback function,
7854 : * but the callback is not re-entrant: if the allocation inside it will
7855 : * trigger the garbage collection, the callback won't be called again.
7856 : * It is possible to specify the GCType filter for your callback. But it is
7857 : * not possible to register the same callback function two times with
7858 : * different GCType filters.
7859 : */
7860 : void AddGCEpilogueCallback(GCCallbackWithData callback, void* data = nullptr,
7861 : GCType gc_type_filter = kGCTypeAll);
7862 : void AddGCEpilogueCallback(GCCallback callback,
7863 : GCType gc_type_filter = kGCTypeAll);
7864 :
7865 : /**
7866 : * This function removes callback which was installed by
7867 : * AddGCEpilogueCallback function.
7868 : */
7869 : void RemoveGCEpilogueCallback(GCCallbackWithData callback,
7870 : void* data = nullptr);
7871 : void RemoveGCEpilogueCallback(GCCallback callback);
7872 :
7873 : typedef size_t (*GetExternallyAllocatedMemoryInBytesCallback)();
7874 :
7875 : /**
7876 : * Set the callback that tells V8 how much memory is currently allocated
7877 : * externally of the V8 heap. Ideally this memory is somehow connected to V8
7878 : * objects and may get freed-up when the corresponding V8 objects get
7879 : * collected by a V8 garbage collection.
7880 : */
7881 : void SetGetExternallyAllocatedMemoryInBytesCallback(
7882 : GetExternallyAllocatedMemoryInBytesCallback callback);
7883 :
7884 : /**
7885 : * Forcefully terminate the current thread of JavaScript execution
7886 : * in the given isolate.
7887 : *
7888 : * This method can be used by any thread even if that thread has not
7889 : * acquired the V8 lock with a Locker object.
7890 : */
7891 : void TerminateExecution();
7892 :
7893 : /**
7894 : * Is V8 terminating JavaScript execution.
7895 : *
7896 : * Returns true if JavaScript execution is currently terminating
7897 : * because of a call to TerminateExecution. In that case there are
7898 : * still JavaScript frames on the stack and the termination
7899 : * exception is still active.
7900 : */
7901 : bool IsExecutionTerminating();
7902 :
7903 : /**
7904 : * Resume execution capability in the given isolate, whose execution
7905 : * was previously forcefully terminated using TerminateExecution().
7906 : *
7907 : * When execution is forcefully terminated using TerminateExecution(),
7908 : * the isolate can not resume execution until all JavaScript frames
7909 : * have propagated the uncatchable exception which is generated. This
7910 : * method allows the program embedding the engine to handle the
7911 : * termination event and resume execution capability, even if
7912 : * JavaScript frames remain on the stack.
7913 : *
7914 : * This method can be used by any thread even if that thread has not
7915 : * acquired the V8 lock with a Locker object.
7916 : */
7917 : void CancelTerminateExecution();
7918 :
7919 : /**
7920 : * Request V8 to interrupt long running JavaScript code and invoke
7921 : * the given |callback| passing the given |data| to it. After |callback|
7922 : * returns control will be returned to the JavaScript code.
7923 : * There may be a number of interrupt requests in flight.
7924 : * Can be called from another thread without acquiring a |Locker|.
7925 : * Registered |callback| must not reenter interrupted Isolate.
7926 : */
7927 : void RequestInterrupt(InterruptCallback callback, void* data);
7928 :
7929 : /**
7930 : * Request garbage collection in this Isolate. It is only valid to call this
7931 : * function if --expose_gc was specified.
7932 : *
7933 : * This should only be used for testing purposes and not to enforce a garbage
7934 : * collection schedule. It has strong negative impact on the garbage
7935 : * collection performance. Use IdleNotificationDeadline() or
7936 : * LowMemoryNotification() instead to influence the garbage collection
7937 : * schedule.
7938 : */
7939 : void RequestGarbageCollectionForTesting(GarbageCollectionType type);
7940 :
7941 : /**
7942 : * Set the callback to invoke for logging event.
7943 : */
7944 : void SetEventLogger(LogEventCallback that);
7945 :
7946 : /**
7947 : * Adds a callback to notify the host application right before a script
7948 : * is about to run. If a script re-enters the runtime during executing, the
7949 : * BeforeCallEnteredCallback is invoked for each re-entrance.
7950 : * Executing scripts inside the callback will re-trigger the callback.
7951 : */
7952 : void AddBeforeCallEnteredCallback(BeforeCallEnteredCallback callback);
7953 :
7954 : /**
7955 : * Removes callback that was installed by AddBeforeCallEnteredCallback.
7956 : */
7957 : void RemoveBeforeCallEnteredCallback(BeforeCallEnteredCallback callback);
7958 :
7959 : /**
7960 : * Adds a callback to notify the host application when a script finished
7961 : * running. If a script re-enters the runtime during executing, the
7962 : * CallCompletedCallback is only invoked when the outer-most script
7963 : * execution ends. Executing scripts inside the callback do not trigger
7964 : * further callbacks.
7965 : */
7966 : void AddCallCompletedCallback(CallCompletedCallback callback);
7967 :
7968 : /**
7969 : * Removes callback that was installed by AddCallCompletedCallback.
7970 : */
7971 : void RemoveCallCompletedCallback(CallCompletedCallback callback);
7972 :
7973 : /**
7974 : * Set the PromiseHook callback for various promise lifecycle
7975 : * events.
7976 : */
7977 : void SetPromiseHook(PromiseHook hook);
7978 :
7979 : /**
7980 : * Set callback to notify about promise reject with no handler, or
7981 : * revocation of such a previous notification once the handler is added.
7982 : */
7983 : void SetPromiseRejectCallback(PromiseRejectCallback callback);
7984 :
7985 : /**
7986 : * Runs the Microtask Work Queue until empty
7987 : * Any exceptions thrown by microtask callbacks are swallowed.
7988 : */
7989 : void RunMicrotasks();
7990 :
7991 : /**
7992 : * Enqueues the callback to the Microtask Work Queue
7993 : */
7994 : void EnqueueMicrotask(Local<Function> microtask);
7995 :
7996 : /**
7997 : * Enqueues the callback to the Microtask Work Queue
7998 : */
7999 : void EnqueueMicrotask(MicrotaskCallback callback, void* data = nullptr);
8000 :
8001 : /**
8002 : * Controls how Microtasks are invoked. See MicrotasksPolicy for details.
8003 : */
8004 : void SetMicrotasksPolicy(MicrotasksPolicy policy);
8005 :
8006 : /**
8007 : * Returns the policy controlling how Microtasks are invoked.
8008 : */
8009 : MicrotasksPolicy GetMicrotasksPolicy() const;
8010 :
8011 : /**
8012 : * Adds a callback to notify the host application after
8013 : * microtasks were run. The callback is triggered by explicit RunMicrotasks
8014 : * call or automatic microtasks execution (see SetAutorunMicrotasks).
8015 : *
8016 : * Callback will trigger even if microtasks were attempted to run,
8017 : * but the microtasks queue was empty and no single microtask was actually
8018 : * executed.
8019 : *
8020 : * Executing scriptsinside the callback will not re-trigger microtasks and
8021 : * the callback.
8022 : */
8023 : void AddMicrotasksCompletedCallback(MicrotasksCompletedCallback callback);
8024 :
8025 : /**
8026 : * Removes callback that was installed by AddMicrotasksCompletedCallback.
8027 : */
8028 : void RemoveMicrotasksCompletedCallback(MicrotasksCompletedCallback callback);
8029 :
8030 : /**
8031 : * Sets a callback for counting the number of times a feature of V8 is used.
8032 : */
8033 : void SetUseCounterCallback(UseCounterCallback callback);
8034 :
8035 : /**
8036 : * Enables the host application to provide a mechanism for recording
8037 : * statistics counters.
8038 : */
8039 : void SetCounterFunction(CounterLookupCallback);
8040 :
8041 : /**
8042 : * Enables the host application to provide a mechanism for recording
8043 : * histograms. The CreateHistogram function returns a
8044 : * histogram which will later be passed to the AddHistogramSample
8045 : * function.
8046 : */
8047 : void SetCreateHistogramFunction(CreateHistogramCallback);
8048 : void SetAddHistogramSampleFunction(AddHistogramSampleCallback);
8049 :
8050 : /**
8051 : * Optional notification that the embedder is idle.
8052 : * V8 uses the notification to perform garbage collection.
8053 : * This call can be used repeatedly if the embedder remains idle.
8054 : * Returns true if the embedder should stop calling IdleNotificationDeadline
8055 : * until real work has been done. This indicates that V8 has done
8056 : * as much cleanup as it will be able to do.
8057 : *
8058 : * The deadline_in_seconds argument specifies the deadline V8 has to finish
8059 : * garbage collection work. deadline_in_seconds is compared with
8060 : * MonotonicallyIncreasingTime() and should be based on the same timebase as
8061 : * that function. There is no guarantee that the actual work will be done
8062 : * within the time limit.
8063 : */
8064 : bool IdleNotificationDeadline(double deadline_in_seconds);
8065 :
8066 : /**
8067 : * Optional notification that the system is running low on memory.
8068 : * V8 uses these notifications to attempt to free memory.
8069 : */
8070 : void LowMemoryNotification();
8071 :
8072 : /**
8073 : * Optional notification that a context has been disposed. V8 uses
8074 : * these notifications to guide the GC heuristic. Returns the number
8075 : * of context disposals - including this one - since the last time
8076 : * V8 had a chance to clean up.
8077 : *
8078 : * The optional parameter |dependant_context| specifies whether the disposed
8079 : * context was depending on state from other contexts or not.
8080 : */
8081 : int ContextDisposedNotification(bool dependant_context = true);
8082 :
8083 : /**
8084 : * Optional notification that the isolate switched to the foreground.
8085 : * V8 uses these notifications to guide heuristics.
8086 : */
8087 : void IsolateInForegroundNotification();
8088 :
8089 : /**
8090 : * Optional notification that the isolate switched to the background.
8091 : * V8 uses these notifications to guide heuristics.
8092 : */
8093 : void IsolateInBackgroundNotification();
8094 :
8095 : /**
8096 : * Optional notification which will enable the memory savings mode.
8097 : * V8 uses this notification to guide heuristics which may result in a
8098 : * smaller memory footprint at the cost of reduced runtime performance.
8099 : */
8100 : void EnableMemorySavingsMode();
8101 :
8102 : /**
8103 : * Optional notification which will disable the memory savings mode.
8104 : */
8105 : void DisableMemorySavingsMode();
8106 :
8107 : /**
8108 : * Optional notification to tell V8 the current performance requirements
8109 : * of the embedder based on RAIL.
8110 : * V8 uses these notifications to guide heuristics.
8111 : * This is an unfinished experimental feature. Semantics and implementation
8112 : * may change frequently.
8113 : */
8114 : void SetRAILMode(RAILMode rail_mode);
8115 :
8116 : /**
8117 : * Optional notification to tell V8 the current isolate is used for debugging
8118 : * and requires higher heap limit.
8119 : */
8120 : void IncreaseHeapLimitForDebugging();
8121 :
8122 : /**
8123 : * Restores the original heap limit after IncreaseHeapLimitForDebugging().
8124 : */
8125 : void RestoreOriginalHeapLimit();
8126 :
8127 : /**
8128 : * Returns true if the heap limit was increased for debugging and the
8129 : * original heap limit was not restored yet.
8130 : */
8131 : bool IsHeapLimitIncreasedForDebugging();
8132 :
8133 : /**
8134 : * Allows the host application to provide the address of a function that is
8135 : * notified each time code is added, moved or removed.
8136 : *
8137 : * \param options options for the JIT code event handler.
8138 : * \param event_handler the JIT code event handler, which will be invoked
8139 : * each time code is added, moved or removed.
8140 : * \note \p event_handler won't get notified of existent code.
8141 : * \note since code removal notifications are not currently issued, the
8142 : * \p event_handler may get notifications of code that overlaps earlier
8143 : * code notifications. This happens when code areas are reused, and the
8144 : * earlier overlapping code areas should therefore be discarded.
8145 : * \note the events passed to \p event_handler and the strings they point to
8146 : * are not guaranteed to live past each call. The \p event_handler must
8147 : * copy strings and other parameters it needs to keep around.
8148 : * \note the set of events declared in JitCodeEvent::EventType is expected to
8149 : * grow over time, and the JitCodeEvent structure is expected to accrue
8150 : * new members. The \p event_handler function must ignore event codes
8151 : * it does not recognize to maintain future compatibility.
8152 : * \note Use Isolate::CreateParams to get events for code executed during
8153 : * Isolate setup.
8154 : */
8155 : void SetJitCodeEventHandler(JitCodeEventOptions options,
8156 : JitCodeEventHandler event_handler);
8157 :
8158 : /**
8159 : * Modifies the stack limit for this Isolate.
8160 : *
8161 : * \param stack_limit An address beyond which the Vm's stack may not grow.
8162 : *
8163 : * \note If you are using threads then you should hold the V8::Locker lock
8164 : * while setting the stack limit and you must set a non-default stack
8165 : * limit separately for each thread.
8166 : */
8167 : void SetStackLimit(uintptr_t stack_limit);
8168 :
8169 : /**
8170 : * Returns a memory range that can potentially contain jitted code. Code for
8171 : * V8's 'builtins' will not be in this range if embedded builtins is enabled.
8172 : * Instead, see GetEmbeddedCodeRange.
8173 : *
8174 : * On Win64, embedders are advised to install function table callbacks for
8175 : * these ranges, as default SEH won't be able to unwind through jitted code.
8176 : *
8177 : * The first page of the code range is reserved for the embedder and is
8178 : * committed, writable, and executable.
8179 : *
8180 : * Might be empty on other platforms.
8181 : *
8182 : * https://code.google.com/p/v8/issues/detail?id=3598
8183 : */
8184 : void GetCodeRange(void** start, size_t* length_in_bytes);
8185 :
8186 : /**
8187 : * Returns the UnwindState necessary for use with the Unwinder API.
8188 : */
8189 : UnwindState GetUnwindState();
8190 :
8191 : /** Set the callback to invoke in case of fatal errors. */
8192 : void SetFatalErrorHandler(FatalErrorCallback that);
8193 :
8194 : /** Set the callback to invoke in case of OOM errors. */
8195 : void SetOOMErrorHandler(OOMErrorCallback that);
8196 :
8197 : /**
8198 : * Add a callback to invoke in case the heap size is close to the heap limit.
8199 : * If multiple callbacks are added, only the most recently added callback is
8200 : * invoked.
8201 : */
8202 : void AddNearHeapLimitCallback(NearHeapLimitCallback callback, void* data);
8203 :
8204 : /**
8205 : * Remove the given callback and restore the heap limit to the
8206 : * given limit. If the given limit is zero, then it is ignored.
8207 : * If the current heap size is greater than the given limit,
8208 : * then the heap limit is restored to the minimal limit that
8209 : * is possible for the current heap size.
8210 : */
8211 : void RemoveNearHeapLimitCallback(NearHeapLimitCallback callback,
8212 : size_t heap_limit);
8213 :
8214 : /**
8215 : * If the heap limit was changed by the NearHeapLimitCallback, then the
8216 : * initial heap limit will be restored once the heap size falls below the
8217 : * given threshold percentage of the initial heap limit.
8218 : * The threshold percentage is a number in (0.0, 1.0) range.
8219 : */
8220 : void AutomaticallyRestoreInitialHeapLimit(double threshold_percent = 0.5);
8221 :
8222 : /**
8223 : * Set the callback to invoke to check if code generation from
8224 : * strings should be allowed.
8225 : */
8226 : void SetAllowCodeGenerationFromStringsCallback(
8227 : AllowCodeGenerationFromStringsCallback callback);
8228 :
8229 : /**
8230 : * Set the callback to invoke to check if wasm code generation should
8231 : * be allowed.
8232 : */
8233 : void SetAllowWasmCodeGenerationCallback(
8234 : AllowWasmCodeGenerationCallback callback);
8235 :
8236 : /**
8237 : * Embedder over{ride|load} injection points for wasm APIs. The expectation
8238 : * is that the embedder sets them at most once.
8239 : */
8240 : void SetWasmModuleCallback(ExtensionCallback callback);
8241 : void SetWasmInstanceCallback(ExtensionCallback callback);
8242 :
8243 : V8_DEPRECATED(
8244 : "The callback set in SetWasmStreamingCallback is used now",
8245 : void SetWasmCompileStreamingCallback(ApiImplementationCallback callback));
8246 :
8247 : void SetWasmStreamingCallback(WasmStreamingCallback callback);
8248 :
8249 : void SetWasmThreadsEnabledCallback(WasmThreadsEnabledCallback callback);
8250 :
8251 : /**
8252 : * Check if V8 is dead and therefore unusable. This is the case after
8253 : * fatal errors such as out-of-memory situations.
8254 : */
8255 : bool IsDead();
8256 :
8257 : /**
8258 : * Adds a message listener (errors only).
8259 : *
8260 : * The same message listener can be added more than once and in that
8261 : * case it will be called more than once for each message.
8262 : *
8263 : * If data is specified, it will be passed to the callback when it is called.
8264 : * Otherwise, the exception object will be passed to the callback instead.
8265 : */
8266 : bool AddMessageListener(MessageCallback that,
8267 : Local<Value> data = Local<Value>());
8268 :
8269 : /**
8270 : * Adds a message listener.
8271 : *
8272 : * The same message listener can be added more than once and in that
8273 : * case it will be called more than once for each message.
8274 : *
8275 : * If data is specified, it will be passed to the callback when it is called.
8276 : * Otherwise, the exception object will be passed to the callback instead.
8277 : *
8278 : * A listener can listen for particular error levels by providing a mask.
8279 : */
8280 : bool AddMessageListenerWithErrorLevel(MessageCallback that,
8281 : int message_levels,
8282 : Local<Value> data = Local<Value>());
8283 :
8284 : /**
8285 : * Remove all message listeners from the specified callback function.
8286 : */
8287 : void RemoveMessageListeners(MessageCallback that);
8288 :
8289 : /** Callback function for reporting failed access checks.*/
8290 : void SetFailedAccessCheckCallbackFunction(FailedAccessCheckCallback);
8291 :
8292 : /**
8293 : * Tells V8 to capture current stack trace when uncaught exception occurs
8294 : * and report it to the message listeners. The option is off by default.
8295 : */
8296 : void SetCaptureStackTraceForUncaughtExceptions(
8297 : bool capture, int frame_limit = 10,
8298 : StackTrace::StackTraceOptions options = StackTrace::kOverview);
8299 :
8300 : /**
8301 : * Iterates through all external resources referenced from current isolate
8302 : * heap. GC is not invoked prior to iterating, therefore there is no
8303 : * guarantee that visited objects are still alive.
8304 : */
8305 : void VisitExternalResources(ExternalResourceVisitor* visitor);
8306 :
8307 : /**
8308 : * Iterates through all the persistent handles in the current isolate's heap
8309 : * that have class_ids.
8310 : */
8311 : void VisitHandlesWithClassIds(PersistentHandleVisitor* visitor);
8312 :
8313 : /**
8314 : * Iterates through all the persistent handles in the current isolate's heap
8315 : * that have class_ids and are candidates to be marked as partially dependent
8316 : * handles. This will visit handles to young objects created since the last
8317 : * garbage collection but is free to visit an arbitrary superset of these
8318 : * objects.
8319 : */
8320 : void VisitHandlesForPartialDependence(PersistentHandleVisitor* visitor);
8321 :
8322 : /**
8323 : * Iterates through all the persistent handles in the current isolate's heap
8324 : * that have class_ids and are weak to be marked as inactive if there is no
8325 : * pending activity for the handle.
8326 : */
8327 : void VisitWeakHandles(PersistentHandleVisitor* visitor);
8328 :
8329 : /**
8330 : * Check if this isolate is in use.
8331 : * True if at least one thread Enter'ed this isolate.
8332 : */
8333 : bool IsInUse();
8334 :
8335 : /**
8336 : * Set whether calling Atomics.wait (a function that may block) is allowed in
8337 : * this isolate. This can also be configured via
8338 : * CreateParams::allow_atomics_wait.
8339 : */
8340 : void SetAllowAtomicsWait(bool allow);
8341 :
8342 : Isolate() = delete;
8343 : ~Isolate() = delete;
8344 : Isolate(const Isolate&) = delete;
8345 : Isolate& operator=(const Isolate&) = delete;
8346 : // Deleting operator new and delete here is allowed as ctor and dtor is also
8347 : // deleted.
8348 : void* operator new(size_t size) = delete;
8349 : void* operator new[](size_t size) = delete;
8350 : void operator delete(void*, size_t) = delete;
8351 : void operator delete[](void*, size_t) = delete;
8352 :
8353 : private:
8354 : template <class K, class V, class Traits>
8355 : friend class PersistentValueMapBase;
8356 :
8357 : internal::Address* GetDataFromSnapshotOnce(size_t index);
8358 : void ReportExternalAllocationLimitReached();
8359 : void CheckMemoryPressure();
8360 : };
8361 :
8362 : class V8_EXPORT StartupData {
8363 : public:
8364 : const char* data;
8365 : int raw_size;
8366 : };
8367 :
8368 :
8369 : /**
8370 : * EntropySource is used as a callback function when v8 needs a source
8371 : * of entropy.
8372 : */
8373 : typedef bool (*EntropySource)(unsigned char* buffer, size_t length);
8374 :
8375 : /**
8376 : * ReturnAddressLocationResolver is used as a callback function when v8 is
8377 : * resolving the location of a return address on the stack. Profilers that
8378 : * change the return address on the stack can use this to resolve the stack
8379 : * location to wherever the profiler stashed the original return address.
8380 : *
8381 : * \param return_addr_location A location on stack where a machine
8382 : * return address resides.
8383 : * \returns Either return_addr_location, or else a pointer to the profiler's
8384 : * copy of the original return address.
8385 : *
8386 : * \note The resolver function must not cause garbage collection.
8387 : */
8388 : typedef uintptr_t (*ReturnAddressLocationResolver)(
8389 : uintptr_t return_addr_location);
8390 :
8391 :
8392 : /**
8393 : * Container class for static utility functions.
8394 : */
8395 : class V8_EXPORT V8 {
8396 : public:
8397 : /**
8398 : * Hand startup data to V8, in case the embedder has chosen to build
8399 : * V8 with external startup data.
8400 : *
8401 : * Note:
8402 : * - By default the startup data is linked into the V8 library, in which
8403 : * case this function is not meaningful.
8404 : * - If this needs to be called, it needs to be called before V8
8405 : * tries to make use of its built-ins.
8406 : * - To avoid unnecessary copies of data, V8 will point directly into the
8407 : * given data blob, so pretty please keep it around until V8 exit.
8408 : * - Compression of the startup blob might be useful, but needs to
8409 : * handled entirely on the embedders' side.
8410 : * - The call will abort if the data is invalid.
8411 : */
8412 : static void SetNativesDataBlob(StartupData* startup_blob);
8413 : static void SetSnapshotDataBlob(StartupData* startup_blob);
8414 :
8415 : /** Set the callback to invoke in case of Dcheck failures. */
8416 : static void SetDcheckErrorHandler(DcheckErrorCallback that);
8417 :
8418 :
8419 : /**
8420 : * Sets V8 flags from a string.
8421 : */
8422 : static void SetFlagsFromString(const char* str, int length);
8423 :
8424 : /**
8425 : * Sets V8 flags from the command line.
8426 : */
8427 : static void SetFlagsFromCommandLine(int* argc,
8428 : char** argv,
8429 : bool remove_flags);
8430 :
8431 : /** Get the version string. */
8432 : static const char* GetVersion();
8433 :
8434 : /**
8435 : * Initializes V8. This function needs to be called before the first Isolate
8436 : * is created. It always returns true.
8437 : */
8438 : static bool Initialize();
8439 :
8440 : /**
8441 : * Allows the host application to provide a callback which can be used
8442 : * as a source of entropy for random number generators.
8443 : */
8444 : static void SetEntropySource(EntropySource source);
8445 :
8446 : /**
8447 : * Allows the host application to provide a callback that allows v8 to
8448 : * cooperate with a profiler that rewrites return addresses on stack.
8449 : */
8450 : static void SetReturnAddressLocationResolver(
8451 : ReturnAddressLocationResolver return_address_resolver);
8452 :
8453 : /**
8454 : * Releases any resources used by v8 and stops any utility threads
8455 : * that may be running. Note that disposing v8 is permanent, it
8456 : * cannot be reinitialized.
8457 : *
8458 : * It should generally not be necessary to dispose v8 before exiting
8459 : * a process, this should happen automatically. It is only necessary
8460 : * to use if the process needs the resources taken up by v8.
8461 : */
8462 : static bool Dispose();
8463 :
8464 : /**
8465 : * Initialize the ICU library bundled with V8. The embedder should only
8466 : * invoke this method when using the bundled ICU. Returns true on success.
8467 : *
8468 : * If V8 was compiled with the ICU data in an external file, the location
8469 : * of the data file has to be provided.
8470 : */
8471 : static bool InitializeICU(const char* icu_data_file = nullptr);
8472 :
8473 : /**
8474 : * Initialize the ICU library bundled with V8. The embedder should only
8475 : * invoke this method when using the bundled ICU. If V8 was compiled with
8476 : * the ICU data in an external file and when the default location of that
8477 : * file should be used, a path to the executable must be provided.
8478 : * Returns true on success.
8479 : *
8480 : * The default is a file called icudtl.dat side-by-side with the executable.
8481 : *
8482 : * Optionally, the location of the data file can be provided to override the
8483 : * default.
8484 : */
8485 : static bool InitializeICUDefaultLocation(const char* exec_path,
8486 : const char* icu_data_file = nullptr);
8487 :
8488 : /**
8489 : * Initialize the external startup data. The embedder only needs to
8490 : * invoke this method when external startup data was enabled in a build.
8491 : *
8492 : * If V8 was compiled with the startup data in an external file, then
8493 : * V8 needs to be given those external files during startup. There are
8494 : * three ways to do this:
8495 : * - InitializeExternalStartupData(const char*)
8496 : * This will look in the given directory for files "natives_blob.bin"
8497 : * and "snapshot_blob.bin" - which is what the default build calls them.
8498 : * - InitializeExternalStartupData(const char*, const char*)
8499 : * As above, but will directly use the two given file names.
8500 : * - Call SetNativesDataBlob, SetNativesDataBlob.
8501 : * This will read the blobs from the given data structures and will
8502 : * not perform any file IO.
8503 : */
8504 : static void InitializeExternalStartupData(const char* directory_path);
8505 : static void InitializeExternalStartupData(const char* natives_blob,
8506 : const char* snapshot_blob);
8507 : /**
8508 : * Sets the v8::Platform to use. This should be invoked before V8 is
8509 : * initialized.
8510 : */
8511 : static void InitializePlatform(Platform* platform);
8512 :
8513 : /**
8514 : * Clears all references to the v8::Platform. This should be invoked after
8515 : * V8 was disposed.
8516 : */
8517 : static void ShutdownPlatform();
8518 :
8519 : #if V8_OS_POSIX
8520 : /**
8521 : * Give the V8 signal handler a chance to handle a fault.
8522 : *
8523 : * This function determines whether a memory access violation can be recovered
8524 : * by V8. If so, it will return true and modify context to return to a code
8525 : * fragment that can recover from the fault. Otherwise, TryHandleSignal will
8526 : * return false.
8527 : *
8528 : * The parameters to this function correspond to those passed to a Linux
8529 : * signal handler.
8530 : *
8531 : * \param signal_number The signal number.
8532 : *
8533 : * \param info A pointer to the siginfo_t structure provided to the signal
8534 : * handler.
8535 : *
8536 : * \param context The third argument passed to the Linux signal handler, which
8537 : * points to a ucontext_t structure.
8538 : */
8539 : V8_DEPRECATE_SOON("Use TryHandleWebAssemblyTrapPosix",
8540 : static bool TryHandleSignal(int signal_number, void* info,
8541 : void* context));
8542 : #endif // V8_OS_POSIX
8543 :
8544 : /**
8545 : * Enable the default signal handler rather than using one provided by the
8546 : * embedder.
8547 : */
8548 : V8_DEPRECATED("Use EnableWebAssemblyTrapHandler",
8549 : static bool RegisterDefaultSignalHandler());
8550 :
8551 : /**
8552 : * Activate trap-based bounds checking for WebAssembly.
8553 : *
8554 : * \param use_v8_signal_handler Whether V8 should install its own signal
8555 : * handler or rely on the embedder's.
8556 : */
8557 : static bool EnableWebAssemblyTrapHandler(bool use_v8_signal_handler);
8558 :
8559 : private:
8560 : V8();
8561 :
8562 : static internal::Address* GlobalizeReference(internal::Isolate* isolate,
8563 : internal::Address* handle);
8564 : static internal::Address* CopyPersistent(internal::Address* handle);
8565 : static void DisposeGlobal(internal::Address* global_handle);
8566 : static void MakeWeak(internal::Address* location, void* data,
8567 : WeakCallbackInfo<void>::Callback weak_callback,
8568 : WeakCallbackType type);
8569 : static void MakeWeak(internal::Address** location_addr);
8570 : static void* ClearWeak(internal::Address* location);
8571 : static void AnnotateStrongRetainer(internal::Address* location,
8572 : const char* label);
8573 : static Value* Eternalize(Isolate* isolate, Value* handle);
8574 :
8575 : static void RegisterExternallyReferencedObject(internal::Address* location,
8576 : internal::Isolate* isolate);
8577 :
8578 : template <class K, class V, class T>
8579 : friend class PersistentValueMapBase;
8580 :
8581 : static void FromJustIsNothing();
8582 : static void ToLocalEmpty();
8583 : static void InternalFieldOutOfBounds(int index);
8584 : template <class T> friend class Local;
8585 : template <class T>
8586 : friend class MaybeLocal;
8587 : template <class T>
8588 : friend class Maybe;
8589 : template <class T>
8590 : friend class WeakCallbackInfo;
8591 : template <class T> friend class Eternal;
8592 : template <class T> friend class PersistentBase;
8593 : template <class T, class M> friend class Persistent;
8594 : friend class Context;
8595 : };
8596 :
8597 : /**
8598 : * Helper class to create a snapshot data blob.
8599 : */
8600 : class V8_EXPORT SnapshotCreator {
8601 : public:
8602 : enum class FunctionCodeHandling { kClear, kKeep };
8603 :
8604 : /**
8605 : * Initialize and enter an isolate, and set it up for serialization.
8606 : * The isolate is either created from scratch or from an existing snapshot.
8607 : * The caller keeps ownership of the argument snapshot.
8608 : * \param existing_blob existing snapshot from which to create this one.
8609 : * \param external_references a null-terminated array of external references
8610 : * that must be equivalent to CreateParams::external_references.
8611 : */
8612 : SnapshotCreator(Isolate* isolate,
8613 : const intptr_t* external_references = nullptr,
8614 : StartupData* existing_blob = nullptr);
8615 :
8616 : /**
8617 : * Create and enter an isolate, and set it up for serialization.
8618 : * The isolate is either created from scratch or from an existing snapshot.
8619 : * The caller keeps ownership of the argument snapshot.
8620 : * \param existing_blob existing snapshot from which to create this one.
8621 : * \param external_references a null-terminated array of external references
8622 : * that must be equivalent to CreateParams::external_references.
8623 : */
8624 : SnapshotCreator(const intptr_t* external_references = nullptr,
8625 : StartupData* existing_blob = nullptr);
8626 :
8627 : ~SnapshotCreator();
8628 :
8629 : /**
8630 : * \returns the isolate prepared by the snapshot creator.
8631 : */
8632 : Isolate* GetIsolate();
8633 :
8634 : /**
8635 : * Set the default context to be included in the snapshot blob.
8636 : * The snapshot will not contain the global proxy, and we expect one or a
8637 : * global object template to create one, to be provided upon deserialization.
8638 : *
8639 : * \param callback optional callback to serialize internal fields.
8640 : */
8641 : void SetDefaultContext(Local<Context> context,
8642 : SerializeInternalFieldsCallback callback =
8643 : SerializeInternalFieldsCallback());
8644 :
8645 : /**
8646 : * Add additional context to be included in the snapshot blob.
8647 : * The snapshot will include the global proxy.
8648 : *
8649 : * \param callback optional callback to serialize internal fields.
8650 : *
8651 : * \returns the index of the context in the snapshot blob.
8652 : */
8653 : size_t AddContext(Local<Context> context,
8654 : SerializeInternalFieldsCallback callback =
8655 : SerializeInternalFieldsCallback());
8656 :
8657 : /**
8658 : * Add a template to be included in the snapshot blob.
8659 : * \returns the index of the template in the snapshot blob.
8660 : */
8661 : size_t AddTemplate(Local<Template> template_obj);
8662 :
8663 : /**
8664 : * Attach arbitrary V8::Data to the context snapshot, which can be retrieved
8665 : * via Context::GetDataFromSnapshot after deserialization. This data does not
8666 : * survive when a new snapshot is created from an existing snapshot.
8667 : * \returns the index for retrieval.
8668 : */
8669 : template <class T>
8670 : V8_INLINE size_t AddData(Local<Context> context, Local<T> object);
8671 :
8672 : /**
8673 : * Attach arbitrary V8::Data to the isolate snapshot, which can be retrieved
8674 : * via Isolate::GetDataFromSnapshot after deserialization. This data does not
8675 : * survive when a new snapshot is created from an existing snapshot.
8676 : * \returns the index for retrieval.
8677 : */
8678 : template <class T>
8679 : V8_INLINE size_t AddData(Local<T> object);
8680 :
8681 : /**
8682 : * Created a snapshot data blob.
8683 : * This must not be called from within a handle scope.
8684 : * \param function_code_handling whether to include compiled function code
8685 : * in the snapshot.
8686 : * \returns { nullptr, 0 } on failure, and a startup snapshot on success. The
8687 : * caller acquires ownership of the data array in the return value.
8688 : */
8689 : StartupData CreateBlob(FunctionCodeHandling function_code_handling);
8690 :
8691 : // Disallow copying and assigning.
8692 : SnapshotCreator(const SnapshotCreator&) = delete;
8693 : void operator=(const SnapshotCreator&) = delete;
8694 :
8695 : private:
8696 : size_t AddData(Local<Context> context, internal::Address object);
8697 : size_t AddData(internal::Address object);
8698 :
8699 : void* data_;
8700 : };
8701 :
8702 : /**
8703 : * A simple Maybe type, representing an object which may or may not have a
8704 : * value, see https://hackage.haskell.org/package/base/docs/Data-Maybe.html.
8705 : *
8706 : * If an API method returns a Maybe<>, the API method can potentially fail
8707 : * either because an exception is thrown, or because an exception is pending,
8708 : * e.g. because a previous API call threw an exception that hasn't been caught
8709 : * yet, or because a TerminateExecution exception was thrown. In that case, a
8710 : * "Nothing" value is returned.
8711 : */
8712 : template <class T>
8713 72066 : class Maybe {
8714 : public:
8715 175 : V8_INLINE bool IsNothing() const { return !has_value_; }
8716 : V8_INLINE bool IsJust() const { return has_value_; }
8717 :
8718 : /**
8719 : * An alias for |FromJust|. Will crash if the Maybe<> is nothing.
8720 : */
8721 : V8_INLINE T ToChecked() const { return FromJust(); }
8722 :
8723 : /**
8724 : * Short-hand for ToChecked(), which doesn't return a value. To be used, where
8725 : * the actual value of the Maybe is not needed like Object::Set.
8726 : */
8727 : V8_INLINE void Check() const {
8728 : if (V8_UNLIKELY(!IsJust())) V8::FromJustIsNothing();
8729 : }
8730 :
8731 : /**
8732 : * Converts this Maybe<> to a value of type T. If this Maybe<> is
8733 : * nothing (empty), |false| is returned and |out| is left untouched.
8734 : */
8735 8406739 : V8_WARN_UNUSED_RESULT V8_INLINE bool To(T* out) const {
8736 8382146 : if (V8_LIKELY(IsJust())) *out = value_;
8737 : return IsJust();
8738 : }
8739 :
8740 : /**
8741 : * Converts this Maybe<> to a value of type T. If this Maybe<> is
8742 : * nothing (empty), V8 will crash the process.
8743 : */
8744 5554879 : V8_INLINE T FromJust() const {
8745 153098519 : if (V8_UNLIKELY(!IsJust())) V8::FromJustIsNothing();
8746 138660675 : return value_;
8747 : }
8748 :
8749 : /**
8750 : * Converts this Maybe<> to a value of type T, using a default value if this
8751 : * Maybe<> is nothing (empty).
8752 : */
8753 : V8_INLINE T FromMaybe(const T& default_value) const {
8754 406981 : return has_value_ ? value_ : default_value;
8755 : }
8756 :
8757 169 : V8_INLINE bool operator==(const Maybe& other) const {
8758 : return (IsJust() == other.IsJust()) &&
8759 338 : (!IsJust() || FromJust() == other.FromJust());
8760 : }
8761 :
8762 : V8_INLINE bool operator!=(const Maybe& other) const {
8763 : return !operator==(other);
8764 : }
8765 :
8766 : private:
8767 30509 : Maybe() : has_value_(false) {}
8768 16132535 : explicit Maybe(const T& t) : has_value_(true), value_(t) {}
8769 :
8770 : bool has_value_;
8771 : T value_;
8772 :
8773 : template <class U>
8774 : friend Maybe<U> Nothing();
8775 : template <class U>
8776 : friend Maybe<U> Just(const U& u);
8777 : };
8778 :
8779 : template <class T>
8780 : inline Maybe<T> Nothing() {
8781 : return Maybe<T>();
8782 : }
8783 :
8784 : template <class T>
8785 1196211 : inline Maybe<T> Just(const T& t) {
8786 1196211 : return Maybe<T>(t);
8787 : }
8788 :
8789 : // A template specialization of Maybe<T> for the case of T = void.
8790 : template <>
8791 : class Maybe<void> {
8792 : public:
8793 : V8_INLINE bool IsNothing() const { return !is_valid_; }
8794 : V8_INLINE bool IsJust() const { return is_valid_; }
8795 :
8796 : V8_INLINE bool operator==(const Maybe& other) const {
8797 : return IsJust() == other.IsJust();
8798 : }
8799 :
8800 : V8_INLINE bool operator!=(const Maybe& other) const {
8801 : return !operator==(other);
8802 : }
8803 :
8804 : private:
8805 : struct JustTag {};
8806 :
8807 : Maybe() : is_valid_(false) {}
8808 : explicit Maybe(JustTag) : is_valid_(true) {}
8809 :
8810 : bool is_valid_;
8811 :
8812 : template <class U>
8813 : friend Maybe<U> Nothing();
8814 : friend Maybe<void> JustVoid();
8815 : };
8816 :
8817 : inline Maybe<void> JustVoid() { return Maybe<void>(Maybe<void>::JustTag()); }
8818 :
8819 : /**
8820 : * An external exception handler.
8821 : */
8822 : class V8_EXPORT TryCatch {
8823 : public:
8824 : /**
8825 : * Creates a new try/catch block and registers it with v8. Note that
8826 : * all TryCatch blocks should be stack allocated because the memory
8827 : * location itself is compared against JavaScript try/catch blocks.
8828 : */
8829 : explicit TryCatch(Isolate* isolate);
8830 :
8831 : /**
8832 : * Unregisters and deletes this try/catch block.
8833 : */
8834 : ~TryCatch();
8835 :
8836 : /**
8837 : * Returns true if an exception has been caught by this try/catch block.
8838 : */
8839 : bool HasCaught() const;
8840 :
8841 : /**
8842 : * For certain types of exceptions, it makes no sense to continue execution.
8843 : *
8844 : * If CanContinue returns false, the correct action is to perform any C++
8845 : * cleanup needed and then return. If CanContinue returns false and
8846 : * HasTerminated returns true, it is possible to call
8847 : * CancelTerminateExecution in order to continue calling into the engine.
8848 : */
8849 : bool CanContinue() const;
8850 :
8851 : /**
8852 : * Returns true if an exception has been caught due to script execution
8853 : * being terminated.
8854 : *
8855 : * There is no JavaScript representation of an execution termination
8856 : * exception. Such exceptions are thrown when the TerminateExecution
8857 : * methods are called to terminate a long-running script.
8858 : *
8859 : * If such an exception has been thrown, HasTerminated will return true,
8860 : * indicating that it is possible to call CancelTerminateExecution in order
8861 : * to continue calling into the engine.
8862 : */
8863 : bool HasTerminated() const;
8864 :
8865 : /**
8866 : * Throws the exception caught by this TryCatch in a way that avoids
8867 : * it being caught again by this same TryCatch. As with ThrowException
8868 : * it is illegal to execute any JavaScript operations after calling
8869 : * ReThrow; the caller must return immediately to where the exception
8870 : * is caught.
8871 : */
8872 : Local<Value> ReThrow();
8873 :
8874 : /**
8875 : * Returns the exception caught by this try/catch block. If no exception has
8876 : * been caught an empty handle is returned.
8877 : *
8878 : * The returned handle is valid until this TryCatch block has been destroyed.
8879 : */
8880 : Local<Value> Exception() const;
8881 :
8882 : /**
8883 : * Returns the .stack property of the thrown object. If no .stack
8884 : * property is present an empty handle is returned.
8885 : */
8886 : V8_WARN_UNUSED_RESULT MaybeLocal<Value> StackTrace(
8887 : Local<Context> context) const;
8888 :
8889 : /**
8890 : * Returns the message associated with this exception. If there is
8891 : * no message associated an empty handle is returned.
8892 : *
8893 : * The returned handle is valid until this TryCatch block has been
8894 : * destroyed.
8895 : */
8896 : Local<v8::Message> Message() const;
8897 :
8898 : /**
8899 : * Clears any exceptions that may have been caught by this try/catch block.
8900 : * After this method has been called, HasCaught() will return false. Cancels
8901 : * the scheduled exception if it is caught and ReThrow() is not called before.
8902 : *
8903 : * It is not necessary to clear a try/catch block before using it again; if
8904 : * another exception is thrown the previously caught exception will just be
8905 : * overwritten. However, it is often a good idea since it makes it easier
8906 : * to determine which operation threw a given exception.
8907 : */
8908 : void Reset();
8909 :
8910 : /**
8911 : * Set verbosity of the external exception handler.
8912 : *
8913 : * By default, exceptions that are caught by an external exception
8914 : * handler are not reported. Call SetVerbose with true on an
8915 : * external exception handler to have exceptions caught by the
8916 : * handler reported as if they were not caught.
8917 : */
8918 : void SetVerbose(bool value);
8919 :
8920 : /**
8921 : * Returns true if verbosity is enabled.
8922 : */
8923 : bool IsVerbose() const;
8924 :
8925 : /**
8926 : * Set whether or not this TryCatch should capture a Message object
8927 : * which holds source information about where the exception
8928 : * occurred. True by default.
8929 : */
8930 : void SetCaptureMessage(bool value);
8931 :
8932 : /**
8933 : * There are cases when the raw address of C++ TryCatch object cannot be
8934 : * used for comparisons with addresses into the JS stack. The cases are:
8935 : * 1) ARM, ARM64 and MIPS simulators which have separate JS stack.
8936 : * 2) Address sanitizer allocates local C++ object in the heap when
8937 : * UseAfterReturn mode is enabled.
8938 : * This method returns address that can be used for comparisons with
8939 : * addresses into the JS stack. When neither simulator nor ASAN's
8940 : * UseAfterReturn is enabled, then the address returned will be the address
8941 : * of the C++ try catch handler itself.
8942 : */
8943 : static void* JSStackComparableAddress(TryCatch* handler) {
8944 211422 : if (handler == nullptr) return nullptr;
8945 202934 : return handler->js_stack_comparable_address_;
8946 : }
8947 :
8948 : TryCatch(const TryCatch&) = delete;
8949 : void operator=(const TryCatch&) = delete;
8950 :
8951 : private:
8952 : // Declaring operator new and delete as deleted is not spec compliant.
8953 : // Therefore declare them private instead to disable dynamic alloc
8954 : void* operator new(size_t size);
8955 : void* operator new[](size_t size);
8956 : void operator delete(void*, size_t);
8957 : void operator delete[](void*, size_t);
8958 :
8959 : void ResetInternal();
8960 :
8961 : internal::Isolate* isolate_;
8962 : TryCatch* next_;
8963 : void* exception_;
8964 : void* message_obj_;
8965 : void* js_stack_comparable_address_;
8966 : bool is_verbose_ : 1;
8967 : bool can_continue_ : 1;
8968 : bool capture_message_ : 1;
8969 : bool rethrow_ : 1;
8970 : bool has_terminated_ : 1;
8971 :
8972 : friend class internal::Isolate;
8973 : };
8974 :
8975 :
8976 : // --- Context ---
8977 :
8978 :
8979 : /**
8980 : * A container for extension names.
8981 : */
8982 : class V8_EXPORT ExtensionConfiguration {
8983 : public:
8984 91891 : ExtensionConfiguration() : name_count_(0), names_(nullptr) {}
8985 : ExtensionConfiguration(int name_count, const char* names[])
8986 436 : : name_count_(name_count), names_(names) { }
8987 :
8988 : const char** begin() const { return &names_[0]; }
8989 93406 : const char** end() const { return &names_[name_count_]; }
8990 :
8991 : private:
8992 : const int name_count_;
8993 : const char** names_;
8994 : };
8995 :
8996 : /**
8997 : * A sandboxed execution context with its own set of built-in objects
8998 : * and functions.
8999 : */
9000 : class V8_EXPORT Context {
9001 : public:
9002 : /**
9003 : * Returns the global proxy object.
9004 : *
9005 : * Global proxy object is a thin wrapper whose prototype points to actual
9006 : * context's global object with the properties like Object, etc. This is done
9007 : * that way for security reasons (for more details see
9008 : * https://wiki.mozilla.org/Gecko:SplitWindow).
9009 : *
9010 : * Please note that changes to global proxy object prototype most probably
9011 : * would break VM---v8 expects only global object as a prototype of global
9012 : * proxy object.
9013 : */
9014 : Local<Object> Global();
9015 :
9016 : /**
9017 : * Detaches the global object from its context before
9018 : * the global object can be reused to create a new context.
9019 : */
9020 : void DetachGlobal();
9021 :
9022 : /**
9023 : * Creates a new context and returns a handle to the newly allocated
9024 : * context.
9025 : *
9026 : * \param isolate The isolate in which to create the context.
9027 : *
9028 : * \param extensions An optional extension configuration containing
9029 : * the extensions to be installed in the newly created context.
9030 : *
9031 : * \param global_template An optional object template from which the
9032 : * global object for the newly created context will be created.
9033 : *
9034 : * \param global_object An optional global object to be reused for
9035 : * the newly created context. This global object must have been
9036 : * created by a previous call to Context::New with the same global
9037 : * template. The state of the global object will be completely reset
9038 : * and only object identify will remain.
9039 : */
9040 : static Local<Context> New(
9041 : Isolate* isolate, ExtensionConfiguration* extensions = nullptr,
9042 : MaybeLocal<ObjectTemplate> global_template = MaybeLocal<ObjectTemplate>(),
9043 : MaybeLocal<Value> global_object = MaybeLocal<Value>(),
9044 : DeserializeInternalFieldsCallback internal_fields_deserializer =
9045 : DeserializeInternalFieldsCallback());
9046 :
9047 : /**
9048 : * Create a new context from a (non-default) context snapshot. There
9049 : * is no way to provide a global object template since we do not create
9050 : * a new global object from template, but we can reuse a global object.
9051 : *
9052 : * \param isolate See v8::Context::New.
9053 : *
9054 : * \param context_snapshot_index The index of the context snapshot to
9055 : * deserialize from. Use v8::Context::New for the default snapshot.
9056 : *
9057 : * \param embedder_fields_deserializer Optional callback to deserialize
9058 : * internal fields. It should match the SerializeInternalFieldCallback used
9059 : * to serialize.
9060 : *
9061 : * \param extensions See v8::Context::New.
9062 : *
9063 : * \param global_object See v8::Context::New.
9064 : */
9065 :
9066 : static MaybeLocal<Context> FromSnapshot(
9067 : Isolate* isolate, size_t context_snapshot_index,
9068 : DeserializeInternalFieldsCallback embedder_fields_deserializer =
9069 : DeserializeInternalFieldsCallback(),
9070 : ExtensionConfiguration* extensions = nullptr,
9071 : MaybeLocal<Value> global_object = MaybeLocal<Value>());
9072 :
9073 : /**
9074 : * Returns an global object that isn't backed by an actual context.
9075 : *
9076 : * The global template needs to have access checks with handlers installed.
9077 : * If an existing global object is passed in, the global object is detached
9078 : * from its context.
9079 : *
9080 : * Note that this is different from a detached context where all accesses to
9081 : * the global proxy will fail. Instead, the access check handlers are invoked.
9082 : *
9083 : * It is also not possible to detach an object returned by this method.
9084 : * Instead, the access check handlers need to return nothing to achieve the
9085 : * same effect.
9086 : *
9087 : * It is possible, however, to create a new context from the global object
9088 : * returned by this method.
9089 : */
9090 : static MaybeLocal<Object> NewRemoteContext(
9091 : Isolate* isolate, Local<ObjectTemplate> global_template,
9092 : MaybeLocal<Value> global_object = MaybeLocal<Value>());
9093 :
9094 : /**
9095 : * Sets the security token for the context. To access an object in
9096 : * another context, the security tokens must match.
9097 : */
9098 : void SetSecurityToken(Local<Value> token);
9099 :
9100 : /** Restores the security token to the default value. */
9101 : void UseDefaultSecurityToken();
9102 :
9103 : /** Returns the security token of this context.*/
9104 : Local<Value> GetSecurityToken();
9105 :
9106 : /**
9107 : * Enter this context. After entering a context, all code compiled
9108 : * and run is compiled and run in this context. If another context
9109 : * is already entered, this old context is saved so it can be
9110 : * restored when the new context is exited.
9111 : */
9112 : void Enter();
9113 :
9114 : /**
9115 : * Exit this context. Exiting the current context restores the
9116 : * context that was in place when entering the current context.
9117 : */
9118 : void Exit();
9119 :
9120 : /** Returns an isolate associated with a current context. */
9121 : Isolate* GetIsolate();
9122 :
9123 : /**
9124 : * The field at kDebugIdIndex used to be reserved for the inspector.
9125 : * It now serves no purpose.
9126 : */
9127 : enum EmbedderDataFields { kDebugIdIndex = 0 };
9128 :
9129 : /**
9130 : * Return the number of fields allocated for embedder data.
9131 : */
9132 : uint32_t GetNumberOfEmbedderDataFields();
9133 :
9134 : /**
9135 : * Gets the embedder data with the given index, which must have been set by a
9136 : * previous call to SetEmbedderData with the same index.
9137 : */
9138 : V8_INLINE Local<Value> GetEmbedderData(int index);
9139 :
9140 : /**
9141 : * Gets the binding object used by V8 extras. Extra natives get a reference
9142 : * to this object and can use it to "export" functionality by adding
9143 : * properties. Extra natives can also "import" functionality by accessing
9144 : * properties added by the embedder using the V8 API.
9145 : */
9146 : Local<Object> GetExtrasBindingObject();
9147 :
9148 : /**
9149 : * Sets the embedder data with the given index, growing the data as
9150 : * needed. Note that index 0 currently has a special meaning for Chrome's
9151 : * debugger.
9152 : */
9153 : void SetEmbedderData(int index, Local<Value> value);
9154 :
9155 : /**
9156 : * Gets a 2-byte-aligned native pointer from the embedder data with the given
9157 : * index, which must have been set by a previous call to
9158 : * SetAlignedPointerInEmbedderData with the same index. Note that index 0
9159 : * currently has a special meaning for Chrome's debugger.
9160 : */
9161 : V8_INLINE void* GetAlignedPointerFromEmbedderData(int index);
9162 :
9163 : /**
9164 : * Sets a 2-byte-aligned native pointer in the embedder data with the given
9165 : * index, growing the data as needed. Note that index 0 currently has a
9166 : * special meaning for Chrome's debugger.
9167 : */
9168 : void SetAlignedPointerInEmbedderData(int index, void* value);
9169 :
9170 : /**
9171 : * Control whether code generation from strings is allowed. Calling
9172 : * this method with false will disable 'eval' and the 'Function'
9173 : * constructor for code running in this context. If 'eval' or the
9174 : * 'Function' constructor are used an exception will be thrown.
9175 : *
9176 : * If code generation from strings is not allowed the
9177 : * V8::AllowCodeGenerationFromStrings callback will be invoked if
9178 : * set before blocking the call to 'eval' or the 'Function'
9179 : * constructor. If that callback returns true, the call will be
9180 : * allowed, otherwise an exception will be thrown. If no callback is
9181 : * set an exception will be thrown.
9182 : */
9183 : void AllowCodeGenerationFromStrings(bool allow);
9184 :
9185 : /**
9186 : * Returns true if code generation from strings is allowed for the context.
9187 : * For more details see AllowCodeGenerationFromStrings(bool) documentation.
9188 : */
9189 : bool IsCodeGenerationFromStringsAllowed();
9190 :
9191 : /**
9192 : * Sets the error description for the exception that is thrown when
9193 : * code generation from strings is not allowed and 'eval' or the 'Function'
9194 : * constructor are called.
9195 : */
9196 : void SetErrorMessageForCodeGenerationFromStrings(Local<String> message);
9197 :
9198 : /**
9199 : * Return data that was previously attached to the context snapshot via
9200 : * SnapshotCreator, and removes the reference to it.
9201 : * Repeated call with the same index returns an empty MaybeLocal.
9202 : */
9203 : template <class T>
9204 : V8_INLINE MaybeLocal<T> GetDataFromSnapshotOnce(size_t index);
9205 :
9206 : /**
9207 : * Stack-allocated class which sets the execution context for all
9208 : * operations executed within a local scope.
9209 : */
9210 : class Scope {
9211 : public:
9212 825 : explicit V8_INLINE Scope(Local<Context> context) : context_(context) {
9213 4135475 : context_->Enter();
9214 : }
9215 4132054 : V8_INLINE ~Scope() { context_->Exit(); }
9216 :
9217 : private:
9218 : Local<Context> context_;
9219 : };
9220 :
9221 : /**
9222 : * Stack-allocated class to support the backup incumbent settings object
9223 : * stack.
9224 : * https://html.spec.whatwg.org/multipage/webappapis.html#backup-incumbent-settings-object-stack
9225 : */
9226 : class V8_EXPORT BackupIncumbentScope final {
9227 : public:
9228 : /**
9229 : * |backup_incumbent_context| is pushed onto the backup incumbent settings
9230 : * object stack.
9231 : */
9232 : explicit BackupIncumbentScope(Local<Context> backup_incumbent_context);
9233 : ~BackupIncumbentScope();
9234 :
9235 : /**
9236 : * Returns address that is comparable with JS stack address. Note that JS
9237 : * stack may be allocated separately from the native stack. See also
9238 : * |TryCatch::JSStackComparableAddress| for details.
9239 : */
9240 : uintptr_t JSStackComparableAddress() const {
9241 : return js_stack_comparable_address_;
9242 : }
9243 :
9244 : private:
9245 : friend class internal::Isolate;
9246 :
9247 : Local<Context> backup_incumbent_context_;
9248 : uintptr_t js_stack_comparable_address_ = 0;
9249 : const BackupIncumbentScope* prev_ = nullptr;
9250 : };
9251 :
9252 : private:
9253 : friend class Value;
9254 : friend class Script;
9255 : friend class Object;
9256 : friend class Function;
9257 :
9258 : internal::Address* GetDataFromSnapshotOnce(size_t index);
9259 : Local<Value> SlowGetEmbedderData(int index);
9260 : void* SlowGetAlignedPointerFromEmbedderData(int index);
9261 : };
9262 :
9263 :
9264 : /**
9265 : * Multiple threads in V8 are allowed, but only one thread at a time is allowed
9266 : * to use any given V8 isolate, see the comments in the Isolate class. The
9267 : * definition of 'using a V8 isolate' includes accessing handles or holding onto
9268 : * object pointers obtained from V8 handles while in the particular V8 isolate.
9269 : * It is up to the user of V8 to ensure, perhaps with locking, that this
9270 : * constraint is not violated. In addition to any other synchronization
9271 : * mechanism that may be used, the v8::Locker and v8::Unlocker classes must be
9272 : * used to signal thread switches to V8.
9273 : *
9274 : * v8::Locker is a scoped lock object. While it's active, i.e. between its
9275 : * construction and destruction, the current thread is allowed to use the locked
9276 : * isolate. V8 guarantees that an isolate can be locked by at most one thread at
9277 : * any time. In other words, the scope of a v8::Locker is a critical section.
9278 : *
9279 : * Sample usage:
9280 : * \code
9281 : * ...
9282 : * {
9283 : * v8::Locker locker(isolate);
9284 : * v8::Isolate::Scope isolate_scope(isolate);
9285 : * ...
9286 : * // Code using V8 and isolate goes here.
9287 : * ...
9288 : * } // Destructor called here
9289 : * \endcode
9290 : *
9291 : * If you wish to stop using V8 in a thread A you can do this either by
9292 : * destroying the v8::Locker object as above or by constructing a v8::Unlocker
9293 : * object:
9294 : *
9295 : * \code
9296 : * {
9297 : * isolate->Exit();
9298 : * v8::Unlocker unlocker(isolate);
9299 : * ...
9300 : * // Code not using V8 goes here while V8 can run in another thread.
9301 : * ...
9302 : * } // Destructor called here.
9303 : * isolate->Enter();
9304 : * \endcode
9305 : *
9306 : * The Unlocker object is intended for use in a long-running callback from V8,
9307 : * where you want to release the V8 lock for other threads to use.
9308 : *
9309 : * The v8::Locker is a recursive lock, i.e. you can lock more than once in a
9310 : * given thread. This can be useful if you have code that can be called either
9311 : * from code that holds the lock or from code that does not. The Unlocker is
9312 : * not recursive so you can not have several Unlockers on the stack at once, and
9313 : * you can not use an Unlocker in a thread that is not inside a Locker's scope.
9314 : *
9315 : * An unlocker will unlock several lockers if it has to and reinstate the
9316 : * correct depth of locking on its destruction, e.g.:
9317 : *
9318 : * \code
9319 : * // V8 not locked.
9320 : * {
9321 : * v8::Locker locker(isolate);
9322 : * Isolate::Scope isolate_scope(isolate);
9323 : * // V8 locked.
9324 : * {
9325 : * v8::Locker another_locker(isolate);
9326 : * // V8 still locked (2 levels).
9327 : * {
9328 : * isolate->Exit();
9329 : * v8::Unlocker unlocker(isolate);
9330 : * // V8 not locked.
9331 : * }
9332 : * isolate->Enter();
9333 : * // V8 locked again (2 levels).
9334 : * }
9335 : * // V8 still locked (1 level).
9336 : * }
9337 : * // V8 Now no longer locked.
9338 : * \endcode
9339 : */
9340 : class V8_EXPORT Unlocker {
9341 : public:
9342 : /**
9343 : * Initialize Unlocker for a given Isolate.
9344 : */
9345 25225 : V8_INLINE explicit Unlocker(Isolate* isolate) { Initialize(isolate); }
9346 :
9347 : ~Unlocker();
9348 : private:
9349 : void Initialize(Isolate* isolate);
9350 :
9351 : internal::Isolate* isolate_;
9352 : };
9353 :
9354 :
9355 : class V8_EXPORT Locker {
9356 : public:
9357 : /**
9358 : * Initialize Locker for a given Isolate.
9359 : */
9360 8432 : V8_INLINE explicit Locker(Isolate* isolate) { Initialize(isolate); }
9361 :
9362 : ~Locker();
9363 :
9364 : /**
9365 : * Returns whether or not the locker for a given isolate, is locked by the
9366 : * current thread.
9367 : */
9368 : static bool IsLocked(Isolate* isolate);
9369 :
9370 : /**
9371 : * Returns whether v8::Locker is being used by this V8 instance.
9372 : */
9373 : static bool IsActive();
9374 :
9375 : // Disallow copying and assigning.
9376 : Locker(const Locker&) = delete;
9377 : void operator=(const Locker&) = delete;
9378 :
9379 : private:
9380 : void Initialize(Isolate* isolate);
9381 :
9382 : bool has_lock_;
9383 : bool top_level_;
9384 : internal::Isolate* isolate_;
9385 : };
9386 :
9387 : /**
9388 : * Various helpers for skipping over V8 frames in a given stack.
9389 : *
9390 : * The unwinder API is only supported on the x64 architecture.
9391 : */
9392 : class V8_EXPORT Unwinder {
9393 : public:
9394 : /**
9395 : * Attempt to unwind the stack to the most recent C++ frame. This function is
9396 : * signal-safe and does not access any V8 state and thus doesn't require an
9397 : * Isolate.
9398 : *
9399 : * The unwinder needs to know the location of the JS Entry Stub (a piece of
9400 : * code that is run when C++ code calls into generated JS code). This is used
9401 : * for edge cases where the current frame is being constructed or torn down
9402 : * when the stack sample occurs.
9403 : *
9404 : * The unwinder also needs the virtual memory range of all possible V8 code
9405 : * objects. There are two ranges required - the heap code range and the range
9406 : * for code embedded in the binary. The V8 API provides all required inputs
9407 : * via an UnwindState object through the Isolate::GetUnwindState() API. These
9408 : * values will not change after Isolate initialization, so the same
9409 : * |unwind_state| can be used for multiple calls.
9410 : *
9411 : * \param unwind_state Input state for the Isolate that the stack comes from.
9412 : * \param register_state The current registers. This is an in-out param that
9413 : * will be overwritten with the register values after unwinding, on success.
9414 : * \param stack_base The resulting stack pointer and frame pointer values are
9415 : * bounds-checked against the stack_base and the original stack pointer value
9416 : * to ensure that they are valid locations in the given stack. If these values
9417 : * or any intermediate frame pointer values used during unwinding are ever out
9418 : * of these bounds, unwinding will fail.
9419 : *
9420 : * \return True on success.
9421 : */
9422 : static bool TryUnwindV8Frames(const UnwindState& unwind_state,
9423 : RegisterState* register_state,
9424 : const void* stack_base);
9425 :
9426 : /**
9427 : * Whether the PC is within the V8 code range represented by code_range or
9428 : * embedded_code_range in |unwind_state|.
9429 : *
9430 : * If this returns false, then calling UnwindV8Frames() with the same PC
9431 : * and unwind_state will always fail. If it returns true, then unwinding may
9432 : * (but not necessarily) be successful.
9433 : */
9434 : static bool PCIsInV8(const UnwindState& unwind_state, void* pc);
9435 : };
9436 :
9437 : // --- Implementation ---
9438 :
9439 : template <class T>
9440 : Local<T> Local<T>::New(Isolate* isolate, Local<T> that) {
9441 : return New(isolate, that.val_);
9442 : }
9443 :
9444 : template <class T>
9445 : Local<T> Local<T>::New(Isolate* isolate, const PersistentBase<T>& that) {
9446 4921544 : return New(isolate, that.val_);
9447 : }
9448 :
9449 :
9450 : template <class T>
9451 : Local<T> Local<T>::New(Isolate* isolate, T* that) {
9452 4981307 : if (that == nullptr) return Local<T>();
9453 : T* that_ptr = that;
9454 : internal::Address* p = reinterpret_cast<internal::Address*>(that_ptr);
9455 : return Local<T>(reinterpret_cast<T*>(HandleScope::CreateHandle(
9456 4980470 : reinterpret_cast<internal::Isolate*>(isolate), *p)));
9457 : }
9458 :
9459 :
9460 : template<class T>
9461 : template<class S>
9462 : void Eternal<T>::Set(Isolate* isolate, Local<S> handle) {
9463 : TYPE_CHECK(T, S);
9464 10235 : val_ = reinterpret_cast<T*>(
9465 10245 : V8::Eternalize(isolate, reinterpret_cast<Value*>(*handle)));
9466 : }
9467 :
9468 : template <class T>
9469 : Local<T> Eternal<T>::Get(Isolate* isolate) const {
9470 : // The eternal handle will never go away, so as with the roots, we don't even
9471 : // need to open a handle.
9472 10235 : return Local<T>(val_);
9473 : }
9474 :
9475 :
9476 : template <class T>
9477 : Local<T> MaybeLocal<T>::ToLocalChecked() {
9478 11149007 : if (V8_UNLIKELY(val_ == nullptr)) V8::ToLocalEmpty();
9479 : return Local<T>(val_);
9480 : }
9481 :
9482 :
9483 : template <class T>
9484 : void* WeakCallbackInfo<T>::GetInternalField(int index) const {
9485 : #ifdef V8_ENABLE_CHECKS
9486 : if (index < 0 || index >= kEmbedderFieldsInWeakCallback) {
9487 : V8::InternalFieldOutOfBounds(index);
9488 : }
9489 : #endif
9490 17 : return embedder_fields_[index];
9491 : }
9492 :
9493 :
9494 : template <class T>
9495 : T* PersistentBase<T>::New(Isolate* isolate, T* that) {
9496 3024887 : if (that == nullptr) return nullptr;
9497 : internal::Address* p = reinterpret_cast<internal::Address*>(that);
9498 : return reinterpret_cast<T*>(
9499 : V8::GlobalizeReference(reinterpret_cast<internal::Isolate*>(isolate),
9500 3024887 : p));
9501 : }
9502 :
9503 :
9504 : template <class T, class M>
9505 : template <class S, class M2>
9506 : void Persistent<T, M>::Copy(const Persistent<S, M2>& that) {
9507 : TYPE_CHECK(T, S);
9508 : this->Reset();
9509 10 : if (that.IsEmpty()) return;
9510 : internal::Address* p = reinterpret_cast<internal::Address*>(that.val_);
9511 10 : this->val_ = reinterpret_cast<T*>(V8::CopyPersistent(p));
9512 : M::Copy(that, this);
9513 : }
9514 :
9515 : template <class T>
9516 : bool PersistentBase<T>::IsIndependent() const {
9517 : typedef internal::Internals I;
9518 46 : if (this->IsEmpty()) return false;
9519 : return I::GetNodeFlag(reinterpret_cast<internal::Address*>(this->val_),
9520 46 : I::kNodeIsIndependentShift);
9521 : }
9522 :
9523 : template <class T>
9524 : bool PersistentBase<T>::IsNearDeath() const {
9525 : typedef internal::Internals I;
9526 : if (this->IsEmpty()) return false;
9527 : uint8_t node_state =
9528 : I::GetNodeState(reinterpret_cast<internal::Address*>(this->val_));
9529 : return node_state == I::kNodeStateIsNearDeathValue ||
9530 : node_state == I::kNodeStateIsPendingValue;
9531 : }
9532 :
9533 :
9534 : template <class T>
9535 : bool PersistentBase<T>::IsWeak() const {
9536 : typedef internal::Internals I;
9537 40 : if (this->IsEmpty()) return false;
9538 : return I::GetNodeState(reinterpret_cast<internal::Address*>(this->val_)) ==
9539 20 : I::kNodeStateIsWeakValue;
9540 : }
9541 :
9542 :
9543 : template <class T>
9544 : void PersistentBase<T>::Reset() {
9545 6208853 : if (this->IsEmpty()) return;
9546 3022425 : V8::DisposeGlobal(reinterpret_cast<internal::Address*>(this->val_));
9547 2988243 : val_ = nullptr;
9548 : }
9549 :
9550 :
9551 : template <class T>
9552 : template <class S>
9553 : void PersistentBase<T>::Reset(Isolate* isolate, const Local<S>& other) {
9554 : TYPE_CHECK(T, S);
9555 : Reset();
9556 2864949 : if (other.IsEmpty()) return;
9557 2864748 : this->val_ = New(isolate, other.val_);
9558 : }
9559 :
9560 :
9561 : template <class T>
9562 : template <class S>
9563 : void PersistentBase<T>::Reset(Isolate* isolate,
9564 : const PersistentBase<S>& other) {
9565 : TYPE_CHECK(T, S);
9566 : Reset();
9567 3145 : if (other.IsEmpty()) return;
9568 841 : this->val_ = New(isolate, other.val_);
9569 : }
9570 :
9571 :
9572 : template <class T>
9573 : template <typename P>
9574 : V8_INLINE void PersistentBase<T>::SetWeak(
9575 : P* parameter, typename WeakCallbackInfo<P>::Callback callback,
9576 : WeakCallbackType type) {
9577 : typedef typename WeakCallbackInfo<void>::Callback Callback;
9578 109728 : V8::MakeWeak(reinterpret_cast<internal::Address*>(this->val_), parameter,
9579 109068 : reinterpret_cast<Callback>(callback), type);
9580 : }
9581 :
9582 : template <class T>
9583 : void PersistentBase<T>::SetWeak() {
9584 26 : V8::MakeWeak(reinterpret_cast<internal::Address**>(&this->val_));
9585 : }
9586 :
9587 : template <class T>
9588 : template <typename P>
9589 : P* PersistentBase<T>::ClearWeak() {
9590 : return reinterpret_cast<P*>(
9591 35 : V8::ClearWeak(reinterpret_cast<internal::Address*>(this->val_)));
9592 : }
9593 :
9594 : template <class T>
9595 : void PersistentBase<T>::AnnotateStrongRetainer(const char* label) {
9596 2799831 : V8::AnnotateStrongRetainer(reinterpret_cast<internal::Address*>(this->val_),
9597 2799826 : label);
9598 : }
9599 :
9600 : template <class T>
9601 : void PersistentBase<T>::RegisterExternalReference(Isolate* isolate) const {
9602 5 : if (IsEmpty()) return;
9603 5 : V8::RegisterExternallyReferencedObject(
9604 : reinterpret_cast<internal::Address*>(this->val_),
9605 : reinterpret_cast<internal::Isolate*>(isolate));
9606 : }
9607 :
9608 : template <class T>
9609 : void PersistentBase<T>::MarkIndependent() {
9610 : typedef internal::Internals I;
9611 104859 : if (this->IsEmpty()) return;
9612 : I::UpdateNodeFlag(reinterpret_cast<internal::Address*>(this->val_), true,
9613 : I::kNodeIsIndependentShift);
9614 : }
9615 :
9616 : template <class T>
9617 : void PersistentBase<T>::MarkActive() {
9618 : typedef internal::Internals I;
9619 15 : if (this->IsEmpty()) return;
9620 : I::UpdateNodeFlag(reinterpret_cast<internal::Address*>(this->val_), true,
9621 : I::kNodeIsActiveShift);
9622 : }
9623 :
9624 :
9625 : template <class T>
9626 : void PersistentBase<T>::SetWrapperClassId(uint16_t class_id) {
9627 : typedef internal::Internals I;
9628 35 : if (this->IsEmpty()) return;
9629 : internal::Address* obj = reinterpret_cast<internal::Address*>(this->val_);
9630 : uint8_t* addr = reinterpret_cast<uint8_t*>(obj) + I::kNodeClassIdOffset;
9631 35 : *reinterpret_cast<uint16_t*>(addr) = class_id;
9632 : }
9633 :
9634 :
9635 : template <class T>
9636 : uint16_t PersistentBase<T>::WrapperClassId() const {
9637 : typedef internal::Internals I;
9638 50 : if (this->IsEmpty()) return 0;
9639 : internal::Address* obj = reinterpret_cast<internal::Address*>(this->val_);
9640 : uint8_t* addr = reinterpret_cast<uint8_t*>(obj) + I::kNodeClassIdOffset;
9641 50 : return *reinterpret_cast<uint16_t*>(addr);
9642 : }
9643 :
9644 : template <typename T>
9645 : ReturnValue<T>::ReturnValue(internal::Address* slot) : value_(slot) {}
9646 :
9647 : template<typename T>
9648 : template<typename S>
9649 : void ReturnValue<T>::Set(const Persistent<S>& handle) {
9650 : TYPE_CHECK(T, S);
9651 : if (V8_UNLIKELY(handle.IsEmpty())) {
9652 : *value_ = GetDefaultValue();
9653 : } else {
9654 : *value_ = *reinterpret_cast<internal::Address*>(*handle);
9655 : }
9656 : }
9657 :
9658 : template <typename T>
9659 : template <typename S>
9660 : void ReturnValue<T>::Set(const Global<S>& handle) {
9661 : TYPE_CHECK(T, S);
9662 5134 : if (V8_UNLIKELY(handle.IsEmpty())) {
9663 0 : *value_ = GetDefaultValue();
9664 : } else {
9665 5134 : *value_ = *reinterpret_cast<internal::Address*>(*handle);
9666 : }
9667 : }
9668 :
9669 : template <typename T>
9670 : template <typename S>
9671 : void ReturnValue<T>::Set(const Local<S> handle) {
9672 : TYPE_CHECK(T, S);
9673 25487537 : if (V8_UNLIKELY(handle.IsEmpty())) {
9674 53443 : *value_ = GetDefaultValue();
9675 : } else {
9676 25434094 : *value_ = *reinterpret_cast<internal::Address*>(*handle);
9677 : }
9678 : }
9679 :
9680 : template<typename T>
9681 : void ReturnValue<T>::Set(double i) {
9682 : TYPE_CHECK(T, Number);
9683 5684 : Set(Number::New(GetIsolate(), i));
9684 : }
9685 :
9686 : template<typename T>
9687 : void ReturnValue<T>::Set(int32_t i) {
9688 : TYPE_CHECK(T, Integer);
9689 : typedef internal::Internals I;
9690 : if (V8_LIKELY(I::IsValidSmi(i))) {
9691 19679 : *value_ = I::IntToSmi(i);
9692 : return;
9693 : }
9694 : Set(Integer::New(GetIsolate(), i));
9695 : }
9696 :
9697 : template<typename T>
9698 : void ReturnValue<T>::Set(uint32_t i) {
9699 : TYPE_CHECK(T, Integer);
9700 : // Can't simply use INT32_MAX here for whatever reason.
9701 4851 : bool fits_into_int32_t = (i & (1U << 31)) == 0;
9702 4851 : if (V8_LIKELY(fits_into_int32_t)) {
9703 : Set(static_cast<int32_t>(i));
9704 : return;
9705 : }
9706 77 : Set(Integer::NewFromUnsigned(GetIsolate(), i));
9707 : }
9708 :
9709 : template<typename T>
9710 : void ReturnValue<T>::Set(bool value) {
9711 : TYPE_CHECK(T, Boolean);
9712 : typedef internal::Internals I;
9713 : int root_index;
9714 925124 : if (value) {
9715 : root_index = I::kTrueValueRootIndex;
9716 : } else {
9717 : root_index = I::kFalseValueRootIndex;
9718 : }
9719 1571908 : *value_ = *I::GetRoot(GetIsolate(), root_index);
9720 : }
9721 :
9722 : template<typename T>
9723 : void ReturnValue<T>::SetNull() {
9724 : TYPE_CHECK(T, Primitive);
9725 : typedef internal::Internals I;
9726 191 : *value_ = *I::GetRoot(GetIsolate(), I::kNullValueRootIndex);
9727 : }
9728 :
9729 : template<typename T>
9730 : void ReturnValue<T>::SetUndefined() {
9731 : TYPE_CHECK(T, Primitive);
9732 : typedef internal::Internals I;
9733 88 : *value_ = *I::GetRoot(GetIsolate(), I::kUndefinedValueRootIndex);
9734 : }
9735 :
9736 : template<typename T>
9737 : void ReturnValue<T>::SetEmptyString() {
9738 : TYPE_CHECK(T, String);
9739 : typedef internal::Internals I;
9740 11 : *value_ = *I::GetRoot(GetIsolate(), I::kEmptyStringRootIndex);
9741 : }
9742 :
9743 : template <typename T>
9744 : Isolate* ReturnValue<T>::GetIsolate() const {
9745 : // Isolate is always the pointer below the default value on the stack.
9746 1611183 : return *reinterpret_cast<Isolate**>(&value_[-2]);
9747 : }
9748 :
9749 : template <typename T>
9750 : Local<Value> ReturnValue<T>::Get() const {
9751 : typedef internal::Internals I;
9752 33224 : if (*value_ == *I::GetRoot(GetIsolate(), I::kTheHoleValueRootIndex))
9753 : return Local<Value>(*Undefined(GetIsolate()));
9754 : return Local<Value>::New(GetIsolate(), reinterpret_cast<Value*>(value_));
9755 : }
9756 :
9757 : template <typename T>
9758 : template <typename S>
9759 : void ReturnValue<T>::Set(S* whatever) {
9760 : // Uncompilable to prevent inadvertent misuse.
9761 : TYPE_CHECK(S*, Primitive);
9762 : }
9763 :
9764 : template <typename T>
9765 : internal::Address ReturnValue<T>::GetDefaultValue() {
9766 : // Default value is always the pointer below value_ on the stack.
9767 53443 : return value_[-1];
9768 : }
9769 :
9770 : template <typename T>
9771 : FunctionCallbackInfo<T>::FunctionCallbackInfo(internal::Address* implicit_args,
9772 : internal::Address* values,
9773 : int length)
9774 2488193 : : implicit_args_(implicit_args), values_(values), length_(length) {}
9775 :
9776 : template<typename T>
9777 7690 : Local<Value> FunctionCallbackInfo<T>::operator[](int i) const {
9778 3439286 : if (i < 0 || length_ <= i) return Local<Value>(*Undefined(GetIsolate()));
9779 3410745 : return Local<Value>(reinterpret_cast<Value*>(values_ - i));
9780 : }
9781 :
9782 :
9783 : template<typename T>
9784 : Local<Object> FunctionCallbackInfo<T>::This() const {
9785 23719591 : return Local<Object>(reinterpret_cast<Object*>(values_ + 1));
9786 : }
9787 :
9788 :
9789 : template<typename T>
9790 : Local<Object> FunctionCallbackInfo<T>::Holder() const {
9791 : return Local<Object>(reinterpret_cast<Object*>(
9792 : &implicit_args_[kHolderIndex]));
9793 : }
9794 :
9795 : template <typename T>
9796 : Local<Value> FunctionCallbackInfo<T>::NewTarget() const {
9797 : return Local<Value>(
9798 48 : reinterpret_cast<Value*>(&implicit_args_[kNewTargetIndex]));
9799 : }
9800 :
9801 : template <typename T>
9802 : Local<Value> FunctionCallbackInfo<T>::Data() const {
9803 836499 : return Local<Value>(reinterpret_cast<Value*>(&implicit_args_[kDataIndex]));
9804 : }
9805 :
9806 :
9807 : template<typename T>
9808 : Isolate* FunctionCallbackInfo<T>::GetIsolate() const {
9809 33584378 : return *reinterpret_cast<Isolate**>(&implicit_args_[kIsolateIndex]);
9810 : }
9811 :
9812 :
9813 : template<typename T>
9814 : ReturnValue<T> FunctionCallbackInfo<T>::GetReturnValue() const {
9815 25274644 : return ReturnValue<T>(&implicit_args_[kReturnValueIndex]);
9816 : }
9817 :
9818 :
9819 : template<typename T>
9820 328181 : bool FunctionCallbackInfo<T>::IsConstructCall() const {
9821 0 : return !NewTarget()->IsUndefined();
9822 : }
9823 :
9824 :
9825 : template<typename T>
9826 : int FunctionCallbackInfo<T>::Length() const {
9827 : return length_;
9828 : }
9829 :
9830 : ScriptOrigin::ScriptOrigin(Local<Value> resource_name,
9831 : Local<Integer> resource_line_offset,
9832 : Local<Integer> resource_column_offset,
9833 : Local<Boolean> resource_is_shared_cross_origin,
9834 : Local<Integer> script_id,
9835 : Local<Value> source_map_url,
9836 : Local<Boolean> resource_is_opaque,
9837 : Local<Boolean> is_wasm, Local<Boolean> is_module,
9838 : Local<PrimitiveArray> host_defined_options)
9839 : : resource_name_(resource_name),
9840 : resource_line_offset_(resource_line_offset),
9841 : resource_column_offset_(resource_column_offset),
9842 30546 : options_(!resource_is_shared_cross_origin.IsEmpty() &&
9843 15273 : resource_is_shared_cross_origin->IsTrue(),
9844 15258 : !resource_is_opaque.IsEmpty() && resource_is_opaque->IsTrue(),
9845 14253 : !is_wasm.IsEmpty() && is_wasm->IsTrue(),
9846 15887 : !is_module.IsEmpty() && is_module->IsTrue()),
9847 : script_id_(script_id),
9848 : source_map_url_(source_map_url),
9849 261394 : host_defined_options_(host_defined_options) {}
9850 :
9851 : Local<Value> ScriptOrigin::ResourceName() const { return resource_name_; }
9852 :
9853 : Local<PrimitiveArray> ScriptOrigin::HostDefinedOptions() const {
9854 : return host_defined_options_;
9855 : }
9856 :
9857 : Local<Integer> ScriptOrigin::ResourceLineOffset() const {
9858 : return resource_line_offset_;
9859 : }
9860 :
9861 :
9862 : Local<Integer> ScriptOrigin::ResourceColumnOffset() const {
9863 : return resource_column_offset_;
9864 : }
9865 :
9866 :
9867 : Local<Integer> ScriptOrigin::ScriptID() const { return script_id_; }
9868 :
9869 :
9870 : Local<Value> ScriptOrigin::SourceMapUrl() const { return source_map_url_; }
9871 :
9872 : ScriptCompiler::Source::Source(Local<String> string, const ScriptOrigin& origin,
9873 : CachedData* data)
9874 : : source_string(string),
9875 : resource_name(origin.ResourceName()),
9876 : resource_line_offset(origin.ResourceLineOffset()),
9877 : resource_column_offset(origin.ResourceColumnOffset()),
9878 : resource_options(origin.Options()),
9879 : source_map_url(origin.SourceMapUrl()),
9880 : host_defined_options(origin.HostDefinedOptions()),
9881 124330 : cached_data(data) {}
9882 :
9883 : ScriptCompiler::Source::Source(Local<String> string,
9884 : CachedData* data)
9885 268924 : : source_string(string), cached_data(data) {}
9886 :
9887 :
9888 : ScriptCompiler::Source::~Source() {
9889 258395 : delete cached_data;
9890 : }
9891 :
9892 :
9893 : const ScriptCompiler::CachedData* ScriptCompiler::Source::GetCachedData()
9894 : const {
9895 : return cached_data;
9896 : }
9897 :
9898 : const ScriptOriginOptions& ScriptCompiler::Source::GetResourceOptions() const {
9899 : return resource_options;
9900 : }
9901 :
9902 : Local<Boolean> Boolean::New(Isolate* isolate, bool value) {
9903 199314 : return value ? True(isolate) : False(isolate);
9904 : }
9905 :
9906 : void Template::Set(Isolate* isolate, const char* name, Local<Data> value) {
9907 : Set(String::NewFromUtf8(isolate, name, NewStringType::kInternalized)
9908 : .ToLocalChecked(),
9909 1290 : value);
9910 : }
9911 :
9912 : FunctionTemplate* FunctionTemplate::Cast(Data* data) {
9913 : #ifdef V8_ENABLE_CHECKS
9914 : CheckCast(data);
9915 : #endif
9916 : return reinterpret_cast<FunctionTemplate*>(data);
9917 : }
9918 :
9919 : ObjectTemplate* ObjectTemplate::Cast(Data* data) {
9920 : #ifdef V8_ENABLE_CHECKS
9921 : CheckCast(data);
9922 : #endif
9923 : return reinterpret_cast<ObjectTemplate*>(data);
9924 : }
9925 :
9926 : Signature* Signature::Cast(Data* data) {
9927 : #ifdef V8_ENABLE_CHECKS
9928 : CheckCast(data);
9929 : #endif
9930 : return reinterpret_cast<Signature*>(data);
9931 : }
9932 :
9933 : AccessorSignature* AccessorSignature::Cast(Data* data) {
9934 : #ifdef V8_ENABLE_CHECKS
9935 : CheckCast(data);
9936 : #endif
9937 : return reinterpret_cast<AccessorSignature*>(data);
9938 : }
9939 :
9940 : Local<Value> Object::GetInternalField(int index) {
9941 : #if !defined(V8_ENABLE_CHECKS) && !defined(V8_COMPRESS_POINTERS)
9942 : typedef internal::Address A;
9943 : typedef internal::Internals I;
9944 1400 : A obj = *reinterpret_cast<A*>(this);
9945 : // Fast path: If the object is a plain JSObject, which is the common case, we
9946 : // know where to find the internal fields and can return the value directly.
9947 : auto instance_type = I::GetInstanceType(obj);
9948 2800 : if (instance_type == I::kJSObjectType ||
9949 1400 : instance_type == I::kJSApiObjectType ||
9950 1400 : instance_type == I::kJSSpecialApiObjectType) {
9951 660 : int offset = I::kJSObjectHeaderSizeForEmbedderFields +
9952 660 : (I::kEmbedderDataSlotSize * index);
9953 : A value = I::ReadTaggedAnyField(obj, offset);
9954 : internal::Isolate* isolate =
9955 824 : internal::IsolateFromNeverReadOnlySpaceObject(obj);
9956 824 : A* result = HandleScope::CreateHandle(isolate, value);
9957 : return Local<Value>(reinterpret_cast<Value*>(result));
9958 : }
9959 : #endif
9960 576 : return SlowGetInternalField(index);
9961 : }
9962 :
9963 :
9964 : void* Object::GetAlignedPointerFromInternalField(int index) {
9965 : #if !defined(V8_ENABLE_CHECKS) && !defined(V8_COMPRESS_POINTERS)
9966 : typedef internal::Address A;
9967 : typedef internal::Internals I;
9968 2935 : A obj = *reinterpret_cast<A*>(this);
9969 : // Fast path: If the object is a plain JSObject, which is the common case, we
9970 : // know where to find the internal fields and can return the value directly.
9971 : auto instance_type = I::GetInstanceType(obj);
9972 2935 : if (V8_LIKELY(instance_type == I::kJSObjectType ||
9973 : instance_type == I::kJSApiObjectType ||
9974 : instance_type == I::kJSSpecialApiObjectType)) {
9975 15 : int offset = I::kJSObjectHeaderSizeForEmbedderFields +
9976 15 : (I::kEmbedderDataSlotSize * index);
9977 : return I::ReadRawField<void*>(obj, offset);
9978 : }
9979 : #endif
9980 135 : return SlowGetAlignedPointerFromInternalField(index);
9981 : }
9982 :
9983 : String* String::Cast(v8::Value* value) {
9984 : #ifdef V8_ENABLE_CHECKS
9985 : CheckCast(value);
9986 : #endif
9987 : return static_cast<String*>(value);
9988 : }
9989 :
9990 :
9991 : Local<String> String::Empty(Isolate* isolate) {
9992 : typedef internal::Address S;
9993 : typedef internal::Internals I;
9994 : I::CheckInitialized(isolate);
9995 : S* slot = I::GetRoot(isolate, I::kEmptyStringRootIndex);
9996 : return Local<String>(reinterpret_cast<String*>(slot));
9997 : }
9998 :
9999 :
10000 : String::ExternalStringResource* String::GetExternalStringResource() const {
10001 : typedef internal::Address A;
10002 : typedef internal::Internals I;
10003 31 : A obj = *reinterpret_cast<const A*>(this);
10004 :
10005 : ExternalStringResource* result;
10006 31 : if (I::IsExternalTwoByteString(I::GetInstanceType(obj))) {
10007 : void* value = I::ReadRawField<void*>(obj, I::kStringResourceOffset);
10008 : result = reinterpret_cast<String::ExternalStringResource*>(value);
10009 : } else {
10010 0 : result = GetExternalStringResourceSlow();
10011 : }
10012 : #ifdef V8_ENABLE_CHECKS
10013 : VerifyExternalStringResource(result);
10014 : #endif
10015 : return result;
10016 : }
10017 :
10018 :
10019 : String::ExternalStringResourceBase* String::GetExternalStringResourceBase(
10020 : String::Encoding* encoding_out) const {
10021 : typedef internal::Address A;
10022 : typedef internal::Internals I;
10023 28 : A obj = *reinterpret_cast<const A*>(this);
10024 28 : int type = I::GetInstanceType(obj) & I::kFullStringRepresentationMask;
10025 28 : *encoding_out = static_cast<Encoding>(type & I::kStringEncodingMask);
10026 : ExternalStringResourceBase* resource;
10027 56 : if (type == I::kExternalOneByteRepresentationTag ||
10028 28 : type == I::kExternalTwoByteRepresentationTag) {
10029 : void* value = I::ReadRawField<void*>(obj, I::kStringResourceOffset);
10030 : resource = static_cast<ExternalStringResourceBase*>(value);
10031 : } else {
10032 6 : resource = GetExternalStringResourceBaseSlow(encoding_out);
10033 : }
10034 : #ifdef V8_ENABLE_CHECKS
10035 : VerifyExternalStringResourceBase(resource, *encoding_out);
10036 : #endif
10037 : return resource;
10038 : }
10039 :
10040 :
10041 : bool Value::IsUndefined() const {
10042 : #ifdef V8_ENABLE_CHECKS
10043 : return FullIsUndefined();
10044 : #else
10045 : return QuickIsUndefined();
10046 : #endif
10047 : }
10048 :
10049 : bool Value::QuickIsUndefined() const {
10050 : typedef internal::Address A;
10051 : typedef internal::Internals I;
10052 7307971 : A obj = *reinterpret_cast<const A*>(this);
10053 7395405 : if (!I::HasHeapObjectTag(obj)) return false;
10054 7381783 : if (I::GetInstanceType(obj) != I::kOddballType) return false;
10055 277070 : return (I::GetOddballKind(obj) == I::kUndefinedOddballKind);
10056 : }
10057 :
10058 :
10059 : bool Value::IsNull() const {
10060 : #ifdef V8_ENABLE_CHECKS
10061 : return FullIsNull();
10062 : #else
10063 : return QuickIsNull();
10064 : #endif
10065 : }
10066 :
10067 : bool Value::QuickIsNull() const {
10068 : typedef internal::Address A;
10069 : typedef internal::Internals I;
10070 3916579 : A obj = *reinterpret_cast<const A*>(this);
10071 3936944 : if (!I::HasHeapObjectTag(obj)) return false;
10072 3797487 : if (I::GetInstanceType(obj) != I::kOddballType) return false;
10073 202868 : return (I::GetOddballKind(obj) == I::kNullOddballKind);
10074 : }
10075 :
10076 : bool Value::IsNullOrUndefined() const {
10077 : #ifdef V8_ENABLE_CHECKS
10078 : return FullIsNull() || FullIsUndefined();
10079 : #else
10080 : return QuickIsNullOrUndefined();
10081 : #endif
10082 : }
10083 :
10084 : bool Value::QuickIsNullOrUndefined() const {
10085 : typedef internal::Address A;
10086 : typedef internal::Internals I;
10087 9004425 : A obj = *reinterpret_cast<const A*>(this);
10088 9004425 : if (!I::HasHeapObjectTag(obj)) return false;
10089 9004425 : if (I::GetInstanceType(obj) != I::kOddballType) return false;
10090 : int kind = I::GetOddballKind(obj);
10091 0 : return kind == I::kNullOddballKind || kind == I::kUndefinedOddballKind;
10092 : }
10093 :
10094 : bool Value::IsString() const {
10095 : #ifdef V8_ENABLE_CHECKS
10096 : return FullIsString();
10097 : #else
10098 : return QuickIsString();
10099 : #endif
10100 : }
10101 :
10102 : bool Value::QuickIsString() const {
10103 : typedef internal::Address A;
10104 : typedef internal::Internals I;
10105 8815838 : A obj = *reinterpret_cast<const A*>(this);
10106 8815850 : if (!I::HasHeapObjectTag(obj)) return false;
10107 8815100 : return (I::GetInstanceType(obj) < I::kFirstNonstringType);
10108 : }
10109 :
10110 :
10111 : template <class T> Value* Value::Cast(T* value) {
10112 : return static_cast<Value*>(value);
10113 : }
10114 :
10115 :
10116 : Boolean* Boolean::Cast(v8::Value* value) {
10117 : #ifdef V8_ENABLE_CHECKS
10118 : CheckCast(value);
10119 : #endif
10120 : return static_cast<Boolean*>(value);
10121 : }
10122 :
10123 :
10124 : Name* Name::Cast(v8::Value* value) {
10125 : #ifdef V8_ENABLE_CHECKS
10126 : CheckCast(value);
10127 : #endif
10128 : return static_cast<Name*>(value);
10129 : }
10130 :
10131 :
10132 : Symbol* Symbol::Cast(v8::Value* value) {
10133 : #ifdef V8_ENABLE_CHECKS
10134 : CheckCast(value);
10135 : #endif
10136 : return static_cast<Symbol*>(value);
10137 : }
10138 :
10139 :
10140 : Private* Private::Cast(Data* data) {
10141 : #ifdef V8_ENABLE_CHECKS
10142 : CheckCast(data);
10143 : #endif
10144 : return reinterpret_cast<Private*>(data);
10145 : }
10146 :
10147 :
10148 : Number* Number::Cast(v8::Value* value) {
10149 : #ifdef V8_ENABLE_CHECKS
10150 : CheckCast(value);
10151 : #endif
10152 : return static_cast<Number*>(value);
10153 : }
10154 :
10155 :
10156 : Integer* Integer::Cast(v8::Value* value) {
10157 : #ifdef V8_ENABLE_CHECKS
10158 : CheckCast(value);
10159 : #endif
10160 : return static_cast<Integer*>(value);
10161 : }
10162 :
10163 :
10164 : Int32* Int32::Cast(v8::Value* value) {
10165 : #ifdef V8_ENABLE_CHECKS
10166 : CheckCast(value);
10167 : #endif
10168 : return static_cast<Int32*>(value);
10169 : }
10170 :
10171 :
10172 : Uint32* Uint32::Cast(v8::Value* value) {
10173 : #ifdef V8_ENABLE_CHECKS
10174 : CheckCast(value);
10175 : #endif
10176 : return static_cast<Uint32*>(value);
10177 : }
10178 :
10179 : BigInt* BigInt::Cast(v8::Value* value) {
10180 : #ifdef V8_ENABLE_CHECKS
10181 : CheckCast(value);
10182 : #endif
10183 : return static_cast<BigInt*>(value);
10184 : }
10185 :
10186 : Date* Date::Cast(v8::Value* value) {
10187 : #ifdef V8_ENABLE_CHECKS
10188 : CheckCast(value);
10189 : #endif
10190 : return static_cast<Date*>(value);
10191 : }
10192 :
10193 :
10194 : StringObject* StringObject::Cast(v8::Value* value) {
10195 : #ifdef V8_ENABLE_CHECKS
10196 : CheckCast(value);
10197 : #endif
10198 : return static_cast<StringObject*>(value);
10199 : }
10200 :
10201 :
10202 : SymbolObject* SymbolObject::Cast(v8::Value* value) {
10203 : #ifdef V8_ENABLE_CHECKS
10204 : CheckCast(value);
10205 : #endif
10206 : return static_cast<SymbolObject*>(value);
10207 : }
10208 :
10209 :
10210 : NumberObject* NumberObject::Cast(v8::Value* value) {
10211 : #ifdef V8_ENABLE_CHECKS
10212 : CheckCast(value);
10213 : #endif
10214 : return static_cast<NumberObject*>(value);
10215 : }
10216 :
10217 : BigIntObject* BigIntObject::Cast(v8::Value* value) {
10218 : #ifdef V8_ENABLE_CHECKS
10219 : CheckCast(value);
10220 : #endif
10221 : return static_cast<BigIntObject*>(value);
10222 : }
10223 :
10224 : BooleanObject* BooleanObject::Cast(v8::Value* value) {
10225 : #ifdef V8_ENABLE_CHECKS
10226 : CheckCast(value);
10227 : #endif
10228 : return static_cast<BooleanObject*>(value);
10229 : }
10230 :
10231 :
10232 : RegExp* RegExp::Cast(v8::Value* value) {
10233 : #ifdef V8_ENABLE_CHECKS
10234 : CheckCast(value);
10235 : #endif
10236 : return static_cast<RegExp*>(value);
10237 : }
10238 :
10239 :
10240 : Object* Object::Cast(v8::Value* value) {
10241 : #ifdef V8_ENABLE_CHECKS
10242 : CheckCast(value);
10243 : #endif
10244 : return static_cast<Object*>(value);
10245 : }
10246 :
10247 :
10248 : Array* Array::Cast(v8::Value* value) {
10249 : #ifdef V8_ENABLE_CHECKS
10250 : CheckCast(value);
10251 : #endif
10252 : return static_cast<Array*>(value);
10253 : }
10254 :
10255 :
10256 : Map* Map::Cast(v8::Value* value) {
10257 : #ifdef V8_ENABLE_CHECKS
10258 : CheckCast(value);
10259 : #endif
10260 : return static_cast<Map*>(value);
10261 : }
10262 :
10263 :
10264 : Set* Set::Cast(v8::Value* value) {
10265 : #ifdef V8_ENABLE_CHECKS
10266 : CheckCast(value);
10267 : #endif
10268 : return static_cast<Set*>(value);
10269 : }
10270 :
10271 :
10272 : Promise* Promise::Cast(v8::Value* value) {
10273 : #ifdef V8_ENABLE_CHECKS
10274 : CheckCast(value);
10275 : #endif
10276 : return static_cast<Promise*>(value);
10277 : }
10278 :
10279 :
10280 : Proxy* Proxy::Cast(v8::Value* value) {
10281 : #ifdef V8_ENABLE_CHECKS
10282 : CheckCast(value);
10283 : #endif
10284 : return static_cast<Proxy*>(value);
10285 : }
10286 :
10287 : WasmModuleObject* WasmModuleObject::Cast(v8::Value* value) {
10288 : #ifdef V8_ENABLE_CHECKS
10289 : CheckCast(value);
10290 : #endif
10291 : return static_cast<WasmModuleObject*>(value);
10292 : }
10293 :
10294 : Promise::Resolver* Promise::Resolver::Cast(v8::Value* value) {
10295 : #ifdef V8_ENABLE_CHECKS
10296 : CheckCast(value);
10297 : #endif
10298 : return static_cast<Promise::Resolver*>(value);
10299 : }
10300 :
10301 :
10302 : ArrayBuffer* ArrayBuffer::Cast(v8::Value* value) {
10303 : #ifdef V8_ENABLE_CHECKS
10304 : CheckCast(value);
10305 : #endif
10306 : return static_cast<ArrayBuffer*>(value);
10307 : }
10308 :
10309 :
10310 : ArrayBufferView* ArrayBufferView::Cast(v8::Value* value) {
10311 : #ifdef V8_ENABLE_CHECKS
10312 : CheckCast(value);
10313 : #endif
10314 : return static_cast<ArrayBufferView*>(value);
10315 : }
10316 :
10317 :
10318 : TypedArray* TypedArray::Cast(v8::Value* value) {
10319 : #ifdef V8_ENABLE_CHECKS
10320 : CheckCast(value);
10321 : #endif
10322 : return static_cast<TypedArray*>(value);
10323 : }
10324 :
10325 :
10326 : Uint8Array* Uint8Array::Cast(v8::Value* value) {
10327 : #ifdef V8_ENABLE_CHECKS
10328 : CheckCast(value);
10329 : #endif
10330 : return static_cast<Uint8Array*>(value);
10331 : }
10332 :
10333 :
10334 : Int8Array* Int8Array::Cast(v8::Value* value) {
10335 : #ifdef V8_ENABLE_CHECKS
10336 : CheckCast(value);
10337 : #endif
10338 : return static_cast<Int8Array*>(value);
10339 : }
10340 :
10341 :
10342 : Uint16Array* Uint16Array::Cast(v8::Value* value) {
10343 : #ifdef V8_ENABLE_CHECKS
10344 : CheckCast(value);
10345 : #endif
10346 : return static_cast<Uint16Array*>(value);
10347 : }
10348 :
10349 :
10350 : Int16Array* Int16Array::Cast(v8::Value* value) {
10351 : #ifdef V8_ENABLE_CHECKS
10352 : CheckCast(value);
10353 : #endif
10354 : return static_cast<Int16Array*>(value);
10355 : }
10356 :
10357 :
10358 : Uint32Array* Uint32Array::Cast(v8::Value* value) {
10359 : #ifdef V8_ENABLE_CHECKS
10360 : CheckCast(value);
10361 : #endif
10362 : return static_cast<Uint32Array*>(value);
10363 : }
10364 :
10365 :
10366 : Int32Array* Int32Array::Cast(v8::Value* value) {
10367 : #ifdef V8_ENABLE_CHECKS
10368 : CheckCast(value);
10369 : #endif
10370 : return static_cast<Int32Array*>(value);
10371 : }
10372 :
10373 :
10374 : Float32Array* Float32Array::Cast(v8::Value* value) {
10375 : #ifdef V8_ENABLE_CHECKS
10376 : CheckCast(value);
10377 : #endif
10378 : return static_cast<Float32Array*>(value);
10379 : }
10380 :
10381 :
10382 : Float64Array* Float64Array::Cast(v8::Value* value) {
10383 : #ifdef V8_ENABLE_CHECKS
10384 : CheckCast(value);
10385 : #endif
10386 : return static_cast<Float64Array*>(value);
10387 : }
10388 :
10389 : BigInt64Array* BigInt64Array::Cast(v8::Value* value) {
10390 : #ifdef V8_ENABLE_CHECKS
10391 : CheckCast(value);
10392 : #endif
10393 : return static_cast<BigInt64Array*>(value);
10394 : }
10395 :
10396 : BigUint64Array* BigUint64Array::Cast(v8::Value* value) {
10397 : #ifdef V8_ENABLE_CHECKS
10398 : CheckCast(value);
10399 : #endif
10400 : return static_cast<BigUint64Array*>(value);
10401 : }
10402 :
10403 : Uint8ClampedArray* Uint8ClampedArray::Cast(v8::Value* value) {
10404 : #ifdef V8_ENABLE_CHECKS
10405 : CheckCast(value);
10406 : #endif
10407 : return static_cast<Uint8ClampedArray*>(value);
10408 : }
10409 :
10410 :
10411 : DataView* DataView::Cast(v8::Value* value) {
10412 : #ifdef V8_ENABLE_CHECKS
10413 : CheckCast(value);
10414 : #endif
10415 : return static_cast<DataView*>(value);
10416 : }
10417 :
10418 :
10419 : SharedArrayBuffer* SharedArrayBuffer::Cast(v8::Value* value) {
10420 : #ifdef V8_ENABLE_CHECKS
10421 : CheckCast(value);
10422 : #endif
10423 : return static_cast<SharedArrayBuffer*>(value);
10424 : }
10425 :
10426 :
10427 : Function* Function::Cast(v8::Value* value) {
10428 : #ifdef V8_ENABLE_CHECKS
10429 : CheckCast(value);
10430 : #endif
10431 : return static_cast<Function*>(value);
10432 : }
10433 :
10434 :
10435 : External* External::Cast(v8::Value* value) {
10436 : #ifdef V8_ENABLE_CHECKS
10437 : CheckCast(value);
10438 : #endif
10439 : return static_cast<External*>(value);
10440 : }
10441 :
10442 :
10443 : template<typename T>
10444 : Isolate* PropertyCallbackInfo<T>::GetIsolate() const {
10445 9313654 : return *reinterpret_cast<Isolate**>(&args_[kIsolateIndex]);
10446 : }
10447 :
10448 :
10449 : template<typename T>
10450 : Local<Value> PropertyCallbackInfo<T>::Data() const {
10451 130846 : return Local<Value>(reinterpret_cast<Value*>(&args_[kDataIndex]));
10452 : }
10453 :
10454 :
10455 : template<typename T>
10456 : Local<Object> PropertyCallbackInfo<T>::This() const {
10457 533255 : return Local<Object>(reinterpret_cast<Object*>(&args_[kThisIndex]));
10458 : }
10459 :
10460 :
10461 : template<typename T>
10462 : Local<Object> PropertyCallbackInfo<T>::Holder() const {
10463 1129554 : return Local<Object>(reinterpret_cast<Object*>(&args_[kHolderIndex]));
10464 : }
10465 :
10466 :
10467 : template<typename T>
10468 : ReturnValue<T> PropertyCallbackInfo<T>::GetReturnValue() const {
10469 1793823 : return ReturnValue<T>(&args_[kReturnValueIndex]);
10470 : }
10471 :
10472 : template <typename T>
10473 : bool PropertyCallbackInfo<T>::ShouldThrowOnError() const {
10474 : typedef internal::Internals I;
10475 198 : return args_[kShouldThrowOnErrorIndex] != I::IntToSmi(0);
10476 : }
10477 :
10478 :
10479 : Local<Primitive> Undefined(Isolate* isolate) {
10480 : typedef internal::Address S;
10481 : typedef internal::Internals I;
10482 : I::CheckInitialized(isolate);
10483 : S* slot = I::GetRoot(isolate, I::kUndefinedValueRootIndex);
10484 : return Local<Primitive>(reinterpret_cast<Primitive*>(slot));
10485 : }
10486 :
10487 :
10488 : Local<Primitive> Null(Isolate* isolate) {
10489 : typedef internal::Address S;
10490 : typedef internal::Internals I;
10491 : I::CheckInitialized(isolate);
10492 : S* slot = I::GetRoot(isolate, I::kNullValueRootIndex);
10493 : return Local<Primitive>(reinterpret_cast<Primitive*>(slot));
10494 : }
10495 :
10496 :
10497 : Local<Boolean> True(Isolate* isolate) {
10498 : typedef internal::Address S;
10499 : typedef internal::Internals I;
10500 : I::CheckInitialized(isolate);
10501 : S* slot = I::GetRoot(isolate, I::kTrueValueRootIndex);
10502 : return Local<Boolean>(reinterpret_cast<Boolean*>(slot));
10503 : }
10504 :
10505 :
10506 : Local<Boolean> False(Isolate* isolate) {
10507 : typedef internal::Address S;
10508 : typedef internal::Internals I;
10509 : I::CheckInitialized(isolate);
10510 : S* slot = I::GetRoot(isolate, I::kFalseValueRootIndex);
10511 : return Local<Boolean>(reinterpret_cast<Boolean*>(slot));
10512 : }
10513 :
10514 :
10515 : void Isolate::SetData(uint32_t slot, void* data) {
10516 : typedef internal::Internals I;
10517 : I::SetEmbedderData(this, slot, data);
10518 : }
10519 :
10520 :
10521 : void* Isolate::GetData(uint32_t slot) {
10522 : typedef internal::Internals I;
10523 : return I::GetEmbedderData(this, slot);
10524 : }
10525 :
10526 :
10527 : uint32_t Isolate::GetNumberOfDataSlots() {
10528 : typedef internal::Internals I;
10529 : return I::kNumIsolateDataSlots;
10530 : }
10531 :
10532 : template <class T>
10533 : MaybeLocal<T> Isolate::GetDataFromSnapshotOnce(size_t index) {
10534 85 : T* data = reinterpret_cast<T*>(GetDataFromSnapshotOnce(index));
10535 85 : if (data) internal::PerformCastCheck(data);
10536 : return Local<T>(data);
10537 : }
10538 :
10539 : int64_t Isolate::AdjustAmountOfExternalAllocatedMemory(
10540 : int64_t change_in_bytes) {
10541 : typedef internal::Internals I;
10542 : constexpr int64_t kMemoryReducerActivationLimit = 32 * 1024 * 1024;
10543 : int64_t* external_memory = reinterpret_cast<int64_t*>(
10544 : reinterpret_cast<uint8_t*>(this) + I::kExternalMemoryOffset);
10545 : int64_t* external_memory_limit = reinterpret_cast<int64_t*>(
10546 : reinterpret_cast<uint8_t*>(this) + I::kExternalMemoryLimitOffset);
10547 : int64_t* external_memory_at_last_mc =
10548 : reinterpret_cast<int64_t*>(reinterpret_cast<uint8_t*>(this) +
10549 : I::kExternalMemoryAtLastMarkCompactOffset);
10550 :
10551 7523897 : const int64_t amount = *external_memory + change_in_bytes;
10552 7523892 : *external_memory = amount;
10553 :
10554 : int64_t allocation_diff_since_last_mc =
10555 7523897 : *external_memory - *external_memory_at_last_mc;
10556 : // Only check memory pressure and potentially trigger GC if the amount of
10557 : // external memory increased.
10558 7523897 : if (allocation_diff_since_last_mc > kMemoryReducerActivationLimit) {
10559 2121124 : CheckMemoryPressure();
10560 : }
10561 :
10562 7523876 : if (change_in_bytes < 0) {
10563 3227896 : const int64_t lower_limit = *external_memory_limit + change_in_bytes;
10564 3227896 : if (lower_limit > I::kExternalAllocationSoftLimit)
10565 1844626 : *external_memory_limit = lower_limit;
10566 4295997 : } else if (change_in_bytes > 0 && amount > *external_memory_limit) {
10567 1200536 : ReportExternalAllocationLimitReached();
10568 : }
10569 25 : return *external_memory;
10570 : }
10571 :
10572 : Local<Value> Context::GetEmbedderData(int index) {
10573 : #if !defined(V8_ENABLE_CHECKS) && !defined(V8_COMPRESS_POINTERS)
10574 : typedef internal::Address A;
10575 : typedef internal::Internals I;
10576 : internal::Isolate* isolate = internal::IsolateFromNeverReadOnlySpaceObject(
10577 135 : *reinterpret_cast<A*>(this));
10578 : A* result =
10579 135 : HandleScope::CreateHandle(isolate, I::ReadEmbedderData<A>(this, index));
10580 : return Local<Value>(reinterpret_cast<Value*>(result));
10581 : #else
10582 : return SlowGetEmbedderData(index);
10583 : #endif
10584 : }
10585 :
10586 :
10587 : void* Context::GetAlignedPointerFromEmbedderData(int index) {
10588 : #if !defined(V8_ENABLE_CHECKS) && !defined(V8_COMPRESS_POINTERS)
10589 : typedef internal::Internals I;
10590 : return I::ReadEmbedderData<void*>(this, index);
10591 : #else
10592 : return SlowGetAlignedPointerFromEmbedderData(index);
10593 : #endif
10594 : }
10595 :
10596 : template <class T>
10597 : MaybeLocal<T> Context::GetDataFromSnapshotOnce(size_t index) {
10598 90 : T* data = reinterpret_cast<T*>(GetDataFromSnapshotOnce(index));
10599 90 : if (data) internal::PerformCastCheck(data);
10600 : return Local<T>(data);
10601 : }
10602 :
10603 : template <class T>
10604 : size_t SnapshotCreator::AddData(Local<Context> context, Local<T> object) {
10605 : T* object_ptr = *object;
10606 : internal::Address* p = reinterpret_cast<internal::Address*>(object_ptr);
10607 35 : return AddData(context, *p);
10608 : }
10609 :
10610 : template <class T>
10611 : size_t SnapshotCreator::AddData(Local<T> object) {
10612 : T* object_ptr = *object;
10613 : internal::Address* p = reinterpret_cast<internal::Address*>(object_ptr);
10614 50 : return AddData(*p);
10615 : }
10616 :
10617 : /**
10618 : * \example shell.cc
10619 : * A simple shell that takes a list of expressions on the
10620 : * command-line and executes them.
10621 : */
10622 :
10623 :
10624 : /**
10625 : * \example process.cc
10626 : */
10627 :
10628 :
10629 : } // namespace v8
10630 :
10631 :
10632 : #undef TYPE_CHECK
10633 :
10634 :
10635 : #endif // INCLUDE_V8_H_
|
