v8  9.4.146 (node 16.13.0)
V8 is Google's open source JavaScript engine
v8.h
Go to the documentation of this file.
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 https://v8.dev/.
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 
22 #include <atomic>
23 #include <memory>
24 #include <string>
25 #include <type_traits>
26 #include <utility>
27 #include <vector>
28 
29 #include "cppgc/common.h"
30 #include "v8-internal.h" // NOLINT(build/include_directory)
31 #include "v8-version.h" // NOLINT(build/include_directory)
32 #include "v8config.h" // NOLINT(build/include_directory)
33 
34 // We reserve the V8_* prefix for macros defined in V8 public API and
35 // assume there are no name conflicts with the embedder's code.
36 
37 /**
38  * The v8 JavaScript engine.
39  */
40 namespace v8 {
41 
42 class AccessorSignature;
43 class Array;
44 class ArrayBuffer;
45 class BigInt;
46 class BigIntObject;
47 class Boolean;
48 class BooleanObject;
49 class CFunction;
50 class CallHandlerHelper;
51 class Context;
52 class CppHeap;
53 class CTypeInfo;
54 class Data;
55 class Date;
57 class External;
58 class Function;
59 class FunctionTemplate;
60 class HeapProfiler;
61 class ImplementationUtilities;
62 class Int32;
63 class Integer;
64 class Isolate;
65 class Isolate;
66 class MicrotaskQueue;
67 class Name;
68 class Number;
69 class NumberObject;
70 class Object;
71 class ObjectOperationDescriptor;
72 class ObjectTemplate;
73 class Platform;
74 class Primitive;
75 class PrimitiveArray;
76 class Private;
77 class Promise;
78 class PropertyDescriptor;
79 class Proxy;
80 class RawOperationDescriptor;
81 class Script;
82 class SharedArrayBuffer;
83 class Signature;
84 class StackFrame;
85 class StackTrace;
86 class StartupData;
87 class String;
88 class StringObject;
89 class Symbol;
90 class SymbolObject;
92 class Uint32;
93 class Utils;
94 class Value;
95 class WasmMemoryObject;
96 class WasmModuleObject;
97 template <class K, class V, class T>
98 class GlobalValueMap;
99 template <class K, class V, class T>
101 template<class T> class NonCopyablePersistentTraits;
102 template <class T, class M = NonCopyablePersistentTraits<T>>
103 class Persistent;
104 template <class T>
106 template <class T>
107 class Eternal;
108 template <class T>
109 class Global;
110 template <class T>
111 class Local;
112 template <class T>
113 class Maybe;
114 template <class T>
115 class MaybeLocal;
116 template <class T>
117 class TracedGlobal;
118 template <class T>
119 class TracedReference;
120 template<class K, class V, class T> class PersistentValueMap;
121 template<class T, class P> class WeakCallbackObject;
122 template <class T>
123 class PersistentBase;
124 template <class V, class T>
126 template<typename T> class FunctionCallbackInfo;
127 template<typename T> class PropertyCallbackInfo;
128 template<typename T> class ReturnValue;
129 
130 namespace internal {
131 class BackgroundDeserializeTask;
132 class BasicTracedReferenceExtractor;
133 class ExternalString;
134 class FunctionCallbackArguments;
135 class GlobalHandles;
136 class Heap;
137 class HeapObject;
138 class Isolate;
139 class LocalEmbedderHeapTracer;
140 class MicrotaskQueue;
141 class PropertyCallbackArguments;
142 class ReadOnlyHeap;
143 class ScopedExternalStringLock;
144 class ThreadLocalTop;
145 struct ScriptStreamingData;
146 enum class ArgumentsType;
147 template <ArgumentsType>
148 class Arguments;
149 template <typename T>
151 
152 namespace wasm {
153 class NativeModule;
154 class StreamingDecoder;
155 } // namespace wasm
156 
157 } // namespace internal
158 
159 namespace metrics {
160 class Recorder;
161 } // namespace metrics
162 
163 namespace debug {
164 class ConsoleCallArguments;
165 } // namespace debug
166 
167 // --- Handles ---
168 
169 /**
170  * An object reference managed by the v8 garbage collector.
171  *
172  * All objects returned from v8 have to be tracked by the garbage
173  * collector so that it knows that the objects are still alive. Also,
174  * because the garbage collector may move objects, it is unsafe to
175  * point directly to an object. Instead, all objects are stored in
176  * handles which are known by the garbage collector and updated
177  * whenever an object moves. Handles should always be passed by value
178  * (except in cases like out-parameters) and they should never be
179  * allocated on the heap.
180  *
181  * There are two types of handles: local and persistent handles.
182  *
183  * Local handles are light-weight and transient and typically used in
184  * local operations. They are managed by HandleScopes. That means that a
185  * HandleScope must exist on the stack when they are created and that they are
186  * only valid inside of the HandleScope active during their creation.
187  * For passing a local handle to an outer HandleScope, an EscapableHandleScope
188  * and its Escape() method must be used.
189  *
190  * Persistent handles can be used when storing objects across several
191  * independent operations and have to be explicitly deallocated when they're no
192  * longer used.
193  *
194  * It is safe to extract the object stored in the handle by
195  * dereferencing the handle (for instance, to extract the Object* from
196  * a Local<Object>); the value will still be governed by a handle
197  * behind the scenes and the same rules apply to these values as to
198  * their handles.
199  */
200 template <class T>
201 class Local {
202  public:
203  V8_INLINE Local() : val_(nullptr) {}
204  template <class S>
206  : val_(reinterpret_cast<T*>(*that)) {
207  /**
208  * This check fails when trying to convert between incompatible
209  * handles. For example, converting from a Local<String> to a
210  * Local<Number>.
211  */
212  static_assert(std::is_base_of<T, S>::value, "type check");
213  }
214 
215  /**
216  * Returns true if the handle is empty.
217  */
218  V8_INLINE bool IsEmpty() const { return val_ == nullptr; }
219 
220  /**
221  * Sets the handle to be empty. IsEmpty() will then return true.
222  */
223  V8_INLINE void Clear() { val_ = nullptr; }
224 
225  V8_INLINE T* operator->() const { return val_; }
226 
227  V8_INLINE T* operator*() const { return val_; }
228 
229  /**
230  * Checks whether two handles are the same.
231  * Returns true if both are empty, or if the objects to which they refer
232  * are identical.
233  *
234  * If both handles refer to JS objects, this is the same as strict equality.
235  * For primitives, such as numbers or strings, a `false` return value does not
236  * indicate that the values aren't equal in the JavaScript sense.
237  * Use `Value::StrictEquals()` to check primitives for equality.
238  */
239  template <class S>
240  V8_INLINE bool operator==(const Local<S>& that) const {
241  internal::Address* a = reinterpret_cast<internal::Address*>(this->val_);
242  internal::Address* b = reinterpret_cast<internal::Address*>(that.val_);
243  if (a == nullptr) return b == nullptr;
244  if (b == nullptr) return false;
245  return *a == *b;
246  }
247 
248  template <class S> V8_INLINE bool operator==(
249  const PersistentBase<S>& that) const {
250  internal::Address* a = reinterpret_cast<internal::Address*>(this->val_);
251  internal::Address* b = reinterpret_cast<internal::Address*>(that.val_);
252  if (a == nullptr) return b == nullptr;
253  if (b == nullptr) return false;
254  return *a == *b;
255  }
256 
257  /**
258  * Checks whether two handles are different.
259  * Returns true if only one of the handles is empty, or if
260  * the objects to which they refer are different.
261  *
262  * If both handles refer to JS objects, this is the same as strict
263  * non-equality. For primitives, such as numbers or strings, a `true` return
264  * value does not indicate that the values aren't equal in the JavaScript
265  * sense. Use `Value::StrictEquals()` to check primitives for equality.
266  */
267  template <class S>
268  V8_INLINE bool operator!=(const Local<S>& that) const {
269  return !operator==(that);
270  }
271 
272  template <class S> V8_INLINE bool operator!=(
273  const Persistent<S>& that) const {
274  return !operator==(that);
275  }
276 
277  /**
278  * Cast a handle to a subclass, e.g. Local<Value> to Local<Object>.
279  * This is only valid if the handle actually refers to a value of the
280  * target type.
281  */
282  template <class S> V8_INLINE static Local<T> Cast(Local<S> that) {
283 #ifdef V8_ENABLE_CHECKS
284  // If we're going to perform the type check then we have to check
285  // that the handle isn't empty before doing the checked cast.
286  if (that.IsEmpty()) return Local<T>();
287 #endif
288  return Local<T>(T::Cast(*that));
289  }
290 
291  /**
292  * Calling this is equivalent to Local<S>::Cast().
293  * In particular, this is only valid if the handle actually refers to a value
294  * of the target type.
295  */
296  template <class S>
297  V8_INLINE Local<S> As() const {
298  return Local<S>::Cast(*this);
299  }
300 
301  /**
302  * Create a local handle for the content of another handle.
303  * The referee is kept alive by the local handle even when
304  * the original handle is destroyed/disposed.
305  */
306  V8_INLINE static Local<T> New(Isolate* isolate, Local<T> that);
307  V8_INLINE static Local<T> New(Isolate* isolate,
308  const PersistentBase<T>& that);
309  V8_INLINE static Local<T> New(Isolate* isolate,
310  const BasicTracedReference<T>& that);
311 
312  private:
313  friend class TracedReferenceBase;
314  friend class Utils;
315  template<class F> friend class Eternal;
316  template<class F> friend class PersistentBase;
317  template<class F, class M> friend class Persistent;
318  template<class F> friend class Local;
319  template <class F>
320  friend class MaybeLocal;
321  template<class F> friend class FunctionCallbackInfo;
322  template<class F> friend class PropertyCallbackInfo;
323  friend class String;
324  friend class Object;
325  friend class Context;
326  friend class Isolate;
327  friend class Private;
328  template<class F> friend class internal::CustomArguments;
329  friend Local<Primitive> Undefined(Isolate* isolate);
330  friend Local<Primitive> Null(Isolate* isolate);
331  friend Local<Boolean> True(Isolate* isolate);
332  friend Local<Boolean> False(Isolate* isolate);
333  friend class HandleScope;
334  friend class EscapableHandleScope;
335  template <class F1, class F2, class F3>
337  template<class F1, class F2> friend class PersistentValueVector;
338  template <class F>
339  friend class ReturnValue;
340  template <class F>
341  friend class Traced;
342  template <class F>
343  friend class TracedGlobal;
344  template <class F>
345  friend class BasicTracedReference;
346  template <class F>
347  friend class TracedReference;
348 
349  explicit V8_INLINE Local(T* that) : val_(that) {}
350  V8_INLINE static Local<T> New(Isolate* isolate, T* that);
351  T* val_;
352 };
353 
354 
355 #if !defined(V8_IMMINENT_DEPRECATION_WARNINGS)
356 // Handle is an alias for Local for historical reasons.
357 template <class T>
358 using Handle = Local<T>;
359 #endif
360 
361 
362 /**
363  * A MaybeLocal<> is a wrapper around Local<> that enforces a check whether
364  * the Local<> is empty before it can be used.
365  *
366  * If an API method returns a MaybeLocal<>, the API method can potentially fail
367  * either because an exception is thrown, or because an exception is pending,
368  * e.g. because a previous API call threw an exception that hasn't been caught
369  * yet, or because a TerminateExecution exception was thrown. In that case, an
370  * empty MaybeLocal is returned.
371  */
372 template <class T>
373 class MaybeLocal {
374  public:
375  V8_INLINE MaybeLocal() : val_(nullptr) {}
376  template <class S>
378  : val_(reinterpret_cast<T*>(*that)) {
379  static_assert(std::is_base_of<T, S>::value, "type check");
380  }
381 
382  V8_INLINE bool IsEmpty() const { return val_ == nullptr; }
383 
384  /**
385  * Converts this MaybeLocal<> to a Local<>. If this MaybeLocal<> is empty,
386  * |false| is returned and |out| is left untouched.
387  */
388  template <class S>
390  out->val_ = IsEmpty() ? nullptr : this->val_;
391  return !IsEmpty();
392  }
393 
394  /**
395  * Converts this MaybeLocal<> to a Local<>. If this MaybeLocal<> is empty,
396  * V8 will crash the process.
397  */
399 
400  /**
401  * Converts this MaybeLocal<> to a Local<>, using a default value if this
402  * MaybeLocal<> is empty.
403  */
404  template <class S>
405  V8_INLINE Local<S> FromMaybe(Local<S> default_value) const {
406  return IsEmpty() ? default_value : Local<S>(val_);
407  }
408 
409  private:
410  T* val_;
411 };
412 
413 /**
414  * Eternal handles are set-once handles that live for the lifetime of the
415  * isolate.
416  */
417 template <class T> class Eternal {
418  public:
419  V8_INLINE Eternal() : val_(nullptr) {}
420  template <class S>
421  V8_INLINE Eternal(Isolate* isolate, Local<S> handle) : val_(nullptr) {
422  Set(isolate, handle);
423  }
424  // Can only be safely called if already set.
425  V8_INLINE Local<T> Get(Isolate* isolate) const;
426  V8_INLINE bool IsEmpty() const { return val_ == nullptr; }
427  template<class S> V8_INLINE void Set(Isolate* isolate, Local<S> handle);
428 
429  private:
430  T* val_;
431 };
432 
433 
434 static const int kInternalFieldsInWeakCallback = 2;
435 static const int kEmbedderFieldsInWeakCallback = 2;
436 
437 template <typename T>
439  public:
440  using Callback = void (*)(const WeakCallbackInfo<T>& data);
441 
442  WeakCallbackInfo(Isolate* isolate, T* parameter,
443  void* embedder_fields[kEmbedderFieldsInWeakCallback],
444  Callback* callback)
445  : isolate_(isolate), parameter_(parameter), callback_(callback) {
446  for (int i = 0; i < kEmbedderFieldsInWeakCallback; ++i) {
447  embedder_fields_[i] = embedder_fields[i];
448  }
449  }
450 
451  V8_INLINE Isolate* GetIsolate() const { return isolate_; }
452  V8_INLINE T* GetParameter() const { return parameter_; }
453  V8_INLINE void* GetInternalField(int index) const;
454 
455  // When first called, the embedder MUST Reset() the Global which triggered the
456  // callback. The Global itself is unusable for anything else. No v8 other api
457  // calls may be called in the first callback. Should additional work be
458  // required, the embedder must set a second pass callback, which will be
459  // called after all the initial callbacks are processed.
460  // Calling SetSecondPassCallback on the second pass will immediately crash.
461  void SetSecondPassCallback(Callback callback) const { *callback_ = callback; }
462 
463  private:
464  Isolate* isolate_;
465  T* parameter_;
466  Callback* callback_;
467  void* embedder_fields_[kEmbedderFieldsInWeakCallback];
468 };
469 
470 
471 // kParameter will pass a void* parameter back to the callback, kInternalFields
472 // will pass the first two internal fields back to the callback, kFinalizer
473 // will pass a void* parameter back, but is invoked before the object is
474 // actually collected, so it can be resurrected. In the last case, it is not
475 // possible to request a second pass callback.
477 
478 /**
479  * An object reference that is independent of any handle scope. Where
480  * a Local handle only lives as long as the HandleScope in which it was
481  * allocated, a PersistentBase handle remains valid until it is explicitly
482  * disposed using Reset().
483  *
484  * A persistent handle contains a reference to a storage cell within
485  * the V8 engine which holds an object value and which is updated by
486  * the garbage collector whenever the object is moved. A new storage
487  * cell can be created using the constructor or PersistentBase::Reset and
488  * existing handles can be disposed using PersistentBase::Reset.
489  *
490  */
491 template <class T> class PersistentBase {
492  public:
493  /**
494  * If non-empty, destroy the underlying storage cell
495  * IsEmpty() will return true after this call.
496  */
497  V8_INLINE void Reset();
498  /**
499  * If non-empty, destroy the underlying storage cell
500  * and create a new one with the contents of other if other is non empty
501  */
502  template <class S>
503  V8_INLINE void Reset(Isolate* isolate, const Local<S>& other);
504 
505  /**
506  * If non-empty, destroy the underlying storage cell
507  * and create a new one with the contents of other if other is non empty
508  */
509  template <class S>
510  V8_INLINE void Reset(Isolate* isolate, const PersistentBase<S>& other);
511 
512  V8_INLINE bool IsEmpty() const { return val_ == nullptr; }
513  V8_INLINE void Empty() { val_ = 0; }
514 
515  V8_INLINE Local<T> Get(Isolate* isolate) const {
516  return Local<T>::New(isolate, *this);
517  }
518 
519  template <class S>
520  V8_INLINE bool operator==(const PersistentBase<S>& that) const {
521  internal::Address* a = reinterpret_cast<internal::Address*>(this->val_);
522  internal::Address* b = reinterpret_cast<internal::Address*>(that.val_);
523  if (a == nullptr) return b == nullptr;
524  if (b == nullptr) return false;
525  return *a == *b;
526  }
527 
528  template <class S>
529  V8_INLINE bool operator==(const Local<S>& that) const {
530  internal::Address* a = reinterpret_cast<internal::Address*>(this->val_);
531  internal::Address* b = reinterpret_cast<internal::Address*>(that.val_);
532  if (a == nullptr) return b == nullptr;
533  if (b == nullptr) return false;
534  return *a == *b;
535  }
536 
537  template <class S>
538  V8_INLINE bool operator!=(const PersistentBase<S>& that) const {
539  return !operator==(that);
540  }
541 
542  template <class S>
543  V8_INLINE bool operator!=(const Local<S>& that) const {
544  return !operator==(that);
545  }
546 
547  /**
548  * Install a finalization callback on this object.
549  * NOTE: There is no guarantee as to *when* or even *if* the callback is
550  * invoked. The invocation is performed solely on a best effort basis.
551  * As always, GC-based finalization should *not* be relied upon for any
552  * critical form of resource management!
553  *
554  * The callback is supposed to reset the handle. No further V8 API may be
555  * called in this callback. In case additional work involving V8 needs to be
556  * done, a second callback can be scheduled using
557  * WeakCallbackInfo<void>::SetSecondPassCallback.
558  */
559  template <typename P>
560  V8_INLINE void SetWeak(P* parameter,
561  typename WeakCallbackInfo<P>::Callback callback,
562  WeakCallbackType type);
563 
564  /**
565  * Turns this handle into a weak phantom handle without finalization callback.
566  * The handle will be reset automatically when the garbage collector detects
567  * that the object is no longer reachable.
568  * A related function Isolate::NumberOfPhantomHandleResetsSinceLastCall
569  * returns how many phantom handles were reset by the garbage collector.
570  */
571  V8_INLINE void SetWeak();
572 
573  template<typename P>
575 
576  // TODO(dcarney): remove this.
577  V8_INLINE void ClearWeak() { ClearWeak<void>(); }
578 
579  /**
580  * Annotates the strong handle with the given label, which is then used by the
581  * heap snapshot generator as a name of the edge from the root to the handle.
582  * The function does not take ownership of the label and assumes that the
583  * label is valid as long as the handle is valid.
584  */
585  V8_INLINE void AnnotateStrongRetainer(const char* label);
586 
587  /** Returns true if the handle's reference is weak. */
588  V8_INLINE bool IsWeak() const;
589 
590  /**
591  * Assigns a wrapper class ID to the handle.
592  */
593  V8_INLINE void SetWrapperClassId(uint16_t class_id);
594 
595  /**
596  * Returns the class ID previously assigned to this handle or 0 if no class ID
597  * was previously assigned.
598  */
599  V8_INLINE uint16_t WrapperClassId() const;
600 
601  PersistentBase(const PersistentBase& other) = delete;
602  void operator=(const PersistentBase&) = delete;
603 
604  private:
605  friend class Isolate;
606  friend class Utils;
607  template<class F> friend class Local;
608  template<class F1, class F2> friend class Persistent;
609  template <class F>
610  friend class Global;
611  template<class F> friend class PersistentBase;
612  template<class F> friend class ReturnValue;
613  template <class F1, class F2, class F3>
615  template<class F1, class F2> friend class PersistentValueVector;
616  friend class Object;
617 
618  explicit V8_INLINE PersistentBase(T* val) : val_(val) {}
619  V8_INLINE static T* New(Isolate* isolate, T* that);
620 
621  T* val_;
622 };
623 
624 
625 /**
626  * Default traits for Persistent. This class does not allow
627  * use of the copy constructor or assignment operator.
628  * At present kResetInDestructor is not set, but that will change in a future
629  * version.
630  */
631 template<class T>
632 class NonCopyablePersistentTraits {
633  public:
634  using NonCopyablePersistent = Persistent<T, NonCopyablePersistentTraits<T>>;
635  static const bool kResetInDestructor = false;
636  template<class S, class M>
637  V8_INLINE static void Copy(const Persistent<S, M>& source,
638  NonCopyablePersistent* dest) {
639  static_assert(sizeof(S) < 0,
640  "NonCopyablePersistentTraits::Copy is not instantiable");
641  }
642 };
643 
644 
645 /**
646  * Helper class traits to allow copying and assignment of Persistent.
647  * This will clone the contents of storage cell, but not any of the flags, etc.
648  */
649 template<class T>
651  using CopyablePersistent = Persistent<T, CopyablePersistentTraits<T>>;
652  static const bool kResetInDestructor = true;
653  template<class S, class M>
654  static V8_INLINE void Copy(const Persistent<S, M>& source,
655  CopyablePersistent* dest) {
656  // do nothing, just allow copy
657  }
658 };
659 
660 
661 /**
662  * A PersistentBase which allows copy and assignment.
663  *
664  * Copy, assignment and destructor behavior is controlled by the traits
665  * class M.
666  *
667  * Note: Persistent class hierarchy is subject to future changes.
668  */
669 template <class T, class M> class Persistent : public PersistentBase<T> {
670  public:
671  /**
672  * A Persistent with no storage cell.
673  */
675  /**
676  * Construct a Persistent from a Local.
677  * When the Local 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>
681  V8_INLINE Persistent(Isolate* isolate, Local<S> that)
682  : PersistentBase<T>(PersistentBase<T>::New(isolate, *that)) {
683  static_assert(std::is_base_of<T, S>::value, "type check");
684  }
685  /**
686  * Construct a Persistent from a Persistent.
687  * When the Persistent is non-empty, a new storage cell is created
688  * pointing to the same object, and no flags are set.
689  */
690  template <class S, class M2>
691  V8_INLINE Persistent(Isolate* isolate, const Persistent<S, M2>& that)
692  : PersistentBase<T>(PersistentBase<T>::New(isolate, *that)) {
693  static_assert(std::is_base_of<T, S>::value, "type check");
694  }
695  /**
696  * The copy constructors and assignment operator create a Persistent
697  * exactly as the Persistent constructor, but the Copy function from the
698  * traits class is called, allowing the setting of flags based on the
699  * copied Persistent.
700  */
701  V8_INLINE Persistent(const Persistent& that) : PersistentBase<T>(nullptr) {
702  Copy(that);
703  }
704  template <class S, class M2>
705  V8_INLINE Persistent(const Persistent<S, M2>& that) : PersistentBase<T>(0) {
706  Copy(that);
707  }
709  Copy(that);
710  return *this;
711  }
712  template <class S, class M2>
713  V8_INLINE Persistent& operator=(const Persistent<S, M2>& that) {
714  Copy(that);
715  return *this;
716  }
717  /**
718  * The destructor will dispose the Persistent based on the
719  * kResetInDestructor flags in the traits class. Since not calling dispose
720  * can result in a memory leak, it is recommended to always set this flag.
721  */
723  if (M::kResetInDestructor) this->Reset();
724  }
725 
726  // TODO(dcarney): this is pretty useless, fix or remove
727  template <class S>
728  V8_INLINE static Persistent<T>& Cast(const Persistent<S>& that) {
729 #ifdef V8_ENABLE_CHECKS
730  // If we're going to perform the type check then we have to check
731  // that the handle isn't empty before doing the checked cast.
732  if (!that.IsEmpty()) T::Cast(*that);
733 #endif
734  return reinterpret_cast<Persistent<T>&>(const_cast<Persistent<S>&>(that));
735  }
736 
737  // TODO(dcarney): this is pretty useless, fix or remove
738  template <class S>
739  V8_INLINE Persistent<S>& As() const {
740  return Persistent<S>::Cast(*this);
741  }
742 
743  private:
744  friend class Isolate;
745  friend class Utils;
746  template<class F> friend class Local;
747  template<class F1, class F2> friend class Persistent;
748  template<class F> friend class ReturnValue;
749 
750  explicit V8_INLINE Persistent(T* that) : PersistentBase<T>(that) {}
751  V8_INLINE T* operator*() const { return this->val_; }
752  template<class S, class M2>
753  V8_INLINE void Copy(const Persistent<S, M2>& that);
754 };
755 
756 
757 /**
758  * A PersistentBase which has move semantics.
759  *
760  * Note: Persistent class hierarchy is subject to future changes.
761  */
762 template <class T>
763 class Global : public PersistentBase<T> {
764  public:
765  /**
766  * A Global with no storage cell.
767  */
768  V8_INLINE Global() : PersistentBase<T>(nullptr) {}
769 
770  /**
771  * Construct a Global from a Local.
772  * When the Local is non-empty, a new storage cell is created
773  * pointing to the same object, and no flags are set.
774  */
775  template <class S>
776  V8_INLINE Global(Isolate* isolate, Local<S> that)
777  : PersistentBase<T>(PersistentBase<T>::New(isolate, *that)) {
778  static_assert(std::is_base_of<T, S>::value, "type check");
779  }
780 
781  /**
782  * Construct a Global from a PersistentBase.
783  * When the Persistent is non-empty, a new storage cell is created
784  * pointing to the same object, and no flags are set.
785  */
786  template <class S>
787  V8_INLINE Global(Isolate* isolate, const PersistentBase<S>& that)
788  : PersistentBase<T>(PersistentBase<T>::New(isolate, that.val_)) {
789  static_assert(std::is_base_of<T, S>::value, "type check");
790  }
791 
792  /**
793  * Move constructor.
794  */
795  V8_INLINE Global(Global&& other);
796 
797  V8_INLINE ~Global() { this->Reset(); }
798 
799  /**
800  * Move via assignment.
801  */
802  template <class S>
804 
805  /**
806  * Pass allows returning uniques from functions, etc.
807  */
808  Global Pass() { return static_cast<Global&&>(*this); }
809 
810  /*
811  * For compatibility with Chromium's base::Bind (base::Passed).
812  */
813  using MoveOnlyTypeForCPP03 = void;
814 
815  Global(const Global&) = delete;
816  void operator=(const Global&) = delete;
817 
818  private:
819  template <class F>
820  friend class ReturnValue;
821  V8_INLINE T* operator*() const { return this->val_; }
822 };
823 
824 
825 // UniquePersistent is an alias for Global for historical reason.
826 template <class T>
827 using UniquePersistent = Global<T>;
828 
829 /**
830  * Deprecated. Use |TracedReference<T>| instead.
831  */
832 template <typename T>
834 
836  public:
837  /**
838  * Returns true if the reference is empty, i.e., has not been assigned
839  * object.
840  */
841  bool IsEmpty() const { return val_ == nullptr; }
842 
843  /**
844  * If non-empty, destroy the underlying storage cell. |IsEmpty| will return
845  * true after this call.
846  */
847  V8_INLINE void Reset();
848 
849  /**
850  * Construct a Local<Value> from this handle.
851  */
852  V8_INLINE v8::Local<v8::Value> Get(v8::Isolate* isolate) const;
853 
854  /**
855  * Returns true if this TracedReference is empty, i.e., has not been
856  * assigned an object. This version of IsEmpty is thread-safe.
857  */
858  bool IsEmptyThreadSafe() const {
859  return this->GetSlotThreadSafe() == nullptr;
860  }
861 
862  /**
863  * Assigns a wrapper class ID to the handle.
864  */
865  V8_INLINE void SetWrapperClassId(uint16_t class_id);
866 
867  /**
868  * Returns the class ID previously assigned to this handle or 0 if no class ID
869  * was previously assigned.
870  */
871  V8_INLINE uint16_t WrapperClassId() const;
872 
873  protected:
874  /**
875  * Update this reference in a thread-safe way.
876  */
877  void SetSlotThreadSafe(void* new_val) {
878  reinterpret_cast<std::atomic<void*>*>(&val_)->store(
879  new_val, std::memory_order_relaxed);
880  }
881 
882  /**
883  * Get this reference in a thread-safe way
884  */
885  const void* GetSlotThreadSafe() const {
886  return reinterpret_cast<std::atomic<const void*> const*>(&val_)->load(
887  std::memory_order_relaxed);
888  }
889 
890  V8_EXPORT void CheckValue() const;
891 
892  // val_ points to a GlobalHandles node.
893  internal::Address* val_ = nullptr;
894 
895  friend class internal::BasicTracedReferenceExtractor;
896  template <typename F>
897  friend class Local;
898  template <typename U>
899  friend bool operator==(const TracedReferenceBase&, const Local<U>&);
900  friend bool operator==(const TracedReferenceBase&,
901  const TracedReferenceBase&);
902 };
903 
904 /**
905  * A traced handle with copy and move semantics. The handle is to be used
906  * together with |v8::EmbedderHeapTracer| or as part of GarbageCollected objects
907  * (see v8-cppgc.h) and specifies edges from C++ objects to JavaScript.
908  *
909  * The exact semantics are:
910  * - Tracing garbage collections use |v8::EmbedderHeapTracer| or cppgc.
911  * - Non-tracing garbage collections refer to
912  * |v8::EmbedderRootsHandler::IsRoot()| whether the handle should
913  * be treated as root or not.
914  *
915  * Note that the base class cannot be instantiated itself. Choose from
916  * - TracedGlobal
917  * - TracedReference
918  */
919 template <typename T>
921  public:
922  /**
923  * Construct a Local<T> from this handle.
924  */
925  Local<T> Get(Isolate* isolate) const { return Local<T>::New(isolate, *this); }
926 
927  template <class S>
929  return reinterpret_cast<BasicTracedReference<S>&>(
930  const_cast<BasicTracedReference<T>&>(*this));
931  }
932 
933  T* operator->() const {
934 #ifdef V8_ENABLE_CHECKS
935  CheckValue();
936 #endif // V8_ENABLE_CHECKS
937  return reinterpret_cast<T*>(val_);
938  }
939  T* operator*() const {
940 #ifdef V8_ENABLE_CHECKS
941  CheckValue();
942 #endif // V8_ENABLE_CHECKS
943  return reinterpret_cast<T*>(val_);
944  }
945 
946  private:
947  enum DestructionMode { kWithDestructor, kWithoutDestructor };
948 
949  /**
950  * An empty BasicTracedReference without storage cell.
951  */
952  BasicTracedReference() = default;
953 
954  V8_INLINE static internal::Address* New(Isolate* isolate, T* that, void* slot,
955  DestructionMode destruction_mode);
956 
957  friend class EmbedderHeapTracer;
958  template <typename F>
959  friend class Local;
960  friend class Object;
961  template <typename F>
962  friend class TracedGlobal;
963  template <typename F>
964  friend class TracedReference;
965  template <typename F>
966  friend class BasicTracedReference;
967  template <typename F>
968  friend class ReturnValue;
969 };
970 
971 /**
972  * A traced handle with destructor that clears the handle. For more details see
973  * BasicTracedReference.
974  */
975 template <typename T>
977  public:
978  using BasicTracedReference<T>::Reset;
979 
980  /**
981  * Destructor resetting the handle.Is
982  */
983  ~TracedGlobal() { this->Reset(); }
984 
985  /**
986  * An empty TracedGlobal without storage cell.
987  */
989 
990  /**
991  * Construct a TracedGlobal from a Local.
992  *
993  * When the Local is non-empty, a new storage cell is created
994  * pointing to the same object.
995  */
996  template <class S>
997  TracedGlobal(Isolate* isolate, Local<S> that) : BasicTracedReference<T>() {
998  this->val_ = this->New(isolate, that.val_, &this->val_,
999  BasicTracedReference<T>::kWithDestructor);
1000  static_assert(std::is_base_of<T, S>::value, "type check");
1001  }
1002 
1003  /**
1004  * Move constructor initializing TracedGlobal from an existing one.
1005  */
1007  // Forward to operator=.
1008  *this = std::move(other);
1009  }
1010 
1011  /**
1012  * Move constructor initializing TracedGlobal from an existing one.
1013  */
1014  template <typename S>
1016  // Forward to operator=.
1017  *this = std::move(other);
1018  }
1019 
1020  /**
1021  * Copy constructor initializing TracedGlobal from an existing one.
1022  */
1024  // Forward to operator=;
1025  *this = other;
1026  }
1027 
1028  /**
1029  * Copy constructor initializing TracedGlobal from an existing one.
1030  */
1031  template <typename S>
1033  // Forward to operator=;
1034  *this = other;
1035  }
1036 
1037  /**
1038  * Move assignment operator initializing TracedGlobal from an existing one.
1039  */
1041 
1042  /**
1043  * Move assignment operator initializing TracedGlobal from an existing one.
1044  */
1045  template <class S>
1047 
1048  /**
1049  * Copy assignment operator initializing TracedGlobal from an existing one.
1050  *
1051  * Note: Prohibited when |other| has a finalization callback set through
1052  * |SetFinalizationCallback|.
1053  */
1055 
1056  /**
1057  * Copy assignment operator initializing TracedGlobal from an existing one.
1058  *
1059  * Note: Prohibited when |other| has a finalization callback set through
1060  * |SetFinalizationCallback|.
1061  */
1062  template <class S>
1064 
1065  /**
1066  * If non-empty, destroy the underlying storage cell and create a new one with
1067  * the contents of other if other is non empty
1068  */
1069  template <class S>
1070  V8_INLINE void Reset(Isolate* isolate, const Local<S>& other);
1071 
1072  template <class S>
1073  V8_INLINE TracedGlobal<S>& As() const {
1074  return reinterpret_cast<TracedGlobal<S>&>(
1075  const_cast<TracedGlobal<T>&>(*this));
1076  }
1077 
1078  /**
1079  * Adds a finalization callback to the handle. The type of this callback is
1080  * similar to WeakCallbackType::kInternalFields, i.e., it will pass the
1081  * parameter and the first two internal fields of the object.
1082  *
1083  * The callback is then supposed to reset the handle in the callback. No
1084  * further V8 API may be called in this callback. In case additional work
1085  * involving V8 needs to be done, a second callback can be scheduled using
1086  * WeakCallbackInfo<void>::SetSecondPassCallback.
1087  */
1089  void* parameter, WeakCallbackInfo<void>::Callback callback);
1090 };
1091 
1092 /**
1093  * A traced handle without destructor that clears the handle. The embedder needs
1094  * to ensure that the handle is not accessed once the V8 object has been
1095  * reclaimed. This can happen when the handle is not passed through the
1096  * EmbedderHeapTracer. For more details see BasicTracedReference.
1097  *
1098  * The reference assumes the embedder has precise knowledge about references at
1099  * all times. In case V8 needs to separately handle on-stack references, the
1100  * embedder is required to set the stack start through
1101  * |EmbedderHeapTracer::SetStackStart|.
1102  */
1103 template <typename T>
1105  public:
1106  using BasicTracedReference<T>::Reset;
1107 
1108  /**
1109  * An empty TracedReference without storage cell.
1110  */
1112 
1113  /**
1114  * Construct a TracedReference from a Local.
1115  *
1116  * When the Local is non-empty, a new storage cell is created
1117  * pointing to the same object.
1118  */
1119  template <class S>
1121  this->val_ = this->New(isolate, that.val_, &this->val_,
1122  BasicTracedReference<T>::kWithoutDestructor);
1123  static_assert(std::is_base_of<T, S>::value, "type check");
1124  }
1125 
1126  /**
1127  * Move constructor initializing TracedReference from an
1128  * existing one.
1129  */
1131  // Forward to operator=.
1132  *this = std::move(other);
1133  }
1134 
1135  /**
1136  * Move constructor initializing TracedReference from an
1137  * existing one.
1138  */
1139  template <typename S>
1141  // Forward to operator=.
1142  *this = std::move(other);
1143  }
1144 
1145  /**
1146  * Copy constructor initializing TracedReference from an
1147  * existing one.
1148  */
1150  // Forward to operator=;
1151  *this = other;
1152  }
1153 
1154  /**
1155  * Copy constructor initializing TracedReference from an
1156  * existing one.
1157  */
1158  template <typename S>
1160  // Forward to operator=;
1161  *this = other;
1162  }
1163 
1164  /**
1165  * Move assignment operator initializing TracedGlobal from an existing one.
1166  */
1168 
1169  /**
1170  * Move assignment operator initializing TracedGlobal from an existing one.
1171  */
1172  template <class S>
1174 
1175  /**
1176  * Copy assignment operator initializing TracedGlobal from an existing one.
1177  */
1179 
1180  /**
1181  * Copy assignment operator initializing TracedGlobal from an existing one.
1182  */
1183  template <class S>
1185 
1186  /**
1187  * If non-empty, destroy the underlying storage cell and create a new one with
1188  * the contents of other if other is non empty
1189  */
1190  template <class S>
1191  V8_INLINE void Reset(Isolate* isolate, const Local<S>& other);
1192 
1193  template <class S>
1195  return reinterpret_cast<TracedReference<S>&>(
1196  const_cast<TracedReference<T>&>(*this));
1197  }
1198 };
1199 
1200  /**
1201  * A stack-allocated class that governs a number of local handles.
1202  * After a handle scope has been created, all local handles will be
1203  * allocated within that handle scope until either the handle scope is
1204  * deleted or another handle scope is created. If there is already a
1205  * handle scope and a new one is created, all allocations will take
1206  * place in the new handle scope until it is deleted. After that,
1207  * new handles will again be allocated in the original handle scope.
1208  *
1209  * After the handle scope of a local handle has been deleted the
1210  * garbage collector will no longer track the object stored in the
1211  * handle and may deallocate it. The behavior of accessing a handle
1212  * for which the handle scope has been deleted is undefined.
1213  */
1215  public:
1216  explicit HandleScope(Isolate* isolate);
1217 
1219 
1220  /**
1221  * Counts the number of allocated handles.
1222  */
1223  static int NumberOfHandles(Isolate* isolate);
1224 
1226  return reinterpret_cast<Isolate*>(isolate_);
1227  }
1228 
1229  HandleScope(const HandleScope&) = delete;
1230  void operator=(const HandleScope&) = delete;
1231 
1232  protected:
1233  V8_INLINE HandleScope() = default;
1234 
1235  void Initialize(Isolate* isolate);
1236 
1237  static internal::Address* CreateHandle(internal::Isolate* isolate,
1238  internal::Address value);
1239 
1240  private:
1241  // Declaring operator new and delete as deleted is not spec compliant.
1242  // Therefore declare them private instead to disable dynamic alloc
1243  void* operator new(size_t size);
1244  void* operator new[](size_t size);
1245  void operator delete(void*, size_t);
1246  void operator delete[](void*, size_t);
1247 
1248  internal::Isolate* isolate_;
1249  internal::Address* prev_next_;
1250  internal::Address* prev_limit_;
1251 
1252  // Local::New uses CreateHandle with an Isolate* parameter.
1253  template<class F> friend class Local;
1254 
1255  // Object::GetInternalField and Context::GetEmbedderData use CreateHandle with
1256  // a HeapObject in their shortcuts.
1257  friend class Object;
1258  friend class Context;
1259 };
1260 
1261 /**
1262  * A HandleScope which first allocates a handle in the current scope
1263  * which will be later filled with the escape value.
1264  */
1266  public:
1267  explicit EscapableHandleScope(Isolate* isolate);
1269 
1270  /**
1271  * Pushes the value into the previous scope and returns a handle to it.
1272  * Cannot be called twice.
1273  */
1274  template <class T>
1275  V8_INLINE Local<T> Escape(Local<T> value) {
1276  internal::Address* slot =
1277  Escape(reinterpret_cast<internal::Address*>(*value));
1278  return Local<T>(reinterpret_cast<T*>(slot));
1279  }
1280 
1281  template <class T>
1283  return Escape(value.FromMaybe(Local<T>()));
1284  }
1285 
1287  void operator=(const EscapableHandleScope&) = delete;
1288 
1289  private:
1290  // Declaring operator new and delete as deleted is not spec compliant.
1291  // Therefore declare them private instead to disable dynamic alloc
1292  void* operator new(size_t size);
1293  void* operator new[](size_t size);
1294  void operator delete(void*, size_t);
1295  void operator delete[](void*, size_t);
1296 
1297  internal::Address* Escape(internal::Address* escape_value);
1298  internal::Address* escape_slot_;
1299 };
1300 
1301 /**
1302  * A SealHandleScope acts like a handle scope in which no handle allocations
1303  * are allowed. It can be useful for debugging handle leaks.
1304  * Handles can be allocated within inner normal HandleScopes.
1305  */
1307  public:
1308  explicit SealHandleScope(Isolate* isolate);
1310 
1312  void operator=(const SealHandleScope&) = delete;
1313 
1314  private:
1315  // Declaring operator new and delete as deleted is not spec compliant.
1316  // Therefore declare them private instead to disable dynamic alloc
1317  void* operator new(size_t size);
1318  void* operator new[](size_t size);
1319  void operator delete(void*, size_t);
1320  void operator delete[](void*, size_t);
1321 
1322  internal::Isolate* const isolate_;
1323  internal::Address* prev_limit_;
1324  int prev_sealed_level_;
1325 };
1326 
1327 // --- Special objects ---
1328 
1329 /**
1330  * The superclass of objects that can reside on V8's heap.
1331  */
1333  public:
1334  /**
1335  * Returns true if this data is a |v8::Value|.
1336  */
1337  bool IsValue() const;
1338 
1339  /**
1340  * Returns true if this data is a |v8::Module|.
1341  */
1342  bool IsModule() const;
1343 
1344  /**
1345  * Returns true if this data is a |v8::Private|.
1346  */
1347  bool IsPrivate() const;
1348 
1349  /**
1350  * Returns true if this data is a |v8::ObjectTemplate|.
1351  */
1352  bool IsObjectTemplate() const;
1353 
1354  /**
1355  * Returns true if this data is a |v8::FunctionTemplate|.
1356  */
1357  bool IsFunctionTemplate() const;
1358 
1359  /**
1360  * Returns true if this data is a |v8::Context|.
1361  */
1362  bool IsContext() const;
1363 
1364  private:
1365  Data();
1366 };
1367 
1368 /**
1369  * A container type that holds relevant metadata for module loading.
1370  *
1371  * This is passed back to the embedder as part of
1372  * HostImportModuleDynamicallyCallback for module loading.
1373  */
1375  public:
1376  /**
1377  * The name that was passed by the embedder as ResourceName to the
1378  * ScriptOrigin. This can be either a v8::String or v8::Undefined.
1379  */
1381 
1382  /**
1383  * The options that were passed by the embedder as HostDefinedOptions to
1384  * the ScriptOrigin.
1385  */
1387 };
1388 
1389 /**
1390  * An array to hold Primitive values. This is used by the embedder to
1391  * pass host defined options to the ScriptOptions during compilation.
1392  *
1393  * This is passed back to the embedder as part of
1394  * HostImportModuleDynamicallyCallback for module loading.
1395  *
1396  */
1398  public:
1399  static Local<PrimitiveArray> New(Isolate* isolate, int length);
1400  int Length() const;
1401  void Set(Isolate* isolate, int index, Local<Primitive> item);
1402  Local<Primitive> Get(Isolate* isolate, int index);
1403 };
1404 
1405 /**
1406  * The optional attributes of ScriptOrigin.
1407  */
1409  public:
1410  V8_INLINE ScriptOriginOptions(bool is_shared_cross_origin = false,
1411  bool is_opaque = false, bool is_wasm = false,
1412  bool is_module = false)
1413  : flags_((is_shared_cross_origin ? kIsSharedCrossOrigin : 0) |
1414  (is_wasm ? kIsWasm : 0) | (is_opaque ? kIsOpaque : 0) |
1415  (is_module ? kIsModule : 0)) {}
1417  : flags_(flags &
1418  (kIsSharedCrossOrigin | kIsOpaque | kIsWasm | kIsModule)) {}
1419 
1420  bool IsSharedCrossOrigin() const {
1421  return (flags_ & kIsSharedCrossOrigin) != 0;
1422  }
1423  bool IsOpaque() const { return (flags_ & kIsOpaque) != 0; }
1424  bool IsWasm() const { return (flags_ & kIsWasm) != 0; }
1425  bool IsModule() const { return (flags_ & kIsModule) != 0; }
1426 
1427  int Flags() const { return flags_; }
1428 
1429  private:
1430  enum {
1431  kIsSharedCrossOrigin = 1,
1432  kIsOpaque = 1 << 1,
1433  kIsWasm = 1 << 2,
1434  kIsModule = 1 << 3
1435  };
1436  const int flags_;
1437 };
1438 
1439 /**
1440  * The origin, within a file, of a script.
1441  */
1443  public:
1444  V8_DEPRECATED("Use constructor with primitive C++ types")
1445  V8_INLINE explicit ScriptOrigin(
1446  Local<Value> resource_name, Local<Integer> resource_line_offset,
1447  Local<Integer> resource_column_offset,
1448  Local<Boolean> resource_is_shared_cross_origin = Local<Boolean>(),
1449  Local<Integer> script_id = Local<Integer>(),
1450  Local<Value> source_map_url = Local<Value>(),
1451  Local<Boolean> resource_is_opaque = Local<Boolean>(),
1452  Local<Boolean> is_wasm = Local<Boolean>(),
1453  Local<Boolean> is_module = Local<Boolean>(),
1454  Local<PrimitiveArray> host_defined_options = Local<PrimitiveArray>());
1455  V8_DEPRECATED("Use constructor that takes an isolate")
1456  V8_INLINE explicit ScriptOrigin(
1457  Local<Value> resource_name, int resource_line_offset = 0,
1458  int resource_column_offset = 0,
1459  bool resource_is_shared_cross_origin = false, int script_id = -1,
1460  Local<Value> source_map_url = Local<Value>(),
1461  bool resource_is_opaque = false, bool is_wasm = false,
1462  bool is_module = false,
1463  Local<PrimitiveArray> host_defined_options = Local<PrimitiveArray>());
1464  V8_INLINE explicit ScriptOrigin(
1465  Isolate* isolate, Local<Value> resource_name,
1466  int resource_line_offset = 0, int resource_column_offset = 0,
1467  bool resource_is_shared_cross_origin = false, int script_id = -1,
1468  Local<Value> source_map_url = Local<Value>(),
1469  bool resource_is_opaque = false, bool is_wasm = false,
1470  bool is_module = false,
1471  Local<PrimitiveArray> host_defined_options = Local<PrimitiveArray>());
1472 
1473  V8_INLINE Local<Value> ResourceName() const;
1474  V8_DEPRECATED("Use getter with primitvie C++ types.")
1476  V8_DEPRECATED("Use getter with primitvie C++ types.")
1478  V8_DEPRECATED("Use getter with primitvie C++ types.")
1479  V8_INLINE Local<Integer> ScriptID() const;
1480  V8_INLINE int LineOffset() const;
1481  V8_INLINE int ColumnOffset() const;
1482  V8_INLINE int ScriptId() const;
1483  V8_INLINE Local<Value> SourceMapUrl() const;
1485  V8_INLINE ScriptOriginOptions Options() const { return options_; }
1486 
1487  private:
1488  Isolate* isolate_;
1489  Local<Value> resource_name_;
1490  int resource_line_offset_;
1491  int resource_column_offset_;
1492  ScriptOriginOptions options_;
1493  int script_id_;
1494  Local<Value> source_map_url_;
1495  Local<PrimitiveArray> host_defined_options_;
1496 };
1497 
1498 /**
1499  * A compiled JavaScript script, not yet tied to a Context.
1500  */
1502  public:
1503  /**
1504  * Binds the script to the currently entered context.
1505  */
1507 
1508  int GetId() const;
1510 
1511  /**
1512  * Data read from magic sourceURL comments.
1513  */
1515  /**
1516  * Data read from magic sourceMappingURL comments.
1517  */
1519 
1520  /**
1521  * Returns zero based line number of the code_pos location in the script.
1522  * -1 will be returned if no information available.
1523  */
1524  int GetLineNumber(int code_pos);
1525 
1526  static const int kNoScriptId = 0;
1527 };
1528 
1529 /**
1530  * A compiled JavaScript module, not yet tied to a Context.
1531  */
1533  // Only used as a container for code caching.
1534 };
1535 
1536 /**
1537  * A location in JavaScript source.
1538  */
1540  public:
1541  int GetLineNumber() { return line_number_; }
1542  int GetColumnNumber() { return column_number_; }
1543 
1544  Location(int line_number, int column_number)
1545  : line_number_(line_number), column_number_(column_number) {}
1546 
1547  private:
1548  int line_number_;
1549  int column_number_;
1550 };
1551 
1552 /**
1553  * A fixed-sized array with elements of type Data.
1554  */
1555 class V8_EXPORT FixedArray : public Data {
1556  public:
1557  int Length() const;
1558  Local<Data> Get(Local<Context> context, int i) const;
1559 };
1560 
1561 class V8_EXPORT ModuleRequest : public Data {
1562  public:
1563  /**
1564  * Returns the module specifier for this ModuleRequest.
1565  */
1567 
1568  /**
1569  * Returns the source code offset of this module request.
1570  * Use Module::SourceOffsetToLocation to convert this to line/column numbers.
1571  */
1572  int GetSourceOffset() const;
1573 
1574  /**
1575  * Contains the import assertions for this request in the form:
1576  * [key1, value1, source_offset1, key2, value2, source_offset2, ...].
1577  * The keys and values are of type v8::String, and the source offsets are of
1578  * type Int32. Use Module::SourceOffsetToLocation to convert the source
1579  * offsets to Locations with line/column numbers.
1580  *
1581  * All assertions present in the module request will be supplied in this
1582  * list, regardless of whether they are supported by the host. Per
1583  * https://tc39.es/proposal-import-assertions/#sec-hostgetsupportedimportassertions,
1584  * hosts are expected to ignore assertions that they do not support (as
1585  * opposed to, for example, triggering an error if an unsupported assertion is
1586  * present).
1587  */
1589 
1590  V8_INLINE static ModuleRequest* Cast(Data* data);
1591 
1592  private:
1593  static void CheckCast(Data* obj);
1594 };
1595 
1596 /**
1597  * A compiled JavaScript module.
1598  */
1599 class V8_EXPORT Module : public Data {
1600  public:
1601  /**
1602  * The different states a module can be in.
1603  *
1604  * This corresponds to the states used in ECMAScript except that "evaluated"
1605  * is split into kEvaluated and kErrored, indicating success and failure,
1606  * respectively.
1607  */
1608  enum Status {
1614  kErrored
1615  };
1616 
1617  /**
1618  * Returns the module's current status.
1619  */
1621 
1622  /**
1623  * For a module in kErrored status, this returns the corresponding exception.
1624  */
1626 
1627  /**
1628  * Returns the number of modules requested by this module.
1629  */
1630  V8_DEPRECATED("Use Module::GetModuleRequests() and FixedArray::Length().")
1631  int GetModuleRequestsLength() const;
1632 
1633  /**
1634  * Returns the ith module specifier in this module.
1635  * i must be < GetModuleRequestsLength() and >= 0.
1636  */
1638  "Use Module::GetModuleRequests() and ModuleRequest::GetSpecifier().")
1639  Local<String> GetModuleRequest(int i) const;
1640 
1641  /**
1642  * Returns the source location (line number and column number) of the ith
1643  * module specifier's first occurrence in this module.
1644  */
1646  "Use Module::GetModuleRequests(), ModuleRequest::GetSourceOffset(), and "
1647  "Module::SourceOffsetToLocation().")
1648  Location GetModuleRequestLocation(int i) const;
1649 
1650  /**
1651  * Returns the ModuleRequests for this module.
1652  */
1654 
1655  /**
1656  * For the given source text offset in this module, returns the corresponding
1657  * Location with line and column numbers.
1658  */
1660 
1661  /**
1662  * Returns the identity hash for this object.
1663  */
1664  int GetIdentityHash() const;
1665 
1666  using ResolveCallback V8_DEPRECATED("Use ResolveModuleCallback") =
1667  MaybeLocal<Module> (*)(Local<Context> context, Local<String> specifier,
1668  Local<Module> referrer);
1669  using ResolveModuleCallback = MaybeLocal<Module> (*)(
1670  Local<Context> context, Local<String> specifier,
1671  Local<FixedArray> import_assertions, Local<Module> referrer);
1672 
1673  /**
1674  * Instantiates the module and its dependencies.
1675  *
1676  * Returns an empty Maybe<bool> if an exception occurred during
1677  * instantiation. (In the case where the callback throws an exception, that
1678  * exception is propagated.)
1679  */
1681  "Use the version of InstantiateModule that takes a ResolveModuleCallback "
1682  "parameter")
1683  V8_WARN_UNUSED_RESULT Maybe<bool> InstantiateModule(Local<Context> context,
1684  ResolveCallback callback);
1686  Local<Context> context, ResolveModuleCallback callback);
1687 
1688  /**
1689  * Evaluates the module and its dependencies.
1690  *
1691  * If status is kInstantiated, run the module's code and return a Promise
1692  * object. On success, set status to kEvaluated and resolve the Promise with
1693  * the completion value; on failure, set status to kErrored and reject the
1694  * Promise with the error.
1695  *
1696  * If IsGraphAsync() is false, the returned Promise is settled.
1697  */
1699 
1700  /**
1701  * Returns the namespace object of this module.
1702  *
1703  * The module's status must be at least kInstantiated.
1704  */
1706 
1707  /**
1708  * Returns the corresponding context-unbound module script.
1709  *
1710  * The module must be unevaluated, i.e. its status must not be kEvaluating,
1711  * kEvaluated or kErrored.
1712  */
1714 
1715  /**
1716  * Returns the underlying script's id.
1717  *
1718  * The module must be a SourceTextModule and must not have a kErrored status.
1719  */
1720  int ScriptId() const;
1721 
1722  /**
1723  * Returns whether this module or any of its requested modules is async,
1724  * i.e. contains top-level await.
1725  *
1726  * The module's status must be at least kInstantiated.
1727  */
1728  bool IsGraphAsync() const;
1729 
1730  /**
1731  * Returns whether the module is a SourceTextModule.
1732  */
1733  bool IsSourceTextModule() const;
1734 
1735  /**
1736  * Returns whether the module is a SyntheticModule.
1737  */
1738  bool IsSyntheticModule() const;
1739 
1740  /*
1741  * Callback defined in the embedder. This is responsible for setting
1742  * the module's exported values with calls to SetSyntheticModuleExport().
1743  * The callback must return a resolved Promise to indicate success (where no
1744  * exception was thrown) and return an empy MaybeLocal to indicate falure
1745  * (where an exception was thrown).
1746  */
1747  using SyntheticModuleEvaluationSteps =
1748  MaybeLocal<Value> (*)(Local<Context> context, Local<Module> module);
1749 
1750  /**
1751  * Creates a new SyntheticModule with the specified export names, where
1752  * evaluation_steps will be executed upon module evaluation.
1753  * export_names must not contain duplicates.
1754  * module_name is used solely for logging/debugging and doesn't affect module
1755  * behavior.
1756  */
1758  Isolate* isolate, Local<String> module_name,
1759  const std::vector<Local<String>>& export_names,
1760  SyntheticModuleEvaluationSteps evaluation_steps);
1761 
1762  /**
1763  * Set this module's exported value for the name export_name to the specified
1764  * export_value. This method must be called only on Modules created via
1765  * CreateSyntheticModule. An error will be thrown if export_name is not one
1766  * of the export_names that were passed in that CreateSyntheticModule call.
1767  * Returns Just(true) on success, Nothing<bool>() if an error was thrown.
1768  */
1770  Isolate* isolate, Local<String> export_name, Local<Value> export_value);
1771 
1772  V8_INLINE static Module* Cast(Data* data);
1773 
1774  private:
1775  static void CheckCast(Data* obj);
1776 };
1777 
1778 /**
1779  * A compiled JavaScript script, tied to a Context which was active when the
1780  * script was compiled.
1781  */
1783  public:
1784  /**
1785  * A shorthand for ScriptCompiler::Compile().
1786  */
1788  Local<Context> context, Local<String> source,
1789  ScriptOrigin* origin = nullptr);
1790 
1791  /**
1792  * Runs the script returning the resulting value. It will be run in the
1793  * context in which it was created (ScriptCompiler::CompileBound or
1794  * UnboundScript::BindToCurrentContext()).
1795  */
1797 
1798  /**
1799  * Returns the corresponding context-unbound script.
1800  */
1802 };
1803 
1804 enum class ScriptType { kClassic, kModule };
1805 
1806 /**
1807  * For compiling scripts.
1808  */
1810  public:
1811  class ConsumeCodeCacheTask;
1812 
1813  /**
1814  * Compilation data that the embedder can cache and pass back to speed up
1815  * future compilations. The data is produced if the CompilerOptions passed to
1816  * the compilation functions in ScriptCompiler contains produce_data_to_cache
1817  * = true. The data to cache can then can be retrieved from
1818  * UnboundScript.
1819  */
1823  BufferOwned
1824  };
1825 
1827  : data(nullptr),
1828  length(0),
1829  rejected(false),
1831 
1832  // If buffer_policy is BufferNotOwned, the caller keeps the ownership of
1833  // data and guarantees that it stays alive until the CachedData object is
1834  // destroyed. If the policy is BufferOwned, the given data will be deleted
1835  // (with delete[]) when the CachedData object is destroyed.
1836  CachedData(const uint8_t* data, int length,
1837  BufferPolicy buffer_policy = BufferNotOwned);
1839  // TODO(marja): Async compilation; add constructors which take a callback
1840  // which will be called when V8 no longer needs the data.
1841  const uint8_t* data;
1842  int length;
1843  bool rejected;
1845 
1846  // Prevent copying.
1847  CachedData(const CachedData&) = delete;
1848  CachedData& operator=(const CachedData&) = delete;
1849  };
1850 
1851  /**
1852  * Source code which can be then compiled to a UnboundScript or Script.
1853  */
1854  class Source {
1855  public:
1856  // Source takes ownership of both CachedData and CodeCacheConsumeTask.
1857  V8_INLINE Source(Local<String> source_string, const ScriptOrigin& origin,
1858  CachedData* cached_data = nullptr,
1859  ConsumeCodeCacheTask* consume_cache_task = nullptr);
1860  // Source takes ownership of both CachedData and CodeCacheConsumeTask.
1861  V8_INLINE explicit Source(
1862  Local<String> source_string, CachedData* cached_data = nullptr,
1863  ConsumeCodeCacheTask* consume_cache_task = nullptr);
1864  V8_INLINE ~Source() = default;
1865 
1866  // Ownership of the CachedData or its buffers is *not* transferred to the
1867  // caller. The CachedData object is alive as long as the Source object is
1868  // alive.
1869  V8_INLINE const CachedData* GetCachedData() const;
1870 
1872 
1873  private:
1874  friend class ScriptCompiler;
1875 
1876  Local<String> source_string;
1877 
1878  // Origin information
1879  Local<Value> resource_name;
1880  int resource_line_offset;
1881  int resource_column_offset;
1882  ScriptOriginOptions resource_options;
1883  Local<Value> source_map_url;
1884  Local<PrimitiveArray> host_defined_options;
1885 
1886  // Cached data from previous compilation (if a kConsume*Cache flag is
1887  // set), or hold newly generated cache data (kProduce*Cache flags) are
1888  // set when calling a compile method.
1889  std::unique_ptr<CachedData> cached_data;
1890  std::unique_ptr<ConsumeCodeCacheTask> consume_cache_task;
1891  };
1892 
1893  /**
1894  * For streaming incomplete script data to V8. The embedder should implement a
1895  * subclass of this class.
1896  */
1898  public:
1899  virtual ~ExternalSourceStream() = default;
1900 
1901  /**
1902  * V8 calls this to request the next chunk of data from the embedder. This
1903  * function will be called on a background thread, so it's OK to block and
1904  * wait for the data, if the embedder doesn't have data yet. Returns the
1905  * length of the data returned. When the data ends, GetMoreData should
1906  * return 0. Caller takes ownership of the data.
1907  *
1908  * When streaming UTF-8 data, V8 handles multi-byte characters split between
1909  * two data chunks, but doesn't handle multi-byte characters split between
1910  * more than two data chunks. The embedder can avoid this problem by always
1911  * returning at least 2 bytes of data.
1912  *
1913  * When streaming UTF-16 data, V8 does not handle characters split between
1914  * two data chunks. The embedder has to make sure that chunks have an even
1915  * length.
1916  *
1917  * If the embedder wants to cancel the streaming, they should make the next
1918  * GetMoreData call return 0. V8 will interpret it as end of data (and most
1919  * probably, parsing will fail). The streaming task will return as soon as
1920  * V8 has parsed the data it received so far.
1921  */
1922  virtual size_t GetMoreData(const uint8_t** src) = 0;
1923 
1924  /**
1925  * V8 calls this method to set a 'bookmark' at the current position in
1926  * the source stream, for the purpose of (maybe) later calling
1927  * ResetToBookmark. If ResetToBookmark is called later, then subsequent
1928  * calls to GetMoreData should return the same data as they did when
1929  * SetBookmark was called earlier.
1930  *
1931  * The embedder may return 'false' to indicate it cannot provide this
1932  * functionality.
1933  */
1934  virtual bool SetBookmark();
1935 
1936  /**
1937  * V8 calls this to return to a previously set bookmark.
1938  */
1939  virtual void ResetToBookmark();
1940  };
1941 
1942  /**
1943  * Source code which can be streamed into V8 in pieces. It will be parsed
1944  * while streaming and compiled after parsing has completed. StreamedSource
1945  * must be kept alive while the streaming task is run (see ScriptStreamingTask
1946  * below).
1947  */
1949  public:
1951 
1952  StreamedSource(std::unique_ptr<ExternalSourceStream> source_stream,
1953  Encoding encoding);
1955 
1956  internal::ScriptStreamingData* impl() const { return impl_.get(); }
1957 
1958  // Prevent copying.
1959  StreamedSource(const StreamedSource&) = delete;
1961 
1962  private:
1963  std::unique_ptr<internal::ScriptStreamingData> impl_;
1964  };
1965 
1966  /**
1967  * A streaming task which the embedder must run on a background thread to
1968  * stream scripts into V8. Returned by ScriptCompiler::StartStreaming.
1969  */
1970  class V8_EXPORT ScriptStreamingTask final {
1971  public:
1972  void Run();
1973 
1974  private:
1975  friend class ScriptCompiler;
1976 
1977  explicit ScriptStreamingTask(internal::ScriptStreamingData* data)
1978  : data_(data) {}
1979 
1980  internal::ScriptStreamingData* data_;
1981  };
1982 
1983  /**
1984  * A task which the embedder must run on a background thread to
1985  * consume a V8 code cache. Returned by
1986  * ScriptCompiler::StarConsumingCodeCache.
1987  */
1988  class V8_EXPORT ConsumeCodeCacheTask final {
1989  public:
1991 
1992  void Run();
1993 
1994  private:
1995  friend class ScriptCompiler;
1996 
1997  explicit ConsumeCodeCacheTask(
1998  std::unique_ptr<internal::BackgroundDeserializeTask> impl);
1999 
2000  std::unique_ptr<internal::BackgroundDeserializeTask> impl_;
2001  };
2002 
2007  };
2008 
2009  /**
2010  * The reason for which we are not requesting or providing a code cache.
2011  */
2028  };
2029 
2030  /**
2031  * Compiles the specified script (context-independent).
2032  * Cached data as part of the source object can be optionally produced to be
2033  * consumed later to speed up compilation of identical source scripts.
2034  *
2035  * Note that when producing cached data, the source must point to NULL for
2036  * cached data. When consuming cached data, the cached data must have been
2037  * produced by the same version of V8, and the embedder needs to ensure the
2038  * cached data is the correct one for the given script.
2039  *
2040  * \param source Script source code.
2041  * \return Compiled script object (context independent; for running it must be
2042  * bound to a context).
2043  */
2045  Isolate* isolate, Source* source,
2047  NoCacheReason no_cache_reason = kNoCacheNoReason);
2048 
2049  /**
2050  * Compiles the specified script (bound to current context).
2051  *
2052  * \param source Script source code.
2053  * \param pre_data Pre-parsing data, as obtained by ScriptData::PreCompile()
2054  * using pre_data speeds compilation if it's done multiple times.
2055  * Owned by caller, no references are kept when this function returns.
2056  * \return Compiled script object, bound to the context that was active
2057  * when this function was called. When run it will always use this
2058  * context.
2059  */
2061  Local<Context> context, Source* source,
2063  NoCacheReason no_cache_reason = kNoCacheNoReason);
2064 
2065  /**
2066  * Returns a task which streams script data into V8, or NULL if the script
2067  * cannot be streamed. The user is responsible for running the task on a
2068  * background thread and deleting it. When ran, the task starts parsing the
2069  * script, and it will request data from the StreamedSource as needed. When
2070  * ScriptStreamingTask::Run exits, all data has been streamed and the script
2071  * can be compiled (see Compile below).
2072  *
2073  * This API allows to start the streaming with as little data as possible, and
2074  * the remaining data (for example, the ScriptOrigin) is passed to Compile.
2075  */
2076  static ScriptStreamingTask* StartStreaming(
2077  Isolate* isolate, StreamedSource* source,
2079 
2080  static ConsumeCodeCacheTask* StartConsumingCodeCache(
2081  Isolate* isolate, std::unique_ptr<CachedData> source);
2082 
2083  /**
2084  * Compiles a streamed script (bound to current context).
2085  *
2086  * This can only be called after the streaming has finished
2087  * (ScriptStreamingTask has been run). V8 doesn't construct the source string
2088  * during streaming, so the embedder needs to pass the full source here.
2089  */
2091  Local<Context> context, StreamedSource* source,
2092  Local<String> full_source_string, const ScriptOrigin& origin);
2093 
2094  /**
2095  * Return a version tag for CachedData for the current V8 version & flags.
2096  *
2097  * This value is meant only for determining whether a previously generated
2098  * CachedData instance is still valid; the tag has no other meaing.
2099  *
2100  * Background: The data carried by CachedData may depend on the exact
2101  * V8 version number or current compiler flags. This means that when
2102  * persisting CachedData, the embedder must take care to not pass in
2103  * data from another V8 version, or the same version with different
2104  * features enabled.
2105  *
2106  * The easiest way to do so is to clear the embedder's cache on any
2107  * such change.
2108  *
2109  * Alternatively, this tag can be stored alongside the cached data and
2110  * compared when it is being used.
2111  */
2112  static uint32_t CachedDataVersionTag();
2113 
2114  /**
2115  * Compile an ES module, returning a Module that encapsulates
2116  * the compiled code.
2117  *
2118  * Corresponds to the ParseModule abstract operation in the
2119  * ECMAScript specification.
2120  */
2122  Isolate* isolate, Source* source,
2124  NoCacheReason no_cache_reason = kNoCacheNoReason);
2125 
2126  /**
2127  * Compiles a streamed module script.
2128  *
2129  * This can only be called after the streaming has finished
2130  * (ScriptStreamingTask has been run). V8 doesn't construct the source string
2131  * during streaming, so the embedder needs to pass the full source here.
2132  */
2134  Local<Context> context, StreamedSource* v8_source,
2135  Local<String> full_source_string, const ScriptOrigin& origin);
2136 
2137  /**
2138  * Compile a function for a given context. This is equivalent to running
2139  *
2140  * with (obj) {
2141  * return function(args) { ... }
2142  * }
2143  *
2144  * It is possible to specify multiple context extensions (obj in the above
2145  * example).
2146  */
2148  Local<Context> context, Source* source, size_t arguments_count,
2149  Local<String> arguments[], size_t context_extension_count,
2150  Local<Object> context_extensions[],
2152  NoCacheReason no_cache_reason = kNoCacheNoReason,
2153  Local<ScriptOrModule>* script_or_module_out = nullptr);
2154 
2155  /**
2156  * Creates and returns code cache for the specified unbound_script.
2157  * This will return nullptr if the script cannot be serialized. The
2158  * CachedData returned by this function should be owned by the caller.
2159  */
2160  static CachedData* CreateCodeCache(Local<UnboundScript> unbound_script);
2161 
2162  /**
2163  * Creates and returns code cache for the specified unbound_module_script.
2164  * This will return nullptr if the script cannot be serialized. The
2165  * CachedData returned by this function should be owned by the caller.
2166  */
2168  Local<UnboundModuleScript> unbound_module_script);
2169 
2170  /**
2171  * Creates and returns code cache for the specified function that was
2172  * previously produced by CompileFunctionInContext.
2173  * This will return nullptr if the script cannot be serialized. The
2174  * CachedData returned by this function should be owned by the caller.
2175  */
2177 
2178  private:
2179  static V8_WARN_UNUSED_RESULT MaybeLocal<UnboundScript> CompileUnboundInternal(
2180  Isolate* isolate, Source* source, CompileOptions options,
2181  NoCacheReason no_cache_reason);
2182 };
2183 
2184 
2185 /**
2186  * An error message.
2187  */
2189  public:
2190  Local<String> Get() const;
2191 
2192  /**
2193  * Return the isolate to which the Message belongs.
2194  */
2196 
2198  Local<Context> context) const;
2200  Local<Context> context) const;
2201 
2202  /**
2203  * Returns the origin for the script from where the function causing the
2204  * error originates.
2205  */
2207 
2208  /**
2209  * Returns the resource name for the script from where the function causing
2210  * the error originates.
2211  */
2213 
2214  /**
2215  * Exception stack trace. By default stack traces are not captured for
2216  * uncaught exceptions. SetCaptureStackTraceForUncaughtExceptions allows
2217  * to change this option.
2218  */
2220 
2221  /**
2222  * Returns the number, 1-based, of the line where the error occurred.
2223  */
2225 
2226  /**
2227  * Returns the index within the script of the first character where
2228  * the error occurred.
2229  */
2230  int GetStartPosition() const;
2231 
2232  /**
2233  * Returns the index within the script of the last character where
2234  * the error occurred.
2235  */
2236  int GetEndPosition() const;
2237 
2238  /**
2239  * Returns the Wasm function index where the error occurred. Returns -1 if
2240  * message is not from a Wasm script.
2241  */
2243 
2244  /**
2245  * Returns the error level of the message.
2246  */
2247  int ErrorLevel() const;
2248 
2249  /**
2250  * Returns the index within the line of the first character where
2251  * the error occurred.
2252  */
2253  int GetStartColumn() const;
2255 
2256  /**
2257  * Returns the index within the line of the last character where
2258  * the error occurred.
2259  */
2260  int GetEndColumn() const;
2262 
2263  /**
2264  * Passes on the value set by the embedder when it fed the script from which
2265  * this Message was generated to V8.
2266  */
2267  bool IsSharedCrossOrigin() const;
2268  bool IsOpaque() const;
2269 
2270  // TODO(1245381): Print to a string instead of on a FILE.
2271  static void PrintCurrentStackTrace(Isolate* isolate, FILE* out);
2272 
2273  static const int kNoLineNumberInfo = 0;
2274  static const int kNoColumnInfo = 0;
2275  static const int kNoScriptIdInfo = 0;
2276  static const int kNoWasmFunctionIndexInfo = -1;
2277 };
2278 
2279 
2280 /**
2281  * Representation of a JavaScript stack trace. The information collected is a
2282  * snapshot of the execution stack and the information remains valid after
2283  * execution continues.
2284  */
2286  public:
2287  /**
2288  * Flags that determine what information is placed captured for each
2289  * StackFrame when grabbing the current stack trace.
2290  * Note: these options are deprecated and we always collect all available
2291  * information (kDetailed).
2292  */
2296  kScriptName = 1 << 2,
2297  kFunctionName = 1 << 3,
2298  kIsEval = 1 << 4,
2299  kIsConstructor = 1 << 5,
2301  kScriptId = 1 << 7,
2305  };
2306 
2307  /**
2308  * Returns a StackFrame at a particular index.
2309  */
2310  Local<StackFrame> GetFrame(Isolate* isolate, uint32_t index) const;
2311 
2312  /**
2313  * Returns the number of StackFrames.
2314  */
2315  int GetFrameCount() const;
2316 
2317  /**
2318  * Grab a snapshot of the current JavaScript execution stack.
2319  *
2320  * \param frame_limit The maximum number of stack frames we want to capture.
2321  * \param options Enumerates the set of things we will capture for each
2322  * StackFrame.
2323  */
2325  Isolate* isolate, int frame_limit, StackTraceOptions options = kDetailed);
2326 };
2327 
2328 
2329 /**
2330  * A single JavaScript stack frame.
2331  */
2333  public:
2334  /**
2335  * Returns the number, 1-based, of the line for the associate function call.
2336  * This method will return Message::kNoLineNumberInfo if it is unable to
2337  * retrieve the line number, or if kLineNumber was not passed as an option
2338  * when capturing the StackTrace.
2339  */
2340  int GetLineNumber() const;
2341 
2342  /**
2343  * Returns the 1-based column offset on the line for the associated function
2344  * call.
2345  * This method will return Message::kNoColumnInfo if it is unable to retrieve
2346  * the column number, or if kColumnOffset was not passed as an option when
2347  * capturing the StackTrace.
2348  */
2349  int GetColumn() const;
2350 
2351  /**
2352  * Returns the id of the script for the function for this StackFrame.
2353  * This method will return Message::kNoScriptIdInfo if it is unable to
2354  * retrieve the script id, or if kScriptId was not passed as an option when
2355  * capturing the StackTrace.
2356  */
2357  int GetScriptId() const;
2358 
2359  /**
2360  * Returns the name of the resource that contains the script for the
2361  * function for this StackFrame.
2362  */
2364 
2365  /**
2366  * Returns the name of the resource that contains the script for the
2367  * function for this StackFrame or sourceURL value if the script name
2368  * is undefined and its source ends with //# sourceURL=... string or
2369  * deprecated //@ sourceURL=... string.
2370  */
2372 
2373  /**
2374  * Returns the source of the script for the function for this StackFrame.
2375  */
2377 
2378  /**
2379  * Returns the source mapping URL (if one is present) of the script for
2380  * the function for this StackFrame.
2381  */
2383 
2384  /**
2385  * Returns the name of the function associated with this stack frame.
2386  */
2388 
2389  /**
2390  * Returns whether or not the associated function is compiled via a call to
2391  * eval().
2392  */
2393  bool IsEval() const;
2394 
2395  /**
2396  * Returns whether or not the associated function is called as a
2397  * constructor via "new".
2398  */
2399  bool IsConstructor() const;
2400 
2401  /**
2402  * Returns whether or not the associated functions is defined in wasm.
2403  */
2404  bool IsWasm() const;
2405 
2406  /**
2407  * Returns whether or not the associated function is defined by the user.
2408  */
2409  bool IsUserJavaScript() const;
2410 };
2411 
2412 
2413 // A StateTag represents a possible state of the VM.
2414 enum StateTag {
2423  IDLE
2424 };
2425 
2426 // Holds the callee saved registers needed for the stack unwinder. It is the
2427 // empty struct if no registers are required. Implemented in
2428 // include/v8-unwinder-state.h.
2429 struct CalleeSavedRegisters;
2430 
2431 // A RegisterState represents the current state of registers used
2432 // by the sampling profiler API.
2438 
2439  void* pc; // Instruction pointer.
2440  void* sp; // Stack pointer.
2441  void* fp; // Frame pointer.
2442  void* lr; // Link register (or nullptr on platforms without a link register).
2443  // Callee saved registers (or null if no callee saved registers were stored)
2444  std::unique_ptr<CalleeSavedRegisters> callee_saved;
2445 };
2446 
2447 // The output structure filled up by GetStackSample API function.
2448 struct SampleInfo {
2449  size_t frames_count; // Number of frames collected.
2450  StateTag vm_state; // Current VM state.
2451  void* external_callback_entry; // External callback address if VM is
2452  // executing an external callback.
2453  void* context; // Incumbent native context address.
2454 };
2455 
2456 struct MemoryRange {
2457  const void* start = nullptr;
2458  size_t length_in_bytes = 0;
2459 };
2460 
2461 struct JSEntryStub {
2463 };
2464 
2469 };
2470 
2471 /**
2472  * A JSON Parser and Stringifier.
2473  */
2475  public:
2476  /**
2477  * Tries to parse the string |json_string| and returns it as value if
2478  * successful.
2479  *
2480  * \param the context in which to parse and create the value.
2481  * \param json_string The string to parse.
2482  * \return The corresponding value if successfully parsed.
2483  */
2485  Local<Context> context, Local<String> json_string);
2486 
2487  /**
2488  * Tries to stringify the JSON-serializable object |json_object| and returns
2489  * it as string if successful.
2490  *
2491  * \param json_object The JSON-serializable object to stringify.
2492  * \return The corresponding string if successfully stringified.
2493  */
2495  Local<Context> context, Local<Value> json_object,
2496  Local<String> gap = Local<String>());
2497 };
2498 
2499 /**
2500  * Value serialization compatible with the HTML structured clone algorithm.
2501  * The format is backward-compatible (i.e. safe to store to disk).
2502  */
2504  public:
2506  public:
2507  virtual ~Delegate() = default;
2508 
2509  /**
2510  * Handles the case where a DataCloneError would be thrown in the structured
2511  * clone spec. Other V8 embedders may throw some other appropriate exception
2512  * type.
2513  */
2514  virtual void ThrowDataCloneError(Local<String> message) = 0;
2515 
2516  /**
2517  * The embedder overrides this method to write some kind of host object, if
2518  * possible. If not, a suitable exception should be thrown and
2519  * Nothing<bool>() returned.
2520  */
2521  virtual Maybe<bool> WriteHostObject(Isolate* isolate, Local<Object> object);
2522 
2523  /**
2524  * Called when the ValueSerializer is going to serialize a
2525  * SharedArrayBuffer object. The embedder must return an ID for the
2526  * object, using the same ID if this SharedArrayBuffer has already been
2527  * serialized in this buffer. When deserializing, this ID will be passed to
2528  * ValueDeserializer::GetSharedArrayBufferFromId as |clone_id|.
2529  *
2530  * If the object cannot be serialized, an
2531  * exception should be thrown and Nothing<uint32_t>() returned.
2532  */
2533  virtual Maybe<uint32_t> GetSharedArrayBufferId(
2534  Isolate* isolate, Local<SharedArrayBuffer> shared_array_buffer);
2535 
2536  virtual Maybe<uint32_t> GetWasmModuleTransferId(
2537  Isolate* isolate, Local<WasmModuleObject> module);
2538  /**
2539  * Allocates memory for the buffer of at least the size provided. The actual
2540  * size (which may be greater or equal) is written to |actual_size|. If no
2541  * buffer has been allocated yet, nullptr will be provided.
2542  *
2543  * If the memory cannot be allocated, nullptr should be returned.
2544  * |actual_size| will be ignored. It is assumed that |old_buffer| is still
2545  * valid in this case and has not been modified.
2546  *
2547  * The default implementation uses the stdlib's `realloc()` function.
2548  */
2549  virtual void* ReallocateBufferMemory(void* old_buffer, size_t size,
2550  size_t* actual_size);
2551 
2552  /**
2553  * Frees a buffer allocated with |ReallocateBufferMemory|.
2554  *
2555  * The default implementation uses the stdlib's `free()` function.
2556  */
2557  virtual void FreeBufferMemory(void* buffer);
2558  };
2559 
2560  explicit ValueSerializer(Isolate* isolate);
2561  ValueSerializer(Isolate* isolate, Delegate* delegate);
2563 
2564  /**
2565  * Writes out a header, which includes the format version.
2566  */
2567  void WriteHeader();
2568 
2569  /**
2570  * Serializes a JavaScript value into the buffer.
2571  */
2573  Local<Value> value);
2574 
2575  /**
2576  * Returns the stored data (allocated using the delegate's
2577  * ReallocateBufferMemory) and its size. This serializer should not be used
2578  * once the buffer is released. The contents are undefined if a previous write
2579  * has failed. Ownership of the buffer is transferred to the caller.
2580  */
2581  V8_WARN_UNUSED_RESULT std::pair<uint8_t*, size_t> Release();
2582 
2583  /**
2584  * Marks an ArrayBuffer as havings its contents transferred out of band.
2585  * Pass the corresponding ArrayBuffer in the deserializing context to
2586  * ValueDeserializer::TransferArrayBuffer.
2587  */
2588  void TransferArrayBuffer(uint32_t transfer_id,
2589  Local<ArrayBuffer> array_buffer);
2590 
2591 
2592  /**
2593  * Indicate whether to treat ArrayBufferView objects as host objects,
2594  * i.e. pass them to Delegate::WriteHostObject. This should not be
2595  * called when no Delegate was passed.
2596  *
2597  * The default is not to treat ArrayBufferViews as host objects.
2598  */
2600 
2601  /**
2602  * Write raw data in various common formats to the buffer.
2603  * Note that integer types are written in base-128 varint format, not with a
2604  * binary copy. For use during an override of Delegate::WriteHostObject.
2605  */
2606  void WriteUint32(uint32_t value);
2607  void WriteUint64(uint64_t value);
2608  void WriteDouble(double value);
2609  void WriteRawBytes(const void* source, size_t length);
2610 
2612  void operator=(const ValueSerializer&) = delete;
2613 
2614  private:
2615  struct PrivateData;
2616  PrivateData* private_;
2617 };
2618 
2619 /**
2620  * Deserializes values from data written with ValueSerializer, or a compatible
2621  * implementation.
2622  */
2624  public:
2626  public:
2627  virtual ~Delegate() = default;
2628 
2629  /**
2630  * The embedder overrides this method to read some kind of host object, if
2631  * possible. If not, a suitable exception should be thrown and
2632  * MaybeLocal<Object>() returned.
2633  */
2635 
2636  /**
2637  * Get a WasmModuleObject given a transfer_id previously provided
2638  * by ValueSerializer::GetWasmModuleTransferId
2639  */
2641  Isolate* isolate, uint32_t transfer_id);
2642 
2643  /**
2644  * Get a SharedArrayBuffer given a clone_id previously provided
2645  * by ValueSerializer::GetSharedArrayBufferId
2646  */
2648  Isolate* isolate, uint32_t clone_id);
2649  };
2650 
2651  ValueDeserializer(Isolate* isolate, const uint8_t* data, size_t size);
2652  ValueDeserializer(Isolate* isolate, const uint8_t* data, size_t size,
2653  Delegate* delegate);
2655 
2656  /**
2657  * Reads and validates a header (including the format version).
2658  * May, for example, reject an invalid or unsupported wire format.
2659  */
2661 
2662  /**
2663  * Deserializes a JavaScript value from the buffer.
2664  */
2666 
2667  /**
2668  * Accepts the array buffer corresponding to the one passed previously to
2669  * ValueSerializer::TransferArrayBuffer.
2670  */
2671  void TransferArrayBuffer(uint32_t transfer_id,
2672  Local<ArrayBuffer> array_buffer);
2673 
2674  /**
2675  * Similar to TransferArrayBuffer, but for SharedArrayBuffer.
2676  * The id is not necessarily in the same namespace as unshared ArrayBuffer
2677  * objects.
2678  */
2679  void TransferSharedArrayBuffer(uint32_t id,
2680  Local<SharedArrayBuffer> shared_array_buffer);
2681 
2682  /**
2683  * Must be called before ReadHeader to enable support for reading the legacy
2684  * wire format (i.e., which predates this being shipped).
2685  *
2686  * Don't use this unless you need to read data written by previous versions of
2687  * blink::ScriptValueSerializer.
2688  */
2689  void SetSupportsLegacyWireFormat(bool supports_legacy_wire_format);
2690 
2691  /**
2692  * Reads the underlying wire format version. Likely mostly to be useful to
2693  * legacy code reading old wire format versions. Must be called after
2694  * ReadHeader.
2695  */
2696  uint32_t GetWireFormatVersion() const;
2697 
2698  /**
2699  * Reads raw data in various common formats to the buffer.
2700  * Note that integer types are read in base-128 varint format, not with a
2701  * binary copy. For use during an override of Delegate::ReadHostObject.
2702  */
2703  V8_WARN_UNUSED_RESULT bool ReadUint32(uint32_t* value);
2704  V8_WARN_UNUSED_RESULT bool ReadUint64(uint64_t* value);
2705  V8_WARN_UNUSED_RESULT bool ReadDouble(double* value);
2706  V8_WARN_UNUSED_RESULT bool ReadRawBytes(size_t length, const void** data);
2707 
2709  void operator=(const ValueDeserializer&) = delete;
2710 
2711  private:
2712  struct PrivateData;
2713  PrivateData* private_;
2714 };
2715 
2716 
2717 // --- Value ---
2718 
2719 
2720 /**
2721  * The superclass of all JavaScript values and objects.
2722  */
2723 class V8_EXPORT Value : public Data {
2724  public:
2725  /**
2726  * Returns true if this value is the undefined value. See ECMA-262
2727  * 4.3.10.
2728  *
2729  * This is equivalent to `value === undefined` in JS.
2730  */
2731  V8_INLINE bool IsUndefined() const;
2732 
2733  /**
2734  * Returns true if this value is the null value. See ECMA-262
2735  * 4.3.11.
2736  *
2737  * This is equivalent to `value === null` in JS.
2738  */
2739  V8_INLINE bool IsNull() const;
2740 
2741  /**
2742  * Returns true if this value is either the null or the undefined value.
2743  * See ECMA-262
2744  * 4.3.11. and 4.3.12
2745  *
2746  * This is equivalent to `value == null` in JS.
2747  */
2748  V8_INLINE bool IsNullOrUndefined() const;
2749 
2750  /**
2751  * Returns true if this value is true.
2752  *
2753  * This is not the same as `BooleanValue()`. The latter performs a
2754  * conversion to boolean, i.e. the result of `Boolean(value)` in JS, whereas
2755  * this checks `value === true`.
2756  */
2757  bool IsTrue() const;
2758 
2759  /**
2760  * Returns true if this value is false.
2761  *
2762  * This is not the same as `!BooleanValue()`. The latter performs a
2763  * conversion to boolean, i.e. the result of `!Boolean(value)` in JS, whereas
2764  * this checks `value === false`.
2765  */
2766  bool IsFalse() const;
2767 
2768  /**
2769  * Returns true if this value is a symbol or a string.
2770  *
2771  * This is equivalent to
2772  * `typeof value === 'string' || typeof value === 'symbol'` in JS.
2773  */
2774  bool IsName() const;
2775 
2776  /**
2777  * Returns true if this value is an instance of the String type.
2778  * See ECMA-262 8.4.
2779  *
2780  * This is equivalent to `typeof value === 'string'` in JS.
2781  */
2782  V8_INLINE bool IsString() const;
2783 
2784  /**
2785  * Returns true if this value is a symbol.
2786  *
2787  * This is equivalent to `typeof value === 'symbol'` in JS.
2788  */
2789  bool IsSymbol() const;
2790 
2791  /**
2792  * Returns true if this value is a function.
2793  *
2794  * This is equivalent to `typeof value === 'function'` in JS.
2795  */
2796  bool IsFunction() const;
2797 
2798  /**
2799  * Returns true if this value is an array. Note that it will return false for
2800  * an Proxy for an array.
2801  */
2802  bool IsArray() const;
2803 
2804  /**
2805  * Returns true if this value is an object.
2806  */
2807  bool IsObject() const;
2808 
2809  /**
2810  * Returns true if this value is a bigint.
2811  *
2812  * This is equivalent to `typeof value === 'bigint'` in JS.
2813  */
2814  bool IsBigInt() const;
2815 
2816  /**
2817  * Returns true if this value is boolean.
2818  *
2819  * This is equivalent to `typeof value === 'boolean'` in JS.
2820  */
2821  bool IsBoolean() const;
2822 
2823  /**
2824  * Returns true if this value is a number.
2825  *
2826  * This is equivalent to `typeof value === 'number'` in JS.
2827  */
2828  bool IsNumber() const;
2829 
2830  /**
2831  * Returns true if this value is an `External` object.
2832  */
2833  bool IsExternal() const;
2834 
2835  /**
2836  * Returns true if this value is a 32-bit signed integer.
2837  */
2838  bool IsInt32() const;
2839 
2840  /**
2841  * Returns true if this value is a 32-bit unsigned integer.
2842  */
2843  bool IsUint32() const;
2844 
2845  /**
2846  * Returns true if this value is a Date.
2847  */
2848  bool IsDate() const;
2849 
2850  /**
2851  * Returns true if this value is an Arguments object.
2852  */
2853  bool IsArgumentsObject() const;
2854 
2855  /**
2856  * Returns true if this value is a BigInt object.
2857  */
2858  bool IsBigIntObject() const;
2859 
2860  /**
2861  * Returns true if this value is a Boolean object.
2862  */
2863  bool IsBooleanObject() const;
2864 
2865  /**
2866  * Returns true if this value is a Number object.
2867  */
2868  bool IsNumberObject() const;
2869 
2870  /**
2871  * Returns true if this value is a String object.
2872  */
2873  bool IsStringObject() const;
2874 
2875  /**
2876  * Returns true if this value is a Symbol object.
2877  */
2878  bool IsSymbolObject() const;
2879 
2880  /**
2881  * Returns true if this value is a NativeError.
2882  */
2883  bool IsNativeError() const;
2884 
2885  /**
2886  * Returns true if this value is a RegExp.
2887  */
2888  bool IsRegExp() const;
2889 
2890  /**
2891  * Returns true if this value is an async function.
2892  */
2893  bool IsAsyncFunction() const;
2894 
2895  /**
2896  * Returns true if this value is a Generator function.
2897  */
2898  bool IsGeneratorFunction() const;
2899 
2900  /**
2901  * Returns true if this value is a Generator object (iterator).
2902  */
2903  bool IsGeneratorObject() const;
2904 
2905  /**
2906  * Returns true if this value is a Promise.
2907  */
2908  bool IsPromise() const;
2909 
2910  /**
2911  * Returns true if this value is a Map.
2912  */
2913  bool IsMap() const;
2914 
2915  /**
2916  * Returns true if this value is a Set.
2917  */
2918  bool IsSet() const;
2919 
2920  /**
2921  * Returns true if this value is a Map Iterator.
2922  */
2923  bool IsMapIterator() const;
2924 
2925  /**
2926  * Returns true if this value is a Set Iterator.
2927  */
2928  bool IsSetIterator() const;
2929 
2930  /**
2931  * Returns true if this value is a WeakMap.
2932  */
2933  bool IsWeakMap() const;
2934 
2935  /**
2936  * Returns true if this value is a WeakSet.
2937  */
2938  bool IsWeakSet() const;
2939 
2940  /**
2941  * Returns true if this value is an ArrayBuffer.
2942  */
2943  bool IsArrayBuffer() const;
2944 
2945  /**
2946  * Returns true if this value is an ArrayBufferView.
2947  */
2948  bool IsArrayBufferView() const;
2949 
2950  /**
2951  * Returns true if this value is one of TypedArrays.
2952  */
2953  bool IsTypedArray() const;
2954 
2955  /**
2956  * Returns true if this value is an Uint8Array.
2957  */
2958  bool IsUint8Array() const;
2959 
2960  /**
2961  * Returns true if this value is an Uint8ClampedArray.
2962  */
2963  bool IsUint8ClampedArray() const;
2964 
2965  /**
2966  * Returns true if this value is an Int8Array.
2967  */
2968  bool IsInt8Array() const;
2969 
2970  /**
2971  * Returns true if this value is an Uint16Array.
2972  */
2973  bool IsUint16Array() const;
2974 
2975  /**
2976  * Returns true if this value is an Int16Array.
2977  */
2978  bool IsInt16Array() const;
2979 
2980  /**
2981  * Returns true if this value is an Uint32Array.
2982  */
2983  bool IsUint32Array() const;
2984 
2985  /**
2986  * Returns true if this value is an Int32Array.
2987  */
2988  bool IsInt32Array() const;
2989 
2990  /**
2991  * Returns true if this value is a Float32Array.
2992  */
2993  bool IsFloat32Array() const;
2994 
2995  /**
2996  * Returns true if this value is a Float64Array.
2997  */
2998  bool IsFloat64Array() const;
2999 
3000  /**
3001  * Returns true if this value is a BigInt64Array.
3002  */
3003  bool IsBigInt64Array() const;
3004 
3005  /**
3006  * Returns true if this value is a BigUint64Array.
3007  */
3008  bool IsBigUint64Array() const;
3009 
3010  /**
3011  * Returns true if this value is a DataView.
3012  */
3013  bool IsDataView() const;
3014 
3015  /**
3016  * Returns true if this value is a SharedArrayBuffer.
3017  */
3018  bool IsSharedArrayBuffer() const;
3019 
3020  /**
3021  * Returns true if this value is a JavaScript Proxy.
3022  */
3023  bool IsProxy() const;
3024 
3025  /**
3026  * Returns true if this value is a WasmMemoryObject.
3027  */
3028  bool IsWasmMemoryObject() const;
3029 
3030  /**
3031  * Returns true if this value is a WasmModuleObject.
3032  */
3033  bool IsWasmModuleObject() const;
3034 
3035  /**
3036  * Returns true if the value is a Module Namespace Object.
3037  */
3039 
3040  /**
3041  * Perform the equivalent of `BigInt(value)` in JS.
3042  */
3044  Local<Context> context) const;
3045  /**
3046  * Perform the equivalent of `Number(value)` in JS.
3047  */
3049  Local<Context> context) const;
3050  /**
3051  * Perform the equivalent of `String(value)` in JS.
3052  */
3054  Local<Context> context) const;
3055  /**
3056  * Provide a string representation of this value usable for debugging.
3057  * This operation has no observable side effects and will succeed
3058  * unless e.g. execution is being terminated.
3059  */
3061  Local<Context> context) const;
3062  /**
3063  * Perform the equivalent of `Object(value)` in JS.
3064  */
3066  Local<Context> context) const;
3067  /**
3068  * Perform the equivalent of `Number(value)` in JS and convert the result
3069  * to an integer. Negative values are rounded up, positive values are rounded
3070  * down. NaN is converted to 0. Infinite values yield undefined results.
3071  */
3073  Local<Context> context) const;
3074  /**
3075  * Perform the equivalent of `Number(value)` in JS and convert the result
3076  * to an unsigned 32-bit integer by performing the steps in
3077  * https://tc39.es/ecma262/#sec-touint32.
3078  */
3080  Local<Context> context) const;
3081  /**
3082  * Perform the equivalent of `Number(value)` in JS and convert the result
3083  * to a signed 32-bit integer by performing the steps in
3084  * https://tc39.es/ecma262/#sec-toint32.
3085  */
3087 
3088  /**
3089  * Perform the equivalent of `Boolean(value)` in JS. This can never fail.
3090  */
3091  Local<Boolean> ToBoolean(Isolate* isolate) const;
3092 
3093  /**
3094  * Attempts to convert a string to an array index.
3095  * Returns an empty handle if the conversion fails.
3096  */
3098  Local<Context> context) const;
3099 
3100  /** Returns the equivalent of `ToBoolean()->Value()`. */
3101  bool BooleanValue(Isolate* isolate) const;
3102 
3103  /** Returns the equivalent of `ToNumber()->Value()`. */
3105  /** Returns the equivalent of `ToInteger()->Value()`. */
3107  Local<Context> context) const;
3108  /** Returns the equivalent of `ToUint32()->Value()`. */
3110  Local<Context> context) const;
3111  /** Returns the equivalent of `ToInt32()->Value()`. */
3113 
3114  /** JS == */
3116  Local<Value> that) const;
3117  bool StrictEquals(Local<Value> that) const;
3118  bool SameValue(Local<Value> that) const;
3119 
3120  template <class T> V8_INLINE static Value* Cast(T* value);
3121 
3123 
3124  Maybe<bool> InstanceOf(Local<Context> context, Local<Object> object);
3125 
3126  private:
3127  V8_INLINE bool QuickIsUndefined() const;
3128  V8_INLINE bool QuickIsNull() const;
3129  V8_INLINE bool QuickIsNullOrUndefined() const;
3130  V8_INLINE bool QuickIsString() const;
3131  bool FullIsUndefined() const;
3132  bool FullIsNull() const;
3133  bool FullIsString() const;
3134 
3135  static void CheckCast(Data* that);
3136 };
3137 
3138 
3139 /**
3140  * The superclass of primitive values. See ECMA-262 4.3.2.
3141  */
3142 class V8_EXPORT Primitive : public Value { };
3143 
3144 
3145 /**
3146  * A primitive boolean value (ECMA-262, 4.3.14). Either the true
3147  * or false value.
3148  */
3149 class V8_EXPORT Boolean : public Primitive {
3150  public:
3151  bool Value() const;
3152  V8_INLINE static Boolean* Cast(v8::Data* data);
3153  V8_INLINE static Local<Boolean> New(Isolate* isolate, bool value);
3154 
3155  private:
3156  static void CheckCast(v8::Data* that);
3157 };
3158 
3159 
3160 /**
3161  * A superclass for symbols and strings.
3162  */
3163 class V8_EXPORT Name : public Primitive {
3164  public:
3165  /**
3166  * Returns the identity hash for this object. The current implementation
3167  * uses an inline property on the object to store the identity hash.
3168  *
3169  * The return value will never be 0. Also, it is not guaranteed to be
3170  * unique.
3171  */
3173 
3174  V8_INLINE static Name* Cast(Data* data);
3175 
3176  private:
3177  static void CheckCast(Data* that);
3178 };
3179 
3180 /**
3181  * A flag describing different modes of string creation.
3182  *
3183  * Aside from performance implications there are no differences between the two
3184  * creation modes.
3185  */
3186 enum class NewStringType {
3187  /**
3188  * Create a new string, always allocating new storage memory.
3189  */
3190  kNormal,
3191 
3192  /**
3193  * Acts as a hint that the string should be created in the
3194  * old generation heap space and be deduplicated if an identical string
3195  * already exists.
3196  */
3198 };
3199 
3200 /**
3201  * A JavaScript string value (ECMA-262, 4.3.17).
3202  */
3203 class V8_EXPORT String : public Name {
3204  public:
3205  static constexpr int kMaxLength =
3206  internal::kApiSystemPointerSize == 4 ? (1 << 28) - 16 : (1 << 29) - 24;
3207 
3208  enum Encoding {
3211  ONE_BYTE_ENCODING = 0x8
3212  };
3213  /**
3214  * Returns the number of characters (UTF-16 code units) in this string.
3215  */
3216  int Length() const;
3217 
3218  /**
3219  * Returns the number of bytes in the UTF-8 encoded
3220  * representation of this string.
3221  */
3222  int Utf8Length(Isolate* isolate) const;
3223 
3224  /**
3225  * Returns whether this string is known to contain only one byte data,
3226  * i.e. ISO-8859-1 code points.
3227  * Does not read the string.
3228  * False negatives are possible.
3229  */
3230  bool IsOneByte() const;
3231 
3232  /**
3233  * Returns whether this string contain only one byte data,
3234  * i.e. ISO-8859-1 code points.
3235  * Will read the entire string in some cases.
3236  */
3237  bool ContainsOnlyOneByte() const;
3238 
3239  /**
3240  * Write the contents of the string to an external buffer.
3241  * If no arguments are given, expects the buffer to be large
3242  * enough to hold the entire string and NULL terminator. Copies
3243  * the contents of the string and the NULL terminator into the
3244  * buffer.
3245  *
3246  * WriteUtf8 will not write partial UTF-8 sequences, preferring to stop
3247  * before the end of the buffer.
3248  *
3249  * Copies up to length characters into the output buffer.
3250  * Only null-terminates if there is enough space in the buffer.
3251  *
3252  * \param buffer The buffer into which the string will be copied.
3253  * \param start The starting position within the string at which
3254  * copying begins.
3255  * \param length The number of characters to copy from the string. For
3256  * WriteUtf8 the number of bytes in the buffer.
3257  * \param nchars_ref The number of characters written, can be NULL.
3258  * \param options Various options that might affect performance of this or
3259  * subsequent operations.
3260  * \return The number of characters copied to the buffer excluding the null
3261  * terminator. For WriteUtf8: The number of bytes copied to the buffer
3262  * including the null terminator (if written).
3263  */
3269  // Used by WriteUtf8 to replace orphan surrogate code units with the
3270  // unicode replacement character. Needs to be set to guarantee valid UTF-8
3271  // output.
3273  };
3274 
3275  // 16-bit character codes.
3276  int Write(Isolate* isolate, uint16_t* buffer, int start = 0, int length = -1,
3277  int options = NO_OPTIONS) const;
3278  // One byte characters.
3279  int WriteOneByte(Isolate* isolate, uint8_t* buffer, int start = 0,
3280  int length = -1, int options = NO_OPTIONS) const;
3281  // UTF-8 encoded characters.
3282  int WriteUtf8(Isolate* isolate, char* buffer, int length = -1,
3283  int* nchars_ref = nullptr, int options = NO_OPTIONS) const;
3284 
3285  /**
3286  * A zero length string.
3287  */
3288  V8_INLINE static Local<String> Empty(Isolate* isolate);
3289 
3290  /**
3291  * Returns true if the string is external.
3292  */
3293  bool IsExternal() const;
3294 
3295  /**
3296  * Returns true if the string is both external and two-byte.
3297  */
3298  bool IsExternalTwoByte() const;
3299 
3300  /**
3301  * Returns true if the string is both external and one-byte.
3302  */
3303  bool IsExternalOneByte() const;
3304 
3306  public:
3307  virtual ~ExternalStringResourceBase() = default;
3308 
3309  /**
3310  * If a string is cacheable, the value returned by
3311  * ExternalStringResource::data() may be cached, otherwise it is not
3312  * expected to be stable beyond the current top-level task.
3313  */
3314  virtual bool IsCacheable() const { return true; }
3315 
3316  // Disallow copying and assigning.
3318  void operator=(const ExternalStringResourceBase&) = delete;
3319 
3320  protected:
3322 
3323  /**
3324  * Internally V8 will call this Dispose method when the external string
3325  * resource is no longer needed. The default implementation will use the
3326  * delete operator. This method can be overridden in subclasses to
3327  * control how allocated external string resources are disposed.
3328  */
3329  virtual void Dispose() { delete this; }
3330 
3331  /**
3332  * For a non-cacheable string, the value returned by
3333  * |ExternalStringResource::data()| has to be stable between |Lock()| and
3334  * |Unlock()|, that is the string must behave as is |IsCacheable()| returned
3335  * true.
3336  *
3337  * These two functions must be thread-safe, and can be called from anywhere.
3338  * They also must handle lock depth, in the sense that each can be called
3339  * several times, from different threads, and unlocking should only happen
3340  * when the balance of Lock() and Unlock() calls is 0.
3341  */
3342  virtual void Lock() const {}
3343 
3344  /**
3345  * Unlocks the string.
3346  */
3347  virtual void Unlock() const {}
3348 
3349  private:
3350  friend class internal::ExternalString;
3351  friend class v8::String;
3352  friend class internal::ScopedExternalStringLock;
3353  };
3354 
3355  /**
3356  * An ExternalStringResource is a wrapper around a two-byte string
3357  * buffer that resides outside V8's heap. Implement an
3358  * ExternalStringResource to manage the life cycle of the underlying
3359  * buffer. Note that the string data must be immutable.
3360  */
3362  : public ExternalStringResourceBase {
3363  public:
3364  /**
3365  * Override the destructor to manage the life cycle of the underlying
3366  * buffer.
3367  */
3368  ~ExternalStringResource() override = default;
3369 
3370  /**
3371  * The string data from the underlying buffer. If the resource is cacheable
3372  * then data() must return the same value for all invocations.
3373  */
3374  virtual const uint16_t* data() const = 0;
3375 
3376  /**
3377  * The length of the string. That is, the number of two-byte characters.
3378  */
3379  virtual size_t length() const = 0;
3380 
3381  /**
3382  * Returns the cached data from the underlying buffer. This method can be
3383  * called only for cacheable resources (i.e. IsCacheable() == true) and only
3384  * after UpdateDataCache() was called.
3385  */
3386  const uint16_t* cached_data() const {
3387  CheckCachedDataInvariants();
3388  return cached_data_;
3389  }
3390 
3391  /**
3392  * Update {cached_data_} with the data from the underlying buffer. This can
3393  * be called only for cacheable resources.
3394  */
3396 
3397  protected:
3399 
3400  private:
3401  void CheckCachedDataInvariants() const;
3402 
3403  const uint16_t* cached_data_ = nullptr;
3404  };
3405 
3406  /**
3407  * An ExternalOneByteStringResource is a wrapper around an one-byte
3408  * string buffer that resides outside V8's heap. Implement an
3409  * ExternalOneByteStringResource to manage the life cycle of the
3410  * underlying buffer. Note that the string data must be immutable
3411  * and that the data must be Latin-1 and not UTF-8, which would require
3412  * special treatment internally in the engine and do not allow efficient
3413  * indexing. Use String::New or convert to 16 bit data for non-Latin1.
3414  */
3415 
3417  : public ExternalStringResourceBase {
3418  public:
3419  /**
3420  * Override the destructor to manage the life cycle of the underlying
3421  * buffer.
3422  */
3423  ~ExternalOneByteStringResource() override = default;
3424 
3425  /**
3426  * The string data from the underlying buffer. If the resource is cacheable
3427  * then data() must return the same value for all invocations.
3428  */
3429  virtual const char* data() const = 0;
3430 
3431  /** The number of Latin-1 characters in the string.*/
3432  virtual size_t length() const = 0;
3433 
3434  /**
3435  * Returns the cached data from the underlying buffer. If the resource is
3436  * uncacheable or if UpdateDataCache() was not called before, it has
3437  * undefined behaviour.
3438  */
3439  const char* cached_data() const {
3440  CheckCachedDataInvariants();
3441  return cached_data_;
3442  }
3443 
3444  /**
3445  * Update {cached_data_} with the data from the underlying buffer. This can
3446  * be called only for cacheable resources.
3447  */
3449 
3450  protected:
3452 
3453  private:
3454  void CheckCachedDataInvariants() const;
3455 
3456  const char* cached_data_ = nullptr;
3457  };
3458 
3459  /**
3460  * If the string is an external string, return the ExternalStringResourceBase
3461  * regardless of the encoding, otherwise return NULL. The encoding of the
3462  * string is returned in encoding_out.
3463  */
3465  Encoding* encoding_out) const;
3466 
3467  /**
3468  * Get the ExternalStringResource for an external string. Returns
3469  * NULL if IsExternal() doesn't return true.
3470  */
3472 
3473  /**
3474  * Get the ExternalOneByteStringResource for an external one-byte string.
3475  * Returns NULL if IsExternalOneByte() doesn't return true.
3476  */
3478 
3479  V8_INLINE static String* Cast(v8::Data* data);
3480 
3481  /**
3482  * Allocates a new string from a UTF-8 literal. This is equivalent to calling
3483  * String::NewFromUtf(isolate, "...").ToLocalChecked(), but without the check
3484  * overhead.
3485  *
3486  * When called on a string literal containing '\0', the inferred length is the
3487  * length of the input array minus 1 (for the final '\0') and not the value
3488  * returned by strlen.
3489  **/
3490  template <int N>
3492  Isolate* isolate, const char (&literal)[N],
3494  static_assert(N <= kMaxLength, "String is too long");
3495  return NewFromUtf8Literal(isolate, literal, type, N - 1);
3496  }
3497 
3498  /** Allocates a new string from UTF-8 data. Only returns an empty value when
3499  * length > kMaxLength. **/
3501  Isolate* isolate, const char* data,
3502  NewStringType type = NewStringType::kNormal, int length = -1);
3503 
3504  /** Allocates a new string from Latin-1 data. Only returns an empty value
3505  * when length > kMaxLength. **/
3507  Isolate* isolate, const uint8_t* data,
3508  NewStringType type = NewStringType::kNormal, int length = -1);
3509 
3510  /** Allocates a new string from UTF-16 data. Only returns an empty value when
3511  * length > kMaxLength. **/
3513  Isolate* isolate, const uint16_t* data,
3514  NewStringType type = NewStringType::kNormal, int length = -1);
3515 
3516  /**
3517  * Creates a new string by concatenating the left and the right strings
3518  * passed in as parameters.
3519  */
3520  static Local<String> Concat(Isolate* isolate, Local<String> left,
3521  Local<String> right);
3522 
3523  /**
3524  * Creates a new external string using the data defined in the given
3525  * resource. When the external string is no longer live on V8's heap the
3526  * resource will be disposed by calling its Dispose method. The caller of
3527  * this function should not otherwise delete or modify the resource. Neither
3528  * should the underlying buffer be deallocated or modified except through the
3529  * destructor of the external string resource.
3530  */
3532  Isolate* isolate, ExternalStringResource* resource);
3533 
3534  /**
3535  * Associate an external string resource with this string by transforming it
3536  * in place so that existing references to this string in the JavaScript heap
3537  * will use the external string resource. The external string resource's
3538  * character contents need to be equivalent to this string.
3539  * Returns true if the string has been changed to be an external string.
3540  * The string is not modified if the operation fails. See NewExternal for
3541  * information on the lifetime of the resource.
3542  */
3544 
3545  /**
3546  * Creates a new external string using the one-byte data defined in the given
3547  * resource. When the external string is no longer live on V8's heap the
3548  * resource will be disposed by calling its Dispose method. The caller of
3549  * this function should not otherwise delete or modify the resource. Neither
3550  * should the underlying buffer be deallocated or modified except through the
3551  * destructor of the external string resource.
3552  */
3554  Isolate* isolate, ExternalOneByteStringResource* resource);
3555 
3556  /**
3557  * Associate an external string resource with this string by transforming it
3558  * in place so that existing references to this string in the JavaScript heap
3559  * will use the external string resource. The external string resource's
3560  * character contents need to be equivalent to this string.
3561  * Returns true if the string has been changed to be an external string.
3562  * The string is not modified if the operation fails. See NewExternal for
3563  * information on the lifetime of the resource.
3564  */
3566 
3567  /**
3568  * Returns true if this string can be made external.
3569  */
3570  bool CanMakeExternal() const;
3571 
3572  /**
3573  * Returns true if the strings values are equal. Same as JS ==/===.
3574  */
3575  bool StringEquals(Local<String> str) const;
3576 
3577  /**
3578  * Converts an object to a UTF-8-encoded character array. Useful if
3579  * you want to print the object. If conversion to a string fails
3580  * (e.g. due to an exception in the toString() method of the object)
3581  * then the length() method returns 0 and the * operator returns
3582  * NULL.
3583  */
3585  public:
3586  Utf8Value(Isolate* isolate, Local<v8::Value> obj);
3588  char* operator*() { return str_; }
3589  const char* operator*() const { return str_; }
3590  int length() const { return length_; }
3591 
3592  // Disallow copying and assigning.
3593  Utf8Value(const Utf8Value&) = delete;
3594  void operator=(const Utf8Value&) = delete;
3595 
3596  private:
3597  char* str_;
3598  int length_;
3599  };
3600 
3601  /**
3602  * Converts an object to a two-byte (UTF-16-encoded) string.
3603  * If conversion to a string fails (eg. due to an exception in the toString()
3604  * method of the object) then the length() method returns 0 and the * operator
3605  * returns NULL.
3606  */
3608  public:
3609  Value(Isolate* isolate, Local<v8::Value> obj);
3610  ~Value();
3611  uint16_t* operator*() { return str_; }
3612  const uint16_t* operator*() const { return str_; }
3613  int length() const { return length_; }
3614 
3615  // Disallow copying and assigning.
3616  Value(const Value&) = delete;
3617  void operator=(const Value&) = delete;
3618 
3619  private:
3620  uint16_t* str_;
3621  int length_;
3622  };
3623 
3624  private:
3625  void VerifyExternalStringResourceBase(ExternalStringResourceBase* v,
3626  Encoding encoding) const;
3627  void VerifyExternalStringResource(ExternalStringResource* val) const;
3628  ExternalStringResource* GetExternalStringResourceSlow() const;
3629  ExternalStringResourceBase* GetExternalStringResourceBaseSlow(
3630  String::Encoding* encoding_out) const;
3631 
3632  static Local<v8::String> NewFromUtf8Literal(Isolate* isolate,
3633  const char* literal,
3634  NewStringType type, int length);
3635 
3636  static void CheckCast(v8::Data* that);
3637 };
3638 
3639 // Zero-length string specialization (templated string size includes
3640 // terminator).
3641 template <>
3643  Isolate* isolate, const char (&literal)[1], NewStringType type) {
3644  return String::Empty(isolate);
3645 }
3646 
3647 /**
3648  * A JavaScript symbol (ECMA-262 edition 6)
3649  */
3650 class V8_EXPORT Symbol : public Name {
3651  public:
3652  /**
3653  * Returns the description string of the symbol, or undefined if none.
3654  */
3655  V8_DEPRECATE_SOON("Use Symbol::Description(isolate)")
3657  Local<Value> Description(Isolate* isolate) const;
3658 
3659  /**
3660  * Create a symbol. If description is not empty, it will be used as the
3661  * description.
3662  */
3663  static Local<Symbol> New(Isolate* isolate,
3664  Local<String> description = Local<String>());
3665 
3666  /**
3667  * Access global symbol registry.
3668  * Note that symbols created this way are never collected, so
3669  * they should only be used for statically fixed properties.
3670  * Also, there is only one global name space for the descriptions used as
3671  * keys.
3672  * To minimize the potential for clashes, use qualified names as keys.
3673  */
3674  static Local<Symbol> For(Isolate* isolate, Local<String> description);
3675 
3676  /**
3677  * Retrieve a global symbol. Similar to |For|, but using a separate
3678  * registry that is not accessible by (and cannot clash with) JavaScript code.
3679  */
3680  static Local<Symbol> ForApi(Isolate* isolate, Local<String> description);
3681 
3682  // Well-known symbols
3684  static Local<Symbol> GetHasInstance(Isolate* isolate);
3686  static Local<Symbol> GetIterator(Isolate* isolate);
3687  static Local<Symbol> GetMatch(Isolate* isolate);
3688  static Local<Symbol> GetReplace(Isolate* isolate);
3689  static Local<Symbol> GetSearch(Isolate* isolate);
3690  static Local<Symbol> GetSplit(Isolate* isolate);
3691  static Local<Symbol> GetToPrimitive(Isolate* isolate);
3692  static Local<Symbol> GetToStringTag(Isolate* isolate);
3693  static Local<Symbol> GetUnscopables(Isolate* isolate);
3694 
3695  V8_INLINE static Symbol* Cast(Data* data);
3696 
3697  private:
3698  Symbol();
3699  static void CheckCast(Data* that);
3700 };
3701 
3702 
3703 /**
3704  * A private symbol
3705  *
3706  * This is an experimental feature. Use at your own risk.
3707  */
3708 class V8_EXPORT Private : public Data {
3709  public:
3710  /**
3711  * Returns the print name string of the private symbol, or undefined if none.
3712  */
3713  Local<Value> Name() const;
3714 
3715  /**
3716  * Create a private symbol. If name is not empty, it will be the description.
3717  */
3718  static Local<Private> New(Isolate* isolate,
3719  Local<String> name = Local<String>());
3720 
3721  /**
3722  * Retrieve a global private symbol. If a symbol with this name has not
3723  * been retrieved in the same isolate before, it is created.
3724  * Note that private symbols created this way are never collected, so
3725  * they should only be used for statically fixed properties.
3726  * Also, there is only one global name space for the names used as keys.
3727  * To minimize the potential for clashes, use qualified names as keys,
3728  * e.g., "Class#property".
3729  */
3730  static Local<Private> ForApi(Isolate* isolate, Local<String> name);
3731 
3732  V8_INLINE static Private* Cast(Data* data);
3733 
3734  private:
3735  Private();
3736 
3737  static void CheckCast(Data* that);
3738 };
3739 
3740 
3741 /**
3742  * A JavaScript number value (ECMA-262, 4.3.20)
3743  */
3744 class V8_EXPORT Number : public Primitive {
3745  public:
3746  double Value() const;
3747  static Local<Number> New(Isolate* isolate, double value);
3748  V8_INLINE static Number* Cast(v8::Data* data);
3749 
3750  private:
3751  Number();
3752  static void CheckCast(v8::Data* that);
3753 };
3754 
3755 
3756 /**
3757  * A JavaScript value representing a signed integer.
3758  */
3759 class V8_EXPORT Integer : public Number {
3760  public:
3761  static Local<Integer> New(Isolate* isolate, int32_t value);
3762  static Local<Integer> NewFromUnsigned(Isolate* isolate, uint32_t value);
3763  int64_t Value() const;
3764  V8_INLINE static Integer* Cast(v8::Data* data);
3765 
3766  private:
3767  Integer();
3768  static void CheckCast(v8::Data* that);
3769 };
3770 
3771 
3772 /**
3773  * A JavaScript value representing a 32-bit signed integer.
3774  */
3775 class V8_EXPORT Int32 : public Integer {
3776  public:
3777  int32_t Value() const;
3778  V8_INLINE static Int32* Cast(v8::Data* data);
3779 
3780  private:
3781  Int32();
3782  static void CheckCast(v8::Data* that);
3783 };
3784 
3785 
3786 /**
3787  * A JavaScript value representing a 32-bit unsigned integer.
3788  */
3789 class V8_EXPORT Uint32 : public Integer {
3790  public:
3791  uint32_t Value() const;
3792  V8_INLINE static Uint32* Cast(v8::Data* data);
3793 
3794  private:
3795  Uint32();
3796  static void CheckCast(v8::Data* that);
3797 };
3798 
3799 /**
3800  * A JavaScript BigInt value (https://tc39.github.io/proposal-bigint)
3801  */
3802 class V8_EXPORT BigInt : public Primitive {
3803  public:
3804  static Local<BigInt> New(Isolate* isolate, int64_t value);
3805  static Local<BigInt> NewFromUnsigned(Isolate* isolate, uint64_t value);
3806  /**
3807  * Creates a new BigInt object using a specified sign bit and a
3808  * specified list of digits/words.
3809  * The resulting number is calculated as:
3810  *
3811  * (-1)^sign_bit * (words[0] * (2^64)^0 + words[1] * (2^64)^1 + ...)
3812  */
3813  static MaybeLocal<BigInt> NewFromWords(Local<Context> context, int sign_bit,
3814  int word_count, const uint64_t* words);
3815 
3816  /**
3817  * Returns the value of this BigInt as an unsigned 64-bit integer.
3818  * If `lossless` is provided, it will reflect whether the return value was
3819  * truncated or wrapped around. In particular, it is set to `false` if this
3820  * BigInt is negative.
3821  */
3822  uint64_t Uint64Value(bool* lossless = nullptr) const;
3823 
3824  /**
3825  * Returns the value of this BigInt as a signed 64-bit integer.
3826  * If `lossless` is provided, it will reflect whether this BigInt was
3827  * truncated or not.
3828  */
3829  int64_t Int64Value(bool* lossless = nullptr) const;
3830 
3831  /**
3832  * Returns the number of 64-bit words needed to store the result of
3833  * ToWordsArray().
3834  */
3835  int WordCount() const;
3836 
3837  /**
3838  * Writes the contents of this BigInt to a specified memory location.
3839  * `sign_bit` must be provided and will be set to 1 if this BigInt is
3840  * negative.
3841  * `*word_count` has to be initialized to the length of the `words` array.
3842  * Upon return, it will be set to the actual number of words that would
3843  * be needed to store this BigInt (i.e. the return value of `WordCount()`).
3844  */
3845  void ToWordsArray(int* sign_bit, int* word_count, uint64_t* words) const;
3846 
3847  V8_INLINE static BigInt* Cast(v8::Data* data);
3848 
3849  private:
3850  BigInt();
3851  static void CheckCast(v8::Data* that);
3852 };
3853 
3854 /**
3855  * PropertyAttribute.
3856  */
3858  /** None. **/
3859  None = 0,
3860  /** ReadOnly, i.e., not writable. **/
3861  ReadOnly = 1 << 0,
3862  /** DontEnum, i.e., not enumerable. **/
3863  DontEnum = 1 << 1,
3864  /** DontDelete, i.e., not configurable. **/
3865  DontDelete = 1 << 2
3866 };
3867 
3868 /**
3869  * Accessor[Getter|Setter] are used as callback functions when
3870  * setting|getting a particular property. See Object and ObjectTemplate's
3871  * method SetAccessor.
3872  */
3873 using AccessorGetterCallback =
3874  void (*)(Local<String> property, const PropertyCallbackInfo<Value>& info);
3875 using AccessorNameGetterCallback =
3876  void (*)(Local<Name> property, const PropertyCallbackInfo<Value>& info);
3877 
3878 using AccessorSetterCallback = void (*)(Local<String> property,
3879  Local<Value> value,
3880  const PropertyCallbackInfo<void>& info);
3881 using AccessorNameSetterCallback =
3882  void (*)(Local<Name> property, Local<Value> value,
3883  const PropertyCallbackInfo<void>& info);
3884 
3885 /**
3886  * Access control specifications.
3887  *
3888  * Some accessors should be accessible across contexts. These
3889  * accessors have an explicit access control parameter which specifies
3890  * the kind of cross-context access that should be allowed.
3891  *
3892  * TODO(dcarney): Remove PROHIBITS_OVERWRITING as it is now unused.
3893  */
3895  DEFAULT = 0,
3897  ALL_CAN_WRITE = 1 << 1,
3898  PROHIBITS_OVERWRITING = 1 << 2
3899 };
3900 
3901 /**
3902  * Property filter bits. They can be or'ed to build a composite filter.
3903  */
3910  SKIP_SYMBOLS = 16
3911 };
3912 
3913 /**
3914  * Options for marking whether callbacks may trigger JS-observable side effects.
3915  * Side-effect-free callbacks are allowlisted during debug evaluation with
3916  * throwOnSideEffect. It applies when calling a Function, FunctionTemplate,
3917  * or an Accessor callback. For Interceptors, please see
3918  * PropertyHandlerFlags's kHasNoSideEffect.
3919  * Callbacks that only cause side effects to the receiver are allowlisted if
3920  * invoked on receiver objects that are created within the same debug-evaluate
3921  * call, as these objects are temporary and the side effect does not escape.
3922  */
3923 enum class SideEffectType {
3927 };
3928 
3929 /**
3930  * Keys/Properties filter enums:
3931  *
3932  * KeyCollectionMode limits the range of collected properties. kOwnOnly limits
3933  * the collected properties to the given Object only. kIncludesPrototypes will
3934  * include all keys of the objects's prototype chain as well.
3935  */
3937 
3938 /**
3939  * kIncludesIndices allows for integer indices to be collected, while
3940  * kSkipIndices will exclude integer indices from being collected.
3941  */
3943 
3944 /**
3945  * kConvertToString will convert integer indices to strings.
3946  * kKeepNumbers will return numbers for integer indices.
3947  */
3949 
3950 /**
3951  * Integrity level for objects.
3952  */
3954 
3955 /**
3956  * A JavaScript object (ECMA-262, 4.3.3)
3957  */
3958 class V8_EXPORT Object : public Value {
3959  public:
3960  /**
3961  * Set only return Just(true) or Empty(), so if it should never fail, use
3962  * result.Check().
3963  */
3965  Local<Value> key, Local<Value> value);
3966 
3967  V8_WARN_UNUSED_RESULT Maybe<bool> Set(Local<Context> context, uint32_t index,
3968  Local<Value> value);
3969 
3970  // Implements CreateDataProperty (ECMA-262, 7.3.4).
3971  //
3972  // Defines a configurable, writable, enumerable property with the given value
3973  // on the object unless the property already exists and is not configurable
3974  // or the object is not extensible.
3975  //
3976  // Returns true on success.
3978  Local<Name> key,
3979  Local<Value> value);
3981  uint32_t index,
3982  Local<Value> value);
3983 
3984  // Implements DefineOwnProperty.
3985  //
3986  // In general, CreateDataProperty will be faster, however, does not allow
3987  // for specifying attributes.
3988  //
3989  // Returns true on success.
3991  Local<Context> context, Local<Name> key, Local<Value> value,
3992  PropertyAttribute attributes = None);
3993 
3994  // Implements Object.DefineProperty(O, P, Attributes), see Ecma-262 19.1.2.4.
3995  //
3996  // The defineProperty function is used to add an own property or
3997  // update the attributes of an existing own property of an object.
3998  //
3999  // Both data and accessor descriptors can be used.
4000  //
4001  // In general, CreateDataProperty is faster, however, does not allow
4002  // for specifying attributes or an accessor descriptor.
4003  //
4004  // The PropertyDescriptor can change when redefining a property.
4005  //
4006  // Returns true on success.
4008  Local<Context> context, Local<Name> key, PropertyDescriptor& descriptor);
4009 
4011  Local<Value> key);
4012 
4014  uint32_t index);
4015 
4016  /**
4017  * Gets the property attributes of a property which can be None or
4018  * any combination of ReadOnly, DontEnum and DontDelete. Returns
4019  * None when the property doesn't exist.
4020  */
4022  Local<Context> context, Local<Value> key);
4023 
4024  /**
4025  * Returns Object.getOwnPropertyDescriptor as per ES2016 section 19.1.2.6.
4026  */
4028  Local<Context> context, Local<Name> key);
4029 
4030  /**
4031  * Object::Has() calls the abstract operation HasProperty(O, P) described
4032  * in ECMA-262, 7.3.10. Has() returns
4033  * true, if the object has the property, either own or on the prototype chain.
4034  * Interceptors, i.e., PropertyQueryCallbacks, are called if present.
4035  *
4036  * Has() has the same side effects as JavaScript's `variable in object`.
4037  * For example, calling Has() on a revoked proxy will throw an exception.
4038  *
4039  * \note Has() converts the key to a name, which possibly calls back into
4040  * JavaScript.
4041  *
4042  * See also v8::Object::HasOwnProperty() and
4043  * v8::Object::HasRealNamedProperty().
4044  */
4046  Local<Value> key);
4047 
4049  Local<Value> key);
4050 
4051  V8_WARN_UNUSED_RESULT Maybe<bool> Has(Local<Context> context, uint32_t index);
4052 
4054  uint32_t index);
4055 
4056  /**
4057  * Note: SideEffectType affects the getter only, not the setter.
4058  */
4060  Local<Context> context, Local<Name> name,
4061  AccessorNameGetterCallback getter,
4062  AccessorNameSetterCallback setter = nullptr,
4064  AccessControl settings = DEFAULT, PropertyAttribute attribute = None,
4065  SideEffectType getter_side_effect_type = SideEffectType::kHasSideEffect,
4066  SideEffectType setter_side_effect_type = SideEffectType::kHasSideEffect);
4067 
4069  Local<Function> setter = Local<Function>(),
4070  PropertyAttribute attribute = None,
4071  AccessControl settings = DEFAULT);
4072 
4073  /**
4074  * Sets a native data property like Template::SetNativeDataProperty, but
4075  * this method sets on this object directly.
4076  */
4078  Local<Context> context, Local<Name> name,
4079  AccessorNameGetterCallback getter,
4080  AccessorNameSetterCallback setter = nullptr,
4081  Local<Value> data = Local<Value>(), PropertyAttribute attributes = None,
4082  SideEffectType getter_side_effect_type = SideEffectType::kHasSideEffect,
4083  SideEffectType setter_side_effect_type = SideEffectType::kHasSideEffect);
4084 
4085  /**
4086  * Attempts to create a property with the given name which behaves like a data
4087  * property, except that the provided getter is invoked (and provided with the
4088  * data value) to supply its value the first time it is read. After the
4089  * property is accessed once, it is replaced with an ordinary data property.
4090  *
4091  * Analogous to Template::SetLazyDataProperty.
4092  */
4094  Local<Context> context, Local<Name> name,
4095  AccessorNameGetterCallback getter, Local<Value> data = Local<Value>(),
4096  PropertyAttribute attributes = None,
4097  SideEffectType getter_side_effect_type = SideEffectType::kHasSideEffect,
4098  SideEffectType setter_side_effect_type = SideEffectType::kHasSideEffect);
4099 
4100  /**
4101  * Functionality for private properties.
4102  * This is an experimental feature, use at your own risk.
4103  * Note: Private properties are not inherited. Do not rely on this, since it
4104  * may change.
4105  */
4106  Maybe<bool> HasPrivate(Local<Context> context, Local<Private> key);
4107  Maybe<bool> SetPrivate(Local<Context> context, Local<Private> key,
4108  Local<Value> value);
4111 
4112  /**
4113  * Returns an array containing the names of the enumerable properties
4114  * of this object, including properties from prototype objects. The
4115  * array returned by this method contains the same values as would
4116  * be enumerated by a for-in statement over this object.
4117  */
4119  Local<Context> context);
4121  Local<Context> context, KeyCollectionMode mode,
4122  PropertyFilter property_filter, IndexFilter index_filter,
4124 
4125  /**
4126  * This function has the same functionality as GetPropertyNames but
4127  * the returned array doesn't contain the names of properties from
4128  * prototype objects.
4129  */
4131  Local<Context> context);
4132 
4133  /**
4134  * Returns an array containing the names of the filtered properties
4135  * of this object, including properties from prototype objects. The
4136  * array returned by this method contains the same values as would
4137  * be enumerated by a for-in statement over this object.
4138  */
4140  Local<Context> context, PropertyFilter filter,
4142 
4143  /**
4144  * Get the prototype object. This does not skip objects marked to
4145  * be skipped by __proto__ and it does not consult the security
4146  * handler.
4147  */
4149 
4150  /**
4151  * Set the prototype object. This does not skip objects marked to
4152  * be skipped by __proto__ and it does not consult the security
4153  * handler.
4154  */
4156  Local<Value> prototype);
4157 
4158  /**
4159  * Finds an instance of the given function template in the prototype
4160  * chain.
4161  */
4163 
4164  /**
4165  * Call builtin Object.prototype.toString on this object.
4166  * This is different from Value::ToString() that may call
4167  * user-defined toString function. This one does not.
4168  */
4170  Local<Context> context);
4171 
4172  /**
4173  * Returns the name of the function invoked as a constructor for this object.
4174  */
4176 
4177  /**
4178  * Sets the integrity level of the object.
4179  */
4181 
4182  /** Gets the number of internal fields for this Object. */
4183  int InternalFieldCount() const;
4184 
4185  /** Same as above, but works for PersistentBase. */
4187  const PersistentBase<Object>& object) {
4188  return object.val_->InternalFieldCount();
4189  }
4190 
4191  /** Same as above, but works for BasicTracedReference. */
4193  const BasicTracedReference<Object>& object) {
4194  return object->InternalFieldCount();
4195  }
4196 
4197  /** Gets the value from an internal field. */
4198  V8_INLINE Local<Value> GetInternalField(int index);
4199 
4200  /** Sets the value in an internal field. */
4201  void SetInternalField(int index, Local<Value> value);
4202 
4203  /**
4204  * Gets a 2-byte-aligned native pointer from an internal field. This field
4205  * must have been set by SetAlignedPointerInInternalField, everything else
4206  * leads to undefined behavior.
4207  */
4209 
4210  /** Same as above, but works for PersistentBase. */
4212  const PersistentBase<Object>& object, int index) {
4213  return object.val_->GetAlignedPointerFromInternalField(index);
4214  }
4215 
4216  /** Same as above, but works for TracedGlobal. */
4218  const BasicTracedReference<Object>& object, int index) {
4219  return object->GetAlignedPointerFromInternalField(index);
4220  }
4221 
4222  /**
4223  * Sets a 2-byte-aligned native pointer in an internal field. To retrieve such
4224  * a field, GetAlignedPointerFromInternalField must be used, everything else
4225  * leads to undefined behavior.
4226  */
4227  void SetAlignedPointerInInternalField(int index, void* value);
4228  void SetAlignedPointerInInternalFields(int argc, int indices[],
4229  void* values[]);
4230 
4231  /**
4232  * HasOwnProperty() is like JavaScript's Object.prototype.hasOwnProperty().
4233  *
4234  * See also v8::Object::Has() and v8::Object::HasRealNamedProperty().
4235  */
4237  Local<Name> key);
4239  uint32_t index);
4240  /**
4241  * Use HasRealNamedProperty() if you want to check if an object has an own
4242  * property without causing side effects, i.e., without calling interceptors.
4243  *
4244  * This function is similar to v8::Object::HasOwnProperty(), but it does not
4245  * call interceptors.
4246  *
4247  * \note Consider using non-masking interceptors, i.e., the interceptors are
4248  * not called if the receiver has the real named property. See
4249  * `v8::PropertyHandlerFlags::kNonMasking`.
4250  *
4251  * See also v8::Object::Has().
4252  */
4254  Local<Name> key);
4256  Local<Context> context, uint32_t index);
4258  Local<Context> context, Local<Name> key);
4259 
4260  /**
4261  * If result.IsEmpty() no real property was located in the prototype chain.
4262  * This means interceptors in the prototype chain are not called.
4263  */
4265  Local<Context> context, Local<Name> key);
4266 
4267  /**
4268  * Gets the property attributes of a real property in the prototype chain,
4269  * which can be None or any combination of ReadOnly, DontEnum and DontDelete.
4270  * Interceptors in the prototype chain are not called.
4271  */
4274  Local<Name> key);
4275 
4276  /**
4277  * If result.IsEmpty() no real property was located on the object or
4278  * in the prototype chain.
4279  * This means interceptors in the prototype chain are not called.
4280  */
4282  Local<Context> context, Local<Name> key);
4283 
4284  /**
4285  * Gets the property attributes of a real property which can be
4286  * None or any combination of ReadOnly, DontEnum and DontDelete.
4287  * Interceptors in the prototype chain are not called.
4288  */
4290  Local<Context> context, Local<Name> key);
4291 
4292  /** Tests for a named lookup interceptor.*/
4294 
4295  /** Tests for an index lookup interceptor.*/
4297 
4298  /**
4299  * Returns the identity hash for this object. The current implementation
4300  * uses a hidden property on the object to store the identity hash.
4301  *
4302  * The return value will never be 0. Also, it is not guaranteed to be
4303  * unique.
4304  */
4306 
4307  /**
4308  * Clone this object with a fast but shallow copy. Values will point
4309  * to the same values as the original object.
4310  */
4311  // TODO(dcarney): take an isolate and optionally bail out?
4313 
4314  /**
4315  * Returns the context in which the object was created.
4316  */
4317  // TODO(chromium:1166077): Mark as deprecate once users are updated.
4318  V8_DEPRECATE_SOON("Use MaybeLocal<Context> GetCreationContext()")
4321 
4322  /** Same as above, but works for Persistents */
4323  // TODO(chromium:1166077): Mark as deprecate once users are updated.
4325  "Use MaybeLocal<Context> GetCreationContext(const "
4326  "PersistentBase<Object>& object)")
4327  static Local<Context> CreationContext(const PersistentBase<Object>& object);
4329  const PersistentBase<Object>& object) {
4330  return object.val_->GetCreationContext();
4331  }
4332 
4333  /**
4334  * Checks whether a callback is set by the
4335  * ObjectTemplate::SetCallAsFunctionHandler method.
4336  * When an Object is callable this method returns true.
4337  */
4338  bool IsCallable() const;
4339 
4340  /**
4341  * True if this object is a constructor.
4342  */
4343  bool IsConstructor() const;
4344 
4345  /**
4346  * True if this object can carry information relevant to the embedder in its
4347  * embedder fields, false otherwise. This is generally true for objects
4348  * constructed through function templates but also holds for other types where
4349  * V8 automatically adds internal fields at compile time, such as e.g.
4350  * v8::ArrayBuffer.
4351  */
4352  bool IsApiWrapper() const;
4353 
4354  /**
4355  * True if this object was created from an object template which was marked
4356  * as undetectable. See v8::ObjectTemplate::MarkAsUndetectable for more
4357  * information.
4358  */
4359  bool IsUndetectable() const;
4360 
4361  /**
4362  * Call an Object as a function if a callback is set by the
4363  * ObjectTemplate::SetCallAsFunctionHandler method.
4364  */
4366  Local<Value> recv,
4367  int argc,
4368  Local<Value> argv[]);
4369 
4370  /**
4371  * Call an Object as a constructor if a callback is set by the
4372  * ObjectTemplate::SetCallAsFunctionHandler method.
4373  * Note: This method behaves like the Function::NewInstance method.
4374  */
4376  Local<Context> context, int argc, Local<Value> argv[]);
4377 
4378  /**
4379  * Return the isolate to which the Object belongs to.
4380  */
4382 
4383  /**
4384  * If this object is a Set, Map, WeakSet or WeakMap, this returns a
4385  * representation of the elements of this object as an array.
4386  * If this object is a SetIterator or MapIterator, this returns all
4387  * elements of the underlying collection, starting at the iterator's current
4388  * position.
4389  * For other types, this will return an empty MaybeLocal<Array> (without
4390  * scheduling an exception).
4391  */
4392  MaybeLocal<Array> PreviewEntries(bool* is_key_value);
4393 
4394  static Local<Object> New(Isolate* isolate);
4395 
4396  /**
4397  * Creates a JavaScript object with the given properties, and
4398  * a the given prototype_or_null (which can be any JavaScript
4399  * value, and if it's null, the newly created object won't have
4400  * a prototype at all). This is similar to Object.create().
4401  * All properties will be created as enumerable, configurable
4402  * and writable properties.
4403  */
4404  static Local<Object> New(Isolate* isolate, Local<Value> prototype_or_null,
4405  Local<Name>* names, Local<Value>* values,
4406  size_t length);
4407 
4408  V8_INLINE static Object* Cast(Value* obj);
4409 
4410  /**
4411  * Support for TC39 "dynamic code brand checks" proposal.
4412  *
4413  * This API allows to query whether an object was constructed from a
4414  * "code like" ObjectTemplate.
4415  *
4416  * See also: v8::ObjectTemplate::SetCodeLike
4417  */
4418  bool IsCodeLike(Isolate* isolate) const;
4419 
4420  private:
4421  Object();
4422  static void CheckCast(Value* obj);
4423  Local<Value> SlowGetInternalField(int index);
4424  void* SlowGetAlignedPointerFromInternalField(int index);
4425 };
4426 
4427 
4428 /**
4429  * An instance of the built-in array constructor (ECMA-262, 15.4.2).
4430  */
4431 class V8_EXPORT Array : public Object {
4432  public:
4433  uint32_t Length() const;
4434 
4435  /**
4436  * Creates a JavaScript array with the given length. If the length
4437  * is negative the returned array will have length 0.
4438  */
4439  static Local<Array> New(Isolate* isolate, int length = 0);
4440 
4441  /**
4442  * Creates a JavaScript array out of a Local<Value> array in C++
4443  * with a known length.
4444  */
4445  static Local<Array> New(Isolate* isolate, Local<Value>* elements,
4446  size_t length);
4447  V8_INLINE static Array* Cast(Value* obj);
4448 
4449  private:
4450  Array();
4451  static void CheckCast(Value* obj);
4452 };
4453 
4454 
4455 /**
4456  * An instance of the built-in Map constructor (ECMA-262, 6th Edition, 23.1.1).
4457  */
4458 class V8_EXPORT Map : public Object {
4459  public:
4460  size_t Size() const;
4461  void Clear();
4463  Local<Value> key);
4465  Local<Value> key,
4466  Local<Value> value);
4468  Local<Value> key);
4470  Local<Value> key);
4471 
4472  /**
4473  * Returns an array of length Size() * 2, where index N is the Nth key and
4474  * index N + 1 is the Nth value.
4475  */
4476  Local<Array> AsArray() const;
4477 
4478  /**
4479  * Creates a new empty Map.
4480  */
4481  static Local<Map> New(Isolate* isolate);
4482 
4483  V8_INLINE static Map* Cast(Value* obj);
4484 
4485  private:
4486  Map();
4487  static void CheckCast(Value* obj);
4488 };
4489 
4490 
4491 /**
4492  * An instance of the built-in Set constructor (ECMA-262, 6th Edition, 23.2.1).
4493  */
4494 class V8_EXPORT Set : public Object {
4495  public:
4496  size_t Size() const;
4497  void Clear();
4499  Local<Value> key);
4501  Local<Value> key);
4503  Local<Value> key);
4504 
4505  /**
4506  * Returns an array of the keys in this Set.
4507  */
4508  Local<Array> AsArray() const;
4509 
4510  /**
4511  * Creates a new empty Set.
4512  */
4513  static Local<Set> New(Isolate* isolate);
4514 
4515  V8_INLINE static Set* Cast(Value* obj);
4516 
4517  private:
4518  Set();
4519  static void CheckCast(Value* obj);
4520 };
4521 
4522 
4523 template<typename T>
4525  public:
4526  template <class S> V8_INLINE ReturnValue(const ReturnValue<S>& that)
4527  : value_(that.value_) {
4528  static_assert(std::is_base_of<T, S>::value, "type check");
4529  }
4530  // Local setters
4531  template <typename S>
4532  V8_INLINE void Set(const Global<S>& handle);
4533  template <typename S>
4534  V8_INLINE void Set(const BasicTracedReference<S>& handle);
4535  template <typename S>
4536  V8_INLINE void Set(const Local<S> handle);
4537  // Fast primitive setters
4538  V8_INLINE void Set(bool value);
4539  V8_INLINE void Set(double i);
4540  V8_INLINE void Set(int32_t i);
4541  V8_INLINE void Set(uint32_t i);
4542  // Fast JS primitive setters
4543  V8_INLINE void SetNull();
4544  V8_INLINE void SetUndefined();
4545  V8_INLINE void SetEmptyString();
4546  // Convenience getter for Isolate
4547  V8_INLINE Isolate* GetIsolate() const;
4548 
4549  // Pointer setter: Uncompilable to prevent inadvertent misuse.
4550  template <typename S>
4551  V8_INLINE void Set(S* whatever);
4552 
4553  // Getter. Creates a new Local<> so it comes with a certain performance
4554  // hit. If the ReturnValue was not yet set, this will return the undefined
4555  // value.
4556  V8_INLINE Local<Value> Get() const;
4557 
4558  private:
4559  template<class F> friend class ReturnValue;
4560  template<class F> friend class FunctionCallbackInfo;
4561  template<class F> friend class PropertyCallbackInfo;
4562  template <class F, class G, class H>
4564  V8_INLINE void SetInternal(internal::Address value) { *value_ = value; }
4565  V8_INLINE internal::Address GetDefaultValue();
4566  V8_INLINE explicit ReturnValue(internal::Address* slot);
4567  internal::Address* value_;
4568 };
4569 
4570 
4571 /**
4572  * The argument information given to function call callbacks. This
4573  * class provides access to information about the context of the call,
4574  * including the receiver, the number and values of arguments, and
4575  * the holder of the function.
4576  */
4577 template<typename T>
4579  public:
4580  /** The number of available arguments. */
4581  V8_INLINE int Length() const;
4582  /**
4583  * Accessor for the available arguments. Returns `undefined` if the index
4584  * is out of bounds.
4585  */
4586  V8_INLINE Local<Value> operator[](int i) const;
4587  /** Returns the receiver. This corresponds to the "this" value. */
4588  V8_INLINE Local<Object> This() const;
4589  /**
4590  * If the callback was created without a Signature, this is the same
4591  * value as This(). If there is a signature, and the signature didn't match
4592  * This() but one of its hidden prototypes, this will be the respective
4593  * hidden prototype.
4594  *
4595  * Note that this is not the prototype of This() on which the accessor
4596  * referencing this callback was found (which in V8 internally is often
4597  * referred to as holder [sic]).
4598  */
4599  V8_INLINE Local<Object> Holder() const;
4600  /** For construct calls, this returns the "new.target" value. */
4601  V8_INLINE Local<Value> NewTarget() const;
4602  /** Indicates whether this is a regular call or a construct call. */
4603  V8_INLINE bool IsConstructCall() const;
4604  /** The data argument specified when creating the callback. */
4605  V8_INLINE Local<Value> Data() const;
4606  /** The current Isolate. */
4607  V8_INLINE Isolate* GetIsolate() const;
4608  /** The ReturnValue for the call. */
4610  // This shouldn't be public, but the arm compiler needs it.
4611  static const int kArgsLength = 6;
4612 
4613  protected:
4614  friend class internal::FunctionCallbackArguments;
4616  friend class debug::ConsoleCallArguments;
4617  static const int kHolderIndex = 0;
4618  static const int kIsolateIndex = 1;
4619  static const int kReturnValueDefaultValueIndex = 2;
4620  static const int kReturnValueIndex = 3;
4621  static const int kDataIndex = 4;
4622  static const int kNewTargetIndex = 5;
4623 
4625  internal::Address* values, int length);
4628  int length_;
4629 };
4630 
4631 
4632 /**
4633  * The information passed to a property callback about the context
4634  * of the property access.
4635  */
4636 template<typename T>
4638  public:
4639  /**
4640  * \return The isolate of the property access.
4641  */
4643 
4644  /**
4645  * \return The data set in the configuration, i.e., in
4646  * `NamedPropertyHandlerConfiguration` or
4647  * `IndexedPropertyHandlerConfiguration.`
4648  */
4650 
4651  /**
4652  * \return The receiver. In many cases, this is the object on which the
4653  * property access was intercepted. When using
4654  * `Reflect.get`, `Function.prototype.call`, or similar functions, it is the
4655  * object passed in as receiver or thisArg.
4656  *
4657  * \code
4658  * void GetterCallback(Local<Name> name,
4659  * const v8::PropertyCallbackInfo<v8::Value>& info) {
4660  * auto context = info.GetIsolate()->GetCurrentContext();
4661  *
4662  * v8::Local<v8::Value> a_this =
4663  * info.This()
4664  * ->GetRealNamedProperty(context, v8_str("a"))
4665  * .ToLocalChecked();
4666  * v8::Local<v8::Value> a_holder =
4667  * info.Holder()
4668  * ->GetRealNamedProperty(context, v8_str("a"))
4669  * .ToLocalChecked();
4670  *
4671  * CHECK(v8_str("r")->Equals(context, a_this).FromJust());
4672  * CHECK(v8_str("obj")->Equals(context, a_holder).FromJust());
4673  *
4674  * info.GetReturnValue().Set(name);
4675  * }
4676  *
4677  * v8::Local<v8::FunctionTemplate> templ =
4678  * v8::FunctionTemplate::New(isolate);
4679  * templ->InstanceTemplate()->SetHandler(
4680  * v8::NamedPropertyHandlerConfiguration(GetterCallback));
4681  * LocalContext env;
4682  * env->Global()
4683  * ->Set(env.local(), v8_str("obj"), templ->GetFunction(env.local())
4684  * .ToLocalChecked()
4685  * ->NewInstance(env.local())
4686  * .ToLocalChecked())
4687  * .FromJust();
4688  *
4689  * CompileRun("obj.a = 'obj'; var r = {a: 'r'}; Reflect.get(obj, 'x', r)");
4690  * \endcode
4691  */
4693 
4694  /**
4695  * \return The object in the prototype chain of the receiver that has the
4696  * interceptor. Suppose you have `x` and its prototype is `y`, and `y`
4697  * has an interceptor. Then `info.This()` is `x` and `info.Holder()` is `y`.
4698  * The Holder() could be a hidden object (the global object, rather
4699  * than the global proxy).
4700  *
4701  * \note For security reasons, do not pass the object back into the runtime.
4702  */
4704 
4705  /**
4706  * \return The return value of the callback.
4707  * Can be changed by calling Set().
4708  * \code
4709  * info.GetReturnValue().Set(...)
4710  * \endcode
4711  *
4712  */
4714 
4715  /**
4716  * \return True if the intercepted function should throw if an error occurs.
4717  * Usually, `true` corresponds to `'use strict'`.
4718  *
4719  * \note Always `false` when intercepting `Reflect.set()`
4720  * independent of the language mode.
4721  */
4723 
4724  // This shouldn't be public, but the arm compiler needs it.
4725  static const int kArgsLength = 7;
4726 
4727  protected:
4728  friend class MacroAssembler;
4729  friend class internal::PropertyCallbackArguments;
4731  static const int kShouldThrowOnErrorIndex = 0;
4732  static const int kHolderIndex = 1;
4733  static const int kIsolateIndex = 2;
4734  static const int kReturnValueDefaultValueIndex = 3;
4735  static const int kReturnValueIndex = 4;
4736  static const int kDataIndex = 5;
4737  static const int kThisIndex = 6;
4738