v8  6.1.534(node8.9.3)
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 http://code.google.com/apis/v8/
13  */
14 
15 #ifndef INCLUDE_V8_H_
16 #define INCLUDE_V8_H_
17 
18 #include <stddef.h>
19 #include <stdint.h>
20 #include <stdio.h>
21 #include <memory>
22 #include <utility>
23 #include <vector>
24 
25 #include "v8-version.h" // NOLINT(build/include)
26 #include "v8config.h" // NOLINT(build/include)
27 
28 // We reserve the V8_* prefix for macros defined in V8 public API and
29 // assume there are no name conflicts with the embedder's code.
30 
31 #ifdef V8_OS_WIN
32 
33 // Setup for Windows DLL export/import. When building the V8 DLL the
34 // BUILDING_V8_SHARED needs to be defined. When building a program which uses
35 // the V8 DLL USING_V8_SHARED needs to be defined. When either building the V8
36 // static library or building a program which uses the V8 static library neither
37 // BUILDING_V8_SHARED nor USING_V8_SHARED should be defined.
38 #ifdef BUILDING_V8_SHARED
39 # define V8_EXPORT __declspec(dllexport)
40 #elif USING_V8_SHARED
41 # define V8_EXPORT __declspec(dllimport)
42 #else
43 # define V8_EXPORT
44 #endif // BUILDING_V8_SHARED
45 
46 #else // V8_OS_WIN
47 
48 // Setup for Linux shared library export.
49 #if V8_HAS_ATTRIBUTE_VISIBILITY
50 # ifdef BUILDING_V8_SHARED
51 # define V8_EXPORT __attribute__ ((visibility("default")))
52 # else
53 # define V8_EXPORT
54 # endif
55 #else
56 # define V8_EXPORT
57 #endif
58 
59 #endif // V8_OS_WIN
60 
61 /**
62  * The v8 JavaScript engine.
63  */
64 namespace v8 {
65 
66 class AccessorSignature;
67 class Array;
68 class ArrayBuffer;
69 class Boolean;
70 class BooleanObject;
71 class Context;
72 class CpuProfiler;
73 class Data;
74 class Date;
75 class External;
76 class Function;
77 class FunctionTemplate;
78 class HeapProfiler;
79 class ImplementationUtilities;
80 class Int32;
81 class Integer;
82 class Isolate;
83 template <class T>
84 class Maybe;
85 class Name;
86 class Number;
87 class NumberObject;
88 class Object;
89 class ObjectOperationDescriptor;
90 class ObjectTemplate;
91 class Platform;
92 class Primitive;
93 class Promise;
94 class PropertyDescriptor;
95 class Proxy;
96 class RawOperationDescriptor;
97 class Script;
98 class SharedArrayBuffer;
99 class Signature;
100 class StartupData;
101 class StackFrame;
102 class StackTrace;
103 class String;
104 class StringObject;
105 class Symbol;
106 class SymbolObject;
107 class Private;
108 class Uint32;
109 class Utils;
110 class Value;
111 class WasmCompiledModule;
112 template <class T> class Local;
113 template <class T>
114 class MaybeLocal;
115 template <class T> class Eternal;
116 template<class T> class NonCopyablePersistentTraits;
117 template<class T> class PersistentBase;
118 template <class T, class M = NonCopyablePersistentTraits<T> >
119 class Persistent;
120 template <class T>
121 class Global;
122 template<class K, class V, class T> class PersistentValueMap;
123 template <class K, class V, class T>
125 template <class K, class V, class T>
126 class GlobalValueMap;
127 template<class V, class T> class PersistentValueVector;
128 template<class T, class P> class WeakCallbackObject;
129 class FunctionTemplate;
130 class ObjectTemplate;
131 template<typename T> class FunctionCallbackInfo;
132 template<typename T> class PropertyCallbackInfo;
133 class StackTrace;
134 class StackFrame;
135 class Isolate;
136 class CallHandlerHelper;
138 template<typename T> class ReturnValue;
139 
140 namespace internal {
141 class Arguments;
142 class Heap;
143 class HeapObject;
144 class Isolate;
145 class Object;
146 struct StreamedSource;
147 template<typename T> class CustomArguments;
148 class PropertyCallbackArguments;
149 class FunctionCallbackArguments;
150 class GlobalHandles;
151 } // namespace internal
152 
153 namespace debug {
154 class ConsoleCallArguments;
155 } // namespace debug
156 
157 // --- Handles ---
158 
159 #define TYPE_CHECK(T, S)
160  while (false) {
161  *(static_cast<T* volatile*>(0)) = static_cast<S*>(0);
162  }
163 
164 /**
165  * An object reference managed by the v8 garbage collector.
166  *
167  * All objects returned from v8 have to be tracked by the garbage
168  * collector so that it knows that the objects are still alive. Also,
169  * because the garbage collector may move objects, it is unsafe to
170  * point directly to an object. Instead, all objects are stored in
171  * handles which are known by the garbage collector and updated
172  * whenever an object moves. Handles should always be passed by value
173  * (except in cases like out-parameters) and they should never be
174  * allocated on the heap.
175  *
176  * There are two types of handles: local and persistent handles.
177  *
178  * Local handles are light-weight and transient and typically used in
179  * local operations. They are managed by HandleScopes. That means that a
180  * HandleScope must exist on the stack when they are created and that they are
181  * only valid inside of the HandleScope active during their creation.
182  * For passing a local handle to an outer HandleScope, an EscapableHandleScope
183  * and its Escape() method must be used.
184  *
185  * Persistent handles can be used when storing objects across several
186  * independent operations and have to be explicitly deallocated when they're no
187  * longer used.
188  *
189  * It is safe to extract the object stored in the handle by
190  * dereferencing the handle (for instance, to extract the Object* from
191  * a Local<Object>); the value will still be governed by a handle
192  * behind the scenes and the same rules apply to these values as to
193  * their handles.
194  */
195 template <class T>
196 class Local {
197  public:
198  V8_INLINE Local() : val_(0) {}
199  template <class S>
200  V8_INLINE Local(Local<S> that)
201  : val_(reinterpret_cast<T*>(*that)) {
202  /**
203  * This check fails when trying to convert between incompatible
204  * handles. For example, converting from a Local<String> to a
205  * Local<Number>.
206  */
207  TYPE_CHECK(T, S);
208  }
209 
210  /**
211  * Returns true if the handle is empty.
212  */
213  V8_INLINE bool IsEmpty() const { return val_ == 0; }
214 
215  /**
216  * Sets the handle to be empty. IsEmpty() will then return true.
217  */
218  V8_INLINE void Clear() { val_ = 0; }
219 
220  V8_INLINE T* operator->() const { return val_; }
221 
222  V8_INLINE T* operator*() const { return val_; }
223 
224  /**
225  * Checks whether two handles are the same.
226  * Returns true if both are empty, or if the objects
227  * to which they refer are identical.
228  * The handles' references are not checked.
229  */
230  template <class S>
231  V8_INLINE bool operator==(const Local<S>& that) const {
232  internal::Object** a = reinterpret_cast<internal::Object**>(this->val_);
233  internal::Object** b = reinterpret_cast<internal::Object**>(that.val_);
234  if (a == 0) return b == 0;
235  if (b == 0) return false;
236  return *a == *b;
237  }
238 
239  template <class S> V8_INLINE bool operator==(
240  const PersistentBase<S>& that) const {
241  internal::Object** a = reinterpret_cast<internal::Object**>(this->val_);
242  internal::Object** b = reinterpret_cast<internal::Object**>(that.val_);
243  if (a == 0) return b == 0;
244  if (b == 0) return false;
245  return *a == *b;
246  }
247 
248  /**
249  * Checks whether two handles are different.
250  * Returns true if only one of the handles is empty, or if
251  * the objects to which they refer are different.
252  * The handles' references are not checked.
253  */
254  template <class S>
255  V8_INLINE bool operator!=(const Local<S>& that) const {
256  return !operator==(that);
257  }
258 
259  template <class S> V8_INLINE bool operator!=(
260  const Persistent<S>& that) const {
261  return !operator==(that);
262  }
263 
264  /**
265  * Cast a handle to a subclass, e.g. Local<Value> to Local<Object>.
266  * This is only valid if the handle actually refers to a value of the
267  * target type.
268  */
269  template <class S> V8_INLINE static Local<T> Cast(Local<S> that) {
270 #ifdef V8_ENABLE_CHECKS
271  // If we're going to perform the type check then we have to check
272  // that the handle isn't empty before doing the checked cast.
273  if (that.IsEmpty()) return Local<T>();
274 #endif
275  return Local<T>(T::Cast(*that));
276  }
277 
278  /**
279  * Calling this is equivalent to Local<S>::Cast().
280  * In particular, this is only valid if the handle actually refers to a value
281  * of the target type.
282  */
283  template <class S>
284  V8_INLINE Local<S> As() const {
285  return Local<S>::Cast(*this);
286  }
287 
288  /**
289  * Create a local handle for the content of another handle.
290  * The referee is kept alive by the local handle even when
291  * the original handle is destroyed/disposed.
292  */
293  V8_INLINE static Local<T> New(Isolate* isolate, Local<T> that);
294  V8_INLINE static Local<T> New(Isolate* isolate,
295  const PersistentBase<T>& that);
296 
297  private:
298  friend class Utils;
299  template<class F> friend class Eternal;
300  template<class F> friend class PersistentBase;
301  template<class F, class M> friend class Persistent;
302  template<class F> friend class Local;
303  template <class F>
304  friend class MaybeLocal;
305  template<class F> friend class FunctionCallbackInfo;
306  template<class F> friend class PropertyCallbackInfo;
307  friend class String;
308  friend class Object;
309  friend class Context;
310  friend class Private;
311  template<class F> friend class internal::CustomArguments;
313  friend Local<Primitive> Null(Isolate* isolate);
314  friend Local<Boolean> True(Isolate* isolate);
315  friend Local<Boolean> False(Isolate* isolate);
316  friend class HandleScope;
317  friend class EscapableHandleScope;
318  template <class F1, class F2, class F3>
320  template<class F1, class F2> friend class PersistentValueVector;
321  template <class F>
322  friend class ReturnValue;
323 
324  explicit V8_INLINE Local(T* that) : val_(that) {}
325  V8_INLINE static Local<T> New(Isolate* isolate, T* that);
326  T* val_;
327 };
328 
329 
330 #if !defined(V8_IMMINENT_DEPRECATION_WARNINGS)
331 // Handle is an alias for Local for historical reasons.
332 template <class T>
333 using Handle = Local<T>;
334 #endif
335 
336 
337 /**
338  * A MaybeLocal<> is a wrapper around Local<> that enforces a check whether
339  * the Local<> is empty before it can be used.
340  *
341  * If an API method returns a MaybeLocal<>, the API method can potentially fail
342  * either because an exception is thrown, or because an exception is pending,
343  * e.g. because a previous API call threw an exception that hasn't been caught
344  * yet, or because a TerminateExecution exception was thrown. In that case, an
345  * empty MaybeLocal is returned.
346  */
347 template <class T>
348 class MaybeLocal {
349  public:
351  template <class S>
352  V8_INLINE MaybeLocal(Local<S> that)
353  : val_(reinterpret_cast<T*>(*that)) {
354  TYPE_CHECK(T, S);
355  }
356 
357  V8_INLINE bool IsEmpty() const { return val_ == nullptr; }
358 
359  /**
360  * Converts this MaybeLocal<> to a Local<>. If this MaybeLocal<> is empty,
361  * |false| is returned and |out| is left untouched.
362  */
363  template <class S>
364  V8_WARN_UNUSED_RESULT V8_INLINE bool ToLocal(Local<S>* out) const {
365  out->val_ = IsEmpty() ? nullptr : this->val_;
366  return !IsEmpty();
367  }
368 
369  /**
370  * Converts this MaybeLocal<> to a Local<>. If this MaybeLocal<> is empty,
371  * V8 will crash the process.
372  */
373  V8_INLINE Local<T> ToLocalChecked();
374 
375  /**
376  * Converts this MaybeLocal<> to a Local<>, using a default value if this
377  * MaybeLocal<> is empty.
378  */
379  template <class S>
380  V8_INLINE Local<S> FromMaybe(Local<S> default_value) const {
381  return IsEmpty() ? default_value : Local<S>(val_);
382  }
383 
384  private:
385  T* val_;
386 };
387 
388 /**
389  * Eternal handles are set-once handles that live for the lifetime of the
390  * isolate.
391  */
392 template <class T> class Eternal {
393  public:
395  template <class S>
396  V8_INLINE Eternal(Isolate* isolate, Local<S> handle) : val_(nullptr) {
397  Set(isolate, handle);
398  }
399  // Can only be safely called if already set.
400  V8_INLINE Local<T> Get(Isolate* isolate) const;
401  V8_INLINE bool IsEmpty() const { return val_ == nullptr; }
402  template<class S> V8_INLINE void Set(Isolate* isolate, Local<S> handle);
403 
404  private:
405  T* val_;
406 };
407 
408 
409 static const int kInternalFieldsInWeakCallback = 2;
410 static const int kEmbedderFieldsInWeakCallback = 2;
411 
412 template <typename T>
414  public:
415  typedef void (*Callback)(const WeakCallbackInfo<T>& data);
416 
417  WeakCallbackInfo(Isolate* isolate, T* parameter,
418  void* embedder_fields[kEmbedderFieldsInWeakCallback],
419  Callback* callback)
420  : isolate_(isolate), parameter_(parameter), callback_(callback) {
421  for (int i = 0; i < kEmbedderFieldsInWeakCallback; ++i) {
422  embedder_fields_[i] = embedder_fields[i];
423  }
424  }
425 
426  V8_INLINE Isolate* GetIsolate() const { return isolate_; }
427  V8_INLINE T* GetParameter() const { return parameter_; }
428  V8_INLINE void* GetInternalField(int index) const;
429 
430  V8_INLINE V8_DEPRECATED("use indexed version",
431  void* GetInternalField1() const) {
432  return embedder_fields_[0];
433  }
434  V8_INLINE V8_DEPRECATED("use indexed version",
435  void* GetInternalField2() const) {
436  return embedder_fields_[1];
437  }
438 
439  V8_DEPRECATED("Not realiable once SetSecondPassCallback() was used.",
440  bool IsFirstPass() const) {
441  return callback_ != nullptr;
442  }
443 
444  // When first called, the embedder MUST Reset() the Global which triggered the
445  // callback. The Global itself is unusable for anything else. No v8 other api
446  // calls may be called in the first callback. Should additional work be
447  // required, the embedder must set a second pass callback, which will be
448  // called after all the initial callbacks are processed.
449  // Calling SetSecondPassCallback on the second pass will immediately crash.
450  void SetSecondPassCallback(Callback callback) const { *callback_ = callback; }
451 
452  private:
453  Isolate* isolate_;
454  T* parameter_;
455  Callback* callback_;
456  void* embedder_fields_[kEmbedderFieldsInWeakCallback];
457 };
458 
459 
460 // kParameter will pass a void* parameter back to the callback, kInternalFields
461 // will pass the first two internal fields back to the callback, kFinalizer
462 // will pass a void* parameter back, but is invoked before the object is
463 // actually collected, so it can be resurrected. In the last case, it is not
464 // possible to request a second pass callback.
466 
467 /**
468  * An object reference that is independent of any handle scope. Where
469  * a Local handle only lives as long as the HandleScope in which it was
470  * allocated, a PersistentBase handle remains valid until it is explicitly
471  * disposed using Reset().
472  *
473  * A persistent handle contains a reference to a storage cell within
474  * the V8 engine which holds an object value and which is updated by
475  * the garbage collector whenever the object is moved. A new storage
476  * cell can be created using the constructor or PersistentBase::Reset and
477  * existing handles can be disposed using PersistentBase::Reset.
478  *
479  */
480 template <class T> class PersistentBase {
481  public:
482  /**
483  * If non-empty, destroy the underlying storage cell
484  * IsEmpty() will return true after this call.
485  */
486  V8_INLINE void Reset();
487  /**
488  * If non-empty, destroy the underlying storage cell
489  * and create a new one with the contents of other if other is non empty
490  */
491  template <class S>
492  V8_INLINE void Reset(Isolate* isolate, const Local<S>& other);
493 
494  /**
495  * If non-empty, destroy the underlying storage cell
496  * and create a new one with the contents of other if other is non empty
497  */
498  template <class S>
499  V8_INLINE void Reset(Isolate* isolate, const PersistentBase<S>& other);
500 
501  V8_INLINE bool IsEmpty() const { return val_ == NULL; }
502  V8_INLINE void Empty() { val_ = 0; }
503 
504  V8_INLINE Local<T> Get(Isolate* isolate) const {
505  return Local<T>::New(isolate, *this);
506  }
507 
508  template <class S>
509  V8_INLINE bool operator==(const PersistentBase<S>& that) const {
510  internal::Object** a = reinterpret_cast<internal::Object**>(this->val_);
511  internal::Object** b = reinterpret_cast<internal::Object**>(that.val_);
512  if (a == NULL) return b == NULL;
513  if (b == NULL) return false;
514  return *a == *b;
515  }
516 
517  template <class S>
518  V8_INLINE bool operator==(const Local<S>& that) const {
519  internal::Object** a = reinterpret_cast<internal::Object**>(this->val_);
520  internal::Object** b = reinterpret_cast<internal::Object**>(that.val_);
521  if (a == NULL) return b == NULL;
522  if (b == NULL) return false;
523  return *a == *b;
524  }
525 
526  template <class S>
527  V8_INLINE bool operator!=(const PersistentBase<S>& that) const {
528  return !operator==(that);
529  }
530 
531  template <class S>
532  V8_INLINE bool operator!=(const Local<S>& that) const {
533  return !operator==(that);
534  }
535 
536  /**
537  * Install a finalization callback on this object.
538  * NOTE: There is no guarantee as to *when* or even *if* the callback is
539  * invoked. The invocation is performed solely on a best effort basis.
540  * As always, GC-based finalization should *not* be relied upon for any
541  * critical form of resource management!
542  */
543  template <typename P>
544  V8_INLINE void SetWeak(P* parameter,
545  typename WeakCallbackInfo<P>::Callback callback,
546  WeakCallbackType type);
547 
548  /**
549  * Turns this handle into a weak phantom handle without finalization callback.
550  * The handle will be reset automatically when the garbage collector detects
551  * that the object is no longer reachable.
552  * A related function Isolate::NumberOfPhantomHandleResetsSinceLastCall
553  * returns how many phantom handles were reset by the garbage collector.
554  */
555  V8_INLINE void SetWeak();
556 
557  template<typename P>
558  V8_INLINE P* ClearWeak();
559 
560  // TODO(dcarney): remove this.
561  V8_INLINE void ClearWeak() { ClearWeak<void>(); }
562 
563  /**
564  * Allows the embedder to tell the v8 garbage collector that a certain object
565  * is alive. Only allowed when the embedder is asked to trace its heap by
566  * EmbedderHeapTracer.
567  */
568  V8_INLINE void RegisterExternalReference(Isolate* isolate) const;
569 
570  /**
571  * Marks the reference to this object independent. Garbage collector is free
572  * to ignore any object groups containing this object. Weak callback for an
573  * independent handle should not assume that it will be preceded by a global
574  * GC prologue callback or followed by a global GC epilogue callback.
575  */
576  V8_INLINE void MarkIndependent();
577 
578  /**
579  * Marks the reference to this object as active. The scavenge garbage
580  * collection should not reclaim the objects marked as active.
581  * This bit is cleared after the each garbage collection pass.
582  */
583  V8_INLINE void MarkActive();
584 
585  V8_INLINE bool IsIndependent() const;
586 
587  /** Checks if the handle holds the only reference to an object. */
588  V8_INLINE bool IsNearDeath() const;
589 
590  /** Returns true if the handle's reference is weak. */
591  V8_INLINE bool IsWeak() const;
592 
593  /**
594  * Assigns a wrapper class ID to the handle. See RetainedObjectInfo interface
595  * description in v8-profiler.h for details.
596  */
597  V8_INLINE void SetWrapperClassId(uint16_t class_id);
598 
599  /**
600  * Returns the class ID previously assigned to this handle or 0 if no class ID
601  * was previously assigned.
602  */
603  V8_INLINE uint16_t WrapperClassId() const;
604 
605  PersistentBase(const PersistentBase& other) = delete; // NOLINT
606  void operator=(const PersistentBase&) = delete;
607 
608  private:
609  friend class Isolate;
610  friend class Utils;
611  template<class F> friend class Local;
612  template<class F1, class F2> friend class Persistent;
613  template <class F>
614  friend class Global;
615  template<class F> friend class PersistentBase;
616  template<class F> friend class ReturnValue;
617  template <class F1, class F2, class F3>
619  template<class F1, class F2> friend class PersistentValueVector;
620  friend class Object;
621 
622  explicit V8_INLINE PersistentBase(T* val) : val_(val) {}
623  V8_INLINE static T* New(Isolate* isolate, T* that);
624 
625  T* val_;
626 };
627 
628 
629 /**
630  * Default traits for Persistent. This class does not allow
631  * use of the copy constructor or assignment operator.
632  * At present kResetInDestructor is not set, but that will change in a future
633  * version.
634  */
635 template<class T>
636 class NonCopyablePersistentTraits {
637  public:
638  typedef Persistent<T, NonCopyablePersistentTraits<T> > NonCopyablePersistent;
639  static const bool kResetInDestructor = false;
640  template<class S, class M>
641  V8_INLINE static void Copy(const Persistent<S, M>& source,
642  NonCopyablePersistent* dest) {
643  Uncompilable<Object>();
644  }
645  // TODO(dcarney): come up with a good compile error here.
646  template<class O> V8_INLINE static void Uncompilable() {
647  TYPE_CHECK(O, Primitive);
648  }
649 };
650 
651 
652 /**
653  * Helper class traits to allow copying and assignment of Persistent.
654  * This will clone the contents of storage cell, but not any of the flags, etc.
655  */
656 template<class T>
658  typedef Persistent<T, CopyablePersistentTraits<T> > CopyablePersistent;
659  static const bool kResetInDestructor = true;
660  template<class S, class M>
661  static V8_INLINE void Copy(const Persistent<S, M>& source,
662  CopyablePersistent* dest) {
663  // do nothing, just allow copy
664  }
665 };
666 
667 
668 /**
669  * A PersistentBase which allows copy and assignment.
670  *
671  * Copy, assignment and destructor behavior is controlled by the traits
672  * class M.
673  *
674  * Note: Persistent class hierarchy is subject to future changes.
675  */
676 template <class T, class M> class Persistent : public PersistentBase<T> {
677  public:
678  /**
679  * A Persistent with no storage cell.
680  */
681  V8_INLINE Persistent() : PersistentBase<T>(0) { }
682  /**
683  * Construct a Persistent from a Local.
684  * When the Local is non-empty, a new storage cell is created
685  * pointing to the same object, and no flags are set.
686  */
687  template <class S>
688  V8_INLINE Persistent(Isolate* isolate, Local<S> that)
689  : PersistentBase<T>(PersistentBase<T>::New(isolate, *that)) {
690  TYPE_CHECK(T, S);
691  }
692  /**
693  * Construct a Persistent from a Persistent.
694  * When the Persistent is non-empty, a new storage cell is created
695  * pointing to the same object, and no flags are set.
696  */
697  template <class S, class M2>
698  V8_INLINE Persistent(Isolate* isolate, const Persistent<S, M2>& that)
699  : PersistentBase<T>(PersistentBase<T>::New(isolate, *that)) {
700  TYPE_CHECK(T, S);
701  }
702  /**
703  * The copy constructors and assignment operator create a Persistent
704  * exactly as the Persistent constructor, but the Copy function from the
705  * traits class is called, allowing the setting of flags based on the
706  * copied Persistent.
707  */
708  V8_INLINE Persistent(const Persistent& that) : PersistentBase<T>(0) {
709  Copy(that);
710  }
711  template <class S, class M2>
712  V8_INLINE Persistent(const Persistent<S, M2>& that) : PersistentBase<T>(0) {
713  Copy(that);
714  }
715  V8_INLINE Persistent& operator=(const Persistent& that) { // NOLINT
716  Copy(that);
717  return *this;
718  }
719  template <class S, class M2>
720  V8_INLINE Persistent& operator=(const Persistent<S, M2>& that) { // NOLINT
721  Copy(that);
722  return *this;
723  }
724  /**
725  * The destructor will dispose the Persistent based on the
726  * kResetInDestructor flags in the traits class. Since not calling dispose
727  * can result in a memory leak, it is recommended to always set this flag.
728  */
730  if (M::kResetInDestructor) this->Reset();
731  }
732 
733  // TODO(dcarney): this is pretty useless, fix or remove
734  template <class S>
735  V8_INLINE static Persistent<T>& Cast(const Persistent<S>& that) { // NOLINT
736 #ifdef V8_ENABLE_CHECKS
737  // If we're going to perform the type check then we have to check
738  // that the handle isn't empty before doing the checked cast.
739  if (!that.IsEmpty()) T::Cast(*that);
740 #endif
741  return reinterpret_cast<Persistent<T>&>(const_cast<Persistent<S>&>(that));
742  }
743 
744  // TODO(dcarney): this is pretty useless, fix or remove
745  template <class S>
746  V8_INLINE Persistent<S>& As() const { // NOLINT
747  return Persistent<S>::Cast(*this);
748  }
749 
750  private:
751  friend class Isolate;
752  friend class Utils;
753  template<class F> friend class Local;
754  template<class F1, class F2> friend class Persistent;
755  template<class F> friend class ReturnValue;
756 
757  explicit V8_INLINE Persistent(T* that) : PersistentBase<T>(that) {}
758  V8_INLINE T* operator*() const { return this->val_; }
759  template<class S, class M2>
760  V8_INLINE void Copy(const Persistent<S, M2>& that);
761 };
762 
763 
764 /**
765  * A PersistentBase which has move semantics.
766  *
767  * Note: Persistent class hierarchy is subject to future changes.
768  */
769 template <class T>
770 class Global : public PersistentBase<T> {
771  public:
772  /**
773  * A Global with no storage cell.
774  */
776  /**
777  * Construct a Global from a Local.
778  * When the Local is non-empty, a new storage cell is created
779  * pointing to the same object, and no flags are set.
780  */
781  template <class S>
782  V8_INLINE Global(Isolate* isolate, Local<S> that)
783  : PersistentBase<T>(PersistentBase<T>::New(isolate, *that)) {
784  TYPE_CHECK(T, S);
785  }
786  /**
787  * Construct a Global from a PersistentBase.
788  * When the Persistent is non-empty, a new storage cell is created
789  * pointing to the same object, and no flags are set.
790  */
791  template <class S>
792  V8_INLINE Global(Isolate* isolate, const PersistentBase<S>& that)
793  : PersistentBase<T>(PersistentBase<T>::New(isolate, that.val_)) {
794  TYPE_CHECK(T, S);
795  }
796  /**
797  * Move constructor.
798  */
799  V8_INLINE Global(Global&& other) : PersistentBase<T>(other.val_) { // NOLINT
800  other.val_ = nullptr;
801  }
802  V8_INLINE ~Global() { this->Reset(); }
803  /**
804  * Move via assignment.
805  */
806  template <class S>
807  V8_INLINE Global& operator=(Global<S>&& rhs) { // NOLINT
808  TYPE_CHECK(T, S);
809  if (this != &rhs) {
810  this->Reset();
811  this->val_ = rhs.val_;
812  rhs.val_ = nullptr;
813  }
814  return *this;
815  }
816  /**
817  * Pass allows returning uniques from functions, etc.
818  */
819  Global Pass() { return static_cast<Global&&>(*this); } // NOLINT
820 
821  /*
822  * For compatibility with Chromium's base::Bind (base::Passed).
823  */
824  typedef void MoveOnlyTypeForCPP03;
825 
826  Global(const Global&) = delete;
827  void operator=(const Global&) = delete;
828 
829  private:
830  template <class F>
831  friend class ReturnValue;
832  V8_INLINE T* operator*() const { return this->val_; }
833 };
834 
835 
836 // UniquePersistent is an alias for Global for historical reason.
837 template <class T>
838 using UniquePersistent = Global<T>;
839 
840 
841  /**
842  * A stack-allocated class that governs a number of local handles.
843  * After a handle scope has been created, all local handles will be
844  * allocated within that handle scope until either the handle scope is
845  * deleted or another handle scope is created. If there is already a
846  * handle scope and a new one is created, all allocations will take
847  * place in the new handle scope until it is deleted. After that,
848  * new handles will again be allocated in the original handle scope.
849  *
850  * After the handle scope of a local handle has been deleted the
851  * garbage collector will no longer track the object stored in the
852  * handle and may deallocate it. The behavior of accessing a handle
853  * for which the handle scope has been deleted is undefined.
854  */
856  public:
857  explicit HandleScope(Isolate* isolate);
858 
859  ~HandleScope();
860 
861  /**
862  * Counts the number of allocated handles.
863  */
864  static int NumberOfHandles(Isolate* isolate);
865 
867  return reinterpret_cast<Isolate*>(isolate_);
868  }
869 
870  HandleScope(const HandleScope&) = delete;
871  void operator=(const HandleScope&) = delete;
872 
873  protected:
875 
876  void Initialize(Isolate* isolate);
877 
878  static internal::Object** CreateHandle(internal::Isolate* isolate,
879  internal::Object* value);
880 
881  private:
882  // Declaring operator new and delete as deleted is not spec compliant.
883  // Therefore declare them private instead to disable dynamic alloc
884  void* operator new(size_t size);
885  void* operator new[](size_t size);
886  void operator delete(void*, size_t);
887  void operator delete[](void*, size_t);
888 
889  // Uses heap_object to obtain the current Isolate.
890  static internal::Object** CreateHandle(internal::HeapObject* heap_object,
891  internal::Object* value);
892 
893  internal::Isolate* isolate_;
894  internal::Object** prev_next_;
895  internal::Object** prev_limit_;
896 
897  // Local::New uses CreateHandle with an Isolate* parameter.
898  template<class F> friend class Local;
899 
900  // Object::GetInternalField and Context::GetEmbedderData use CreateHandle with
901  // a HeapObject* in their shortcuts.
902  friend class Object;
903  friend class Context;
904 };
905 
906 
907 /**
908  * A HandleScope which first allocates a handle in the current scope
909  * which will be later filled with the escape value.
910  */
912  public:
913  explicit EscapableHandleScope(Isolate* isolate);
915 
916  /**
917  * Pushes the value into the previous scope and returns a handle to it.
918  * Cannot be called twice.
919  */
920  template <class T>
921  V8_INLINE Local<T> Escape(Local<T> value) {
922  internal::Object** slot =
923  Escape(reinterpret_cast<internal::Object**>(*value));
924  return Local<T>(reinterpret_cast<T*>(slot));
925  }
926 
928  void operator=(const EscapableHandleScope&) = delete;
929 
930  private:
931  // Declaring operator new and delete as deleted is not spec compliant.
932  // Therefore declare them private instead to disable dynamic alloc
933  void* operator new(size_t size);
934  void* operator new[](size_t size);
935  void operator delete(void*, size_t);
936  void operator delete[](void*, size_t);
937 
938  internal::Object** Escape(internal::Object** escape_value);
939  internal::Object** escape_slot_;
940 };
941 
942 /**
943  * A SealHandleScope acts like a handle scope in which no handle allocations
944  * are allowed. It can be useful for debugging handle leaks.
945  * Handles can be allocated within inner normal HandleScopes.
946  */
948  public:
949  SealHandleScope(Isolate* isolate);
950  ~SealHandleScope();
951 
952  SealHandleScope(const SealHandleScope&) = delete;
953  void operator=(const SealHandleScope&) = delete;
954 
955  private:
956  // Declaring operator new and delete as deleted is not spec compliant.
957  // Therefore declare them private instead to disable dynamic alloc
958  void* operator new(size_t size);
959  void* operator new[](size_t size);
960  void operator delete(void*, size_t);
961  void operator delete[](void*, size_t);
962 
963  internal::Isolate* const isolate_;
964  internal::Object** prev_limit_;
965  int prev_sealed_level_;
966 };
967 
968 
969 // --- Special objects ---
970 
971 
972 /**
973  * The superclass of values and API object templates.
974  */
976  private:
977  Data();
978 };
979 
980 
981 /**
982  * The optional attributes of ScriptOrigin.
983  */
985  public:
986  V8_INLINE ScriptOriginOptions(bool is_shared_cross_origin = false,
987  bool is_opaque = false, bool is_wasm = false,
988  bool is_module = false)
989  : flags_((is_shared_cross_origin ? kIsSharedCrossOrigin : 0) |
990  (is_wasm ? kIsWasm : 0) | (is_opaque ? kIsOpaque : 0) |
991  (is_module ? kIsModule : 0)) {}
993  : flags_(flags &
994  (kIsSharedCrossOrigin | kIsOpaque | kIsWasm | kIsModule)) {}
995 
996  bool IsSharedCrossOrigin() const {
997  return (flags_ & kIsSharedCrossOrigin) != 0;
998  }
999  bool IsOpaque() const { return (flags_ & kIsOpaque) != 0; }
1000  bool IsWasm() const { return (flags_ & kIsWasm) != 0; }
1001  bool IsModule() const { return (flags_ & kIsModule) != 0; }
1002 
1003  int Flags() const { return flags_; }
1004 
1005  private:
1006  enum {
1007  kIsSharedCrossOrigin = 1,
1008  kIsOpaque = 1 << 1,
1009  kIsWasm = 1 << 2,
1010  kIsModule = 1 << 3
1011  };
1012  const int flags_;
1013 };
1014 
1015 /**
1016  * The origin, within a file, of a script.
1017  */
1019  public:
1021  Local<Value> resource_name,
1022  Local<Integer> resource_line_offset = Local<Integer>(),
1023  Local<Integer> resource_column_offset = Local<Integer>(),
1024  Local<Boolean> resource_is_shared_cross_origin = Local<Boolean>(),
1025  Local<Integer> script_id = Local<Integer>(),
1026  Local<Value> source_map_url = Local<Value>(),
1027  Local<Boolean> resource_is_opaque = Local<Boolean>(),
1028  Local<Boolean> is_wasm = Local<Boolean>(),
1029  Local<Boolean> is_module = Local<Boolean>());
1030 
1031  V8_INLINE Local<Value> ResourceName() const;
1032  V8_INLINE Local<Integer> ResourceLineOffset() const;
1033  V8_INLINE Local<Integer> ResourceColumnOffset() const;
1034  V8_INLINE Local<Integer> ScriptID() const;
1035  V8_INLINE Local<Value> SourceMapUrl() const;
1036  V8_INLINE ScriptOriginOptions Options() const { return options_; }
1037 
1038  private:
1039  Local<Value> resource_name_;
1040  Local<Integer> resource_line_offset_;
1041  Local<Integer> resource_column_offset_;
1042  ScriptOriginOptions options_;
1043  Local<Integer> script_id_;
1044  Local<Value> source_map_url_;
1045 };
1046 
1047 /**
1048  * A compiled JavaScript script, not yet tied to a Context.
1049  */
1051  public:
1052  /**
1053  * Binds the script to the currently entered context.
1054  */
1055  Local<Script> BindToCurrentContext();
1056 
1057  int GetId();
1058  Local<Value> GetScriptName();
1059 
1060  /**
1061  * Data read from magic sourceURL comments.
1062  */
1063  Local<Value> GetSourceURL();
1064  /**
1065  * Data read from magic sourceMappingURL comments.
1066  */
1067  Local<Value> GetSourceMappingURL();
1068 
1069  /**
1070  * Returns zero based line number of the code_pos location in the script.
1071  * -1 will be returned if no information available.
1072  */
1073  int GetLineNumber(int code_pos);
1074 
1075  static const int kNoScriptId = 0;
1076 };
1077 
1078 /**
1079  * A location in JavaScript source.
1080  */
1082  public:
1083  int GetLineNumber() { return line_number_; }
1084  int GetColumnNumber() { return column_number_; }
1085 
1086  Location(int line_number, int column_number)
1087  : line_number_(line_number), column_number_(column_number) {}
1088 
1089  private:
1090  int line_number_;
1091  int column_number_;
1092 };
1093 
1094 /**
1095  * This is an unfinished experimental feature, and is only exposed
1096  * here for internal testing purposes. DO NOT USE.
1097  *
1098  * A compiled JavaScript module.
1099  */
1101  public:
1102  /**
1103  * The different states a module can be in.
1104  */
1105  enum Status {
1112  };
1113 
1114  /**
1115  * Returns the module's current status.
1116  */
1117  Status GetStatus() const;
1118 
1119  /**
1120  * For a module in kErrored status, this returns the corresponding exception.
1121  */
1122  Local<Value> GetException() const;
1123 
1124  /**
1125  * Returns the number of modules requested by this module.
1126  */
1127  int GetModuleRequestsLength() const;
1128 
1129  /**
1130  * Returns the ith module specifier in this module.
1131  * i must be < GetModuleRequestsLength() and >= 0.
1132  */
1133  Local<String> GetModuleRequest(int i) const;
1134 
1135  /**
1136  * Returns the source location (line number and column number) of the ith
1137  * module specifier's first occurrence in this module.
1138  */
1139  Location GetModuleRequestLocation(int i) const;
1140 
1141  /**
1142  * Returns the identity hash for this object.
1143  */
1144  int GetIdentityHash() const;
1145 
1146  typedef MaybeLocal<Module> (*ResolveCallback)(Local<Context> context,
1147  Local<String> specifier,
1148  Local<Module> referrer);
1149 
1150  /**
1151  * ModuleDeclarationInstantiation
1152  *
1153  * Returns an empty Maybe<bool> if an exception occurred during
1154  * instantiation. (In the case where the callback throws an exception, that
1155  * exception is propagated.)
1156  */
1157  V8_DEPRECATED("Use Maybe<bool> version",
1158  bool Instantiate(Local<Context> context,
1159  ResolveCallback callback));
1160  V8_WARN_UNUSED_RESULT Maybe<bool> InstantiateModule(Local<Context> context,
1161  ResolveCallback callback);
1162 
1163  /**
1164  * ModuleEvaluation
1165  *
1166  * Returns the completion value.
1167  * TODO(neis): Be more precise or say nothing.
1168  */
1169  V8_WARN_UNUSED_RESULT MaybeLocal<Value> Evaluate(Local<Context> context);
1170 
1171  /**
1172  * Returns the namespace object of this module. The module must have
1173  * been successfully instantiated before and must not be errored.
1174  */
1175  Local<Value> GetModuleNamespace();
1176 };
1177 
1178 /**
1179  * A compiled JavaScript script, tied to a Context which was active when the
1180  * script was compiled.
1181  */
1183  public:
1184  /**
1185  * A shorthand for ScriptCompiler::Compile().
1186  */
1187  static V8_DEPRECATE_SOON(
1188  "Use maybe version",
1189  Local<Script> Compile(Local<String> source,
1190  ScriptOrigin* origin = nullptr));
1191  static V8_WARN_UNUSED_RESULT MaybeLocal<Script> Compile(
1192  Local<Context> context, Local<String> source,
1193  ScriptOrigin* origin = nullptr);
1194 
1195  static Local<Script> V8_DEPRECATE_SOON("Use maybe version",
1196  Compile(Local<String> source,
1197  Local<String> file_name));
1198 
1199  /**
1200  * Runs the script returning the resulting value. It will be run in the
1201  * context in which it was created (ScriptCompiler::CompileBound or
1202  * UnboundScript::BindToCurrentContext()).
1203  */
1204  V8_DEPRECATE_SOON("Use maybe version", Local<Value> Run());
1205  V8_WARN_UNUSED_RESULT MaybeLocal<Value> Run(Local<Context> context);
1206 
1207  /**
1208  * Returns the corresponding context-unbound script.
1209  */
1211 };
1212 
1213 
1214 /**
1215  * For compiling scripts.
1216  */
1218  public:
1219  /**
1220  * Compilation data that the embedder can cache and pass back to speed up
1221  * future compilations. The data is produced if the CompilerOptions passed to
1222  * the compilation functions in ScriptCompiler contains produce_data_to_cache
1223  * = true. The data to cache can then can be retrieved from
1224  * UnboundScript.
1225  */
1230  };
1231 
1233  : data(NULL),
1234  length(0),
1235  rejected(false),
1237 
1238  // If buffer_policy is BufferNotOwned, the caller keeps the ownership of
1239  // data and guarantees that it stays alive until the CachedData object is
1240  // destroyed. If the policy is BufferOwned, the given data will be deleted
1241  // (with delete[]) when the CachedData object is destroyed.
1242  CachedData(const uint8_t* data, int length,
1243  BufferPolicy buffer_policy = BufferNotOwned);
1244  ~CachedData();
1245  // TODO(marja): Async compilation; add constructors which take a callback
1246  // which will be called when V8 no longer needs the data.
1247  const uint8_t* data;
1248  int length;
1249  bool rejected;
1251 
1252  // Prevent copying.
1253  CachedData(const CachedData&) = delete;
1254  CachedData& operator=(const CachedData&) = delete;
1255  };
1256 
1257  /**
1258  * Source code which can be then compiled to a UnboundScript or Script.
1259  */
1260  class Source {
1261  public:
1262  // Source takes ownership of CachedData.
1263  V8_INLINE Source(Local<String> source_string, const ScriptOrigin& origin,
1264  CachedData* cached_data = NULL);
1265  V8_INLINE Source(Local<String> source_string,
1266  CachedData* cached_data = NULL);
1267  V8_INLINE ~Source();
1268 
1269  // Ownership of the CachedData or its buffers is *not* transferred to the
1270  // caller. The CachedData object is alive as long as the Source object is
1271  // alive.
1272  V8_INLINE const CachedData* GetCachedData() const;
1273 
1275 
1276  // Prevent copying.
1277  Source(const Source&) = delete;
1278  Source& operator=(const Source&) = delete;
1279 
1280  private:
1281  friend class ScriptCompiler;
1282 
1283  Local<String> source_string;
1284 
1285  // Origin information
1286  Local<Value> resource_name;
1287  Local<Integer> resource_line_offset;
1288  Local<Integer> resource_column_offset;
1289  ScriptOriginOptions resource_options;
1290  Local<Value> source_map_url;
1291 
1292  // Cached data from previous compilation (if a kConsume*Cache flag is
1293  // set), or hold newly generated cache data (kProduce*Cache flags) are
1294  // set when calling a compile method.
1295  CachedData* cached_data;
1296  };
1297 
1298  /**
1299  * For streaming incomplete script data to V8. The embedder should implement a
1300  * subclass of this class.
1301  */
1303  public:
1304  virtual ~ExternalSourceStream() {}
1305 
1306  /**
1307  * V8 calls this to request the next chunk of data from the embedder. This
1308  * function will be called on a background thread, so it's OK to block and
1309  * wait for the data, if the embedder doesn't have data yet. Returns the
1310  * length of the data returned. When the data ends, GetMoreData should
1311  * return 0. Caller takes ownership of the data.
1312  *
1313  * If the embedder wants to cancel the streaming, they should make the next
1314  * GetMoreData call return 0. V8 will interpret it as end of data (and most
1315  * probably, parsing will fail). The streaming task will return as soon as
1316  * V8 has parsed the data it received so far.
1317  */
1318  virtual size_t GetMoreData(const uint8_t** src) = 0;
1319 
1320  /**
1321  * V8 calls this method to set a 'bookmark' at the current position in
1322  * the source stream, for the purpose of (maybe) later calling
1323  * ResetToBookmark. If ResetToBookmark is called later, then subsequent
1324  * calls to GetMoreData should return the same data as they did when
1325  * SetBookmark was called earlier.
1326  *
1327  * The embedder may return 'false' to indicate it cannot provide this
1328  * functionality.
1329  */
1330  virtual bool SetBookmark();
1331 
1332  /**
1333  * V8 calls this to return to a previously set bookmark.
1334  */
1335  virtual void ResetToBookmark();
1336  };
1337 
1338 
1339  /**
1340  * Source code which can be streamed into V8 in pieces. It will be parsed
1341  * while streaming. It can be compiled after the streaming is complete.
1342  * StreamedSource must be kept alive while the streaming task is ran (see
1343  * ScriptStreamingTask below).
1344  */
1346  public:
1348 
1349  StreamedSource(ExternalSourceStream* source_stream, Encoding encoding);
1350  ~StreamedSource();
1351 
1352  // Ownership of the CachedData or its buffers is *not* transferred to the
1353  // caller. The CachedData object is alive as long as the StreamedSource
1354  // object is alive.
1355  const CachedData* GetCachedData() const;
1356 
1357  internal::StreamedSource* impl() const { return impl_; }
1358 
1359  // Prevent copying.
1360  StreamedSource(const StreamedSource&) = delete;
1361  StreamedSource& operator=(const StreamedSource&) = delete;
1362 
1363  private:
1364  internal::StreamedSource* impl_;
1365  };
1366 
1367  /**
1368  * A streaming task which the embedder must run on a background thread to
1369  * stream scripts into V8. Returned by ScriptCompiler::StartStreamingScript.
1370  */
1372  public:
1373  virtual ~ScriptStreamingTask() {}
1374  virtual void Run() = 0;
1375  };
1376 
1383  };
1384 
1385  /**
1386  * Compiles the specified script (context-independent).
1387  * Cached data as part of the source object can be optionally produced to be
1388  * consumed later to speed up compilation of identical source scripts.
1389  *
1390  * Note that when producing cached data, the source must point to NULL for
1391  * cached data. When consuming cached data, the cached data must have been
1392  * produced by the same version of V8.
1393  *
1394  * \param source Script source code.
1395  * \return Compiled script object (context independent; for running it must be
1396  * bound to a context).
1397  */
1398  static V8_DEPRECATED("Use maybe version",
1399  Local<UnboundScript> CompileUnbound(
1400  Isolate* isolate, Source* source,
1401  CompileOptions options = kNoCompileOptions));
1403  Isolate* isolate, Source* source,
1404  CompileOptions options = kNoCompileOptions);
1405 
1406  /**
1407  * Compiles the specified script (bound to current context).
1408  *
1409  * \param source Script source code.
1410  * \param pre_data Pre-parsing data, as obtained by ScriptData::PreCompile()
1411  * using pre_data speeds compilation if it's done multiple times.
1412  * Owned by caller, no references are kept when this function returns.
1413  * \return Compiled script object, bound to the context that was active
1414  * when this function was called. When run it will always use this
1415  * context.
1416  */
1417  static V8_DEPRECATED(
1418  "Use maybe version",
1419  Local<Script> Compile(Isolate* isolate, Source* source,
1420  CompileOptions options = kNoCompileOptions));
1421  static V8_WARN_UNUSED_RESULT MaybeLocal<Script> Compile(
1422  Local<Context> context, Source* source,
1423  CompileOptions options = kNoCompileOptions);
1424 
1425  /**
1426  * Returns a task which streams script data into V8, or NULL if the script
1427  * cannot be streamed. The user is responsible for running the task on a
1428  * background thread and deleting it. When ran, the task starts parsing the
1429  * script, and it will request data from the StreamedSource as needed. When
1430  * ScriptStreamingTask::Run exits, all data has been streamed and the script
1431  * can be compiled (see Compile below).
1432  *
1433  * This API allows to start the streaming with as little data as possible, and
1434  * the remaining data (for example, the ScriptOrigin) is passed to Compile.
1435  */
1437  Isolate* isolate, StreamedSource* source,
1438  CompileOptions options = kNoCompileOptions);
1439 
1440  /**
1441  * Compiles a streamed script (bound to current context).
1442  *
1443  * This can only be called after the streaming has finished
1444  * (ScriptStreamingTask has been run). V8 doesn't construct the source string
1445  * during streaming, so the embedder needs to pass the full source here.
1446  */
1447  static V8_DEPRECATED("Use maybe version",
1448  Local<Script> Compile(Isolate* isolate,
1449  StreamedSource* source,
1450  Local<String> full_source_string,
1451  const ScriptOrigin& origin));
1452  static V8_WARN_UNUSED_RESULT MaybeLocal<Script> Compile(
1453  Local<Context> context, StreamedSource* source,
1454  Local<String> full_source_string, const ScriptOrigin& origin);
1455 
1456  /**
1457  * Return a version tag for CachedData for the current V8 version & flags.
1458  *
1459  * This value is meant only for determining whether a previously generated
1460  * CachedData instance is still valid; the tag has no other meaing.
1461  *
1462  * Background: The data carried by CachedData may depend on the exact
1463  * V8 version number or current compiler flags. This means that when
1464  * persisting CachedData, the embedder must take care to not pass in
1465  * data from another V8 version, or the same version with different
1466  * features enabled.
1467  *
1468  * The easiest way to do so is to clear the embedder's cache on any
1469  * such change.
1470  *
1471  * Alternatively, this tag can be stored alongside the cached data and
1472  * compared when it is being used.
1473  */
1474  static uint32_t CachedDataVersionTag();
1475 
1476  /**
1477  * This is an unfinished experimental feature, and is only exposed
1478  * here for internal testing purposes. DO NOT USE.
1479  *
1480  * Compile an ES module, returning a Module that encapsulates
1481  * the compiled code.
1482  *
1483  * Corresponds to the ParseModule abstract operation in the
1484  * ECMAScript specification.
1485  */
1486  static V8_WARN_UNUSED_RESULT MaybeLocal<Module> CompileModule(
1487  Isolate* isolate, Source* source);
1488 
1489  /**
1490  * Compile a function for a given context. This is equivalent to running
1491  *
1492  * with (obj) {
1493  * return function(args) { ... }
1494  * }
1495  *
1496  * It is possible to specify multiple context extensions (obj in the above
1497  * example).
1498  */
1499  static V8_DEPRECATE_SOON("Use maybe version",
1500  Local<Function> CompileFunctionInContext(
1501  Isolate* isolate, Source* source,
1502  Local<Context> context, size_t arguments_count,
1503  Local<String> arguments[],
1504  size_t context_extension_count,
1505  Local<Object> context_extensions[]));
1507  Local<Context> context, Source* source, size_t arguments_count,
1508  Local<String> arguments[], size_t context_extension_count,
1509  Local<Object> context_extensions[]);
1510 
1511  private:
1512  static V8_WARN_UNUSED_RESULT MaybeLocal<UnboundScript> CompileUnboundInternal(
1513  Isolate* isolate, Source* source, CompileOptions options);
1514 };
1515 
1516 
1517 /**
1518  * An error message.
1519  */
1521  public:
1522  Local<String> Get() const;
1523 
1524  V8_DEPRECATE_SOON("Use maybe version", Local<String> GetSourceLine() const);
1526  Local<Context> context) const;
1527 
1528  /**
1529  * Returns the origin for the script from where the function causing the
1530  * error originates.
1531  */
1532  ScriptOrigin GetScriptOrigin() const;
1533 
1534  /**
1535  * Returns the resource name for the script from where the function causing
1536  * the error originates.
1537  */
1538  Local<Value> GetScriptResourceName() const;
1539 
1540  /**
1541  * Exception stack trace. By default stack traces are not captured for
1542  * uncaught exceptions. SetCaptureStackTraceForUncaughtExceptions allows
1543  * to change this option.
1544  */
1545  Local<StackTrace> GetStackTrace() const;
1546 
1547  /**
1548  * Returns the number, 1-based, of the line where the error occurred.
1549  */
1550  V8_DEPRECATE_SOON("Use maybe version", int GetLineNumber() const);
1551  V8_WARN_UNUSED_RESULT Maybe<int> GetLineNumber(Local<Context> context) const;
1552 
1553  /**
1554  * Returns the index within the script of the first character where
1555  * the error occurred.
1556  */
1557  int GetStartPosition() const;
1558 
1559  /**
1560  * Returns the index within the script of the last character where
1561  * the error occurred.
1562  */
1563  int GetEndPosition() const;
1564 
1565  /**
1566  * Returns the error level of the message.
1567  */
1568  int ErrorLevel() const;
1569 
1570  /**
1571  * Returns the index within the line of the first character where
1572  * the error occurred.
1573  */
1574  V8_DEPRECATE_SOON("Use maybe version", int GetStartColumn() const);
1575  V8_WARN_UNUSED_RESULT Maybe<int> GetStartColumn(Local<Context> context) const;
1576 
1577  /**
1578  * Returns the index within the line of the last character where
1579  * the error occurred.
1580  */
1581  V8_DEPRECATED("Use maybe version", int GetEndColumn() const);
1582  V8_WARN_UNUSED_RESULT Maybe<int> GetEndColumn(Local<Context> context) const;
1583 
1584  /**
1585  * Passes on the value set by the embedder when it fed the script from which
1586  * this Message was generated to V8.
1587  */
1588  bool IsSharedCrossOrigin() const;
1589  bool IsOpaque() const;
1590 
1591  // TODO(1245381): Print to a string instead of on a FILE.
1592  static void PrintCurrentStackTrace(Isolate* isolate, FILE* out);
1593 
1594  static const int kNoLineNumberInfo = 0;
1595  static const int kNoColumnInfo = 0;
1596  static const int kNoScriptIdInfo = 0;
1597 };
1598 
1599 
1600 /**
1601  * Representation of a JavaScript stack trace. The information collected is a
1602  * snapshot of the execution stack and the information remains valid after
1603  * execution continues.
1604  */
1606  public:
1607  /**
1608  * Flags that determine what information is placed captured for each
1609  * StackFrame when grabbing the current stack trace.
1610  * Note: these options are deprecated and we always collect all available
1611  * information (kDetailed).
1612  */
1616  kScriptName = 1 << 2,
1617  kFunctionName = 1 << 3,
1618  kIsEval = 1 << 4,
1619  kIsConstructor = 1 << 5,
1621  kScriptId = 1 << 7,
1625  };
1626 
1627  /**
1628  * Returns a StackFrame at a particular index.
1629  */
1630  Local<StackFrame> GetFrame(uint32_t index) const;
1631 
1632  /**
1633  * Returns the number of StackFrames.
1634  */
1635  int GetFrameCount() const;
1636 
1637  /**
1638  * Returns StackTrace as a v8::Array that contains StackFrame objects.
1639  */
1640  V8_DEPRECATED("Use native API instead", Local<Array> AsArray());
1641 
1642  /**
1643  * Grab a snapshot of the current JavaScript execution stack.
1644  *
1645  * \param frame_limit The maximum number of stack frames we want to capture.
1646  * \param options Enumerates the set of things we will capture for each
1647  * StackFrame.
1648  */
1649  static Local<StackTrace> CurrentStackTrace(
1650  Isolate* isolate, int frame_limit, StackTraceOptions options = kDetailed);
1651 };
1652 
1653 
1654 /**
1655  * A single JavaScript stack frame.
1656  */
1658  public:
1659  /**
1660  * Returns the number, 1-based, of the line for the associate function call.
1661  * This method will return Message::kNoLineNumberInfo if it is unable to
1662  * retrieve the line number, or if kLineNumber was not passed as an option
1663  * when capturing the StackTrace.
1664  */
1665  int GetLineNumber() const;
1666 
1667  /**
1668  * Returns the 1-based column offset on the line for the associated function
1669  * call.
1670  * This method will return Message::kNoColumnInfo if it is unable to retrieve
1671  * the column number, or if kColumnOffset was not passed as an option when
1672  * capturing the StackTrace.
1673  */
1674  int GetColumn() const;
1675 
1676  /**
1677  * Returns the id of the script for the function for this StackFrame.
1678  * This method will return Message::kNoScriptIdInfo if it is unable to
1679  * retrieve the script id, or if kScriptId was not passed as an option when
1680  * capturing the StackTrace.
1681  */
1682  int GetScriptId() const;
1683 
1684  /**
1685  * Returns the name of the resource that contains the script for the
1686  * function for this StackFrame.
1687  */
1688  Local<String> GetScriptName() const;
1689 
1690  /**
1691  * Returns the name of the resource that contains the script for the
1692  * function for this StackFrame or sourceURL value if the script name
1693  * is undefined and its source ends with //# sourceURL=... string or
1694  * deprecated //@ sourceURL=... string.
1695  */
1696  Local<String> GetScriptNameOrSourceURL() const;
1697 
1698  /**
1699  * Returns the name of the function associated with this stack frame.
1700  */
1701  Local<String> GetFunctionName() const;
1702 
1703  /**
1704  * Returns whether or not the associated function is compiled via a call to
1705  * eval().
1706  */
1707  bool IsEval() const;
1708 
1709  /**
1710  * Returns whether or not the associated function is called as a
1711  * constructor via "new".
1712  */
1713  bool IsConstructor() const;
1714 
1715  /**
1716  * Returns whether or not the associated functions is defined in wasm.
1717  */
1718  bool IsWasm() const;
1719 };
1720 
1721 
1722 // A StateTag represents a possible state of the VM.
1724 
1725 // A RegisterState represents the current state of registers used
1726 // by the sampling profiler API.
1729  void* pc; // Instruction pointer.
1730  void* sp; // Stack pointer.
1731  void* fp; // Frame pointer.
1732 };
1733 
1734 // The output structure filled up by GetStackSample API function.
1735 struct SampleInfo {
1736  size_t frames_count; // Number of frames collected.
1737  StateTag vm_state; // Current VM state.
1738  void* external_callback_entry; // External callback address if VM is
1739  // executing an external callback.
1740 };
1741 
1742 /**
1743  * A JSON Parser and Stringifier.
1744  */
1746  public:
1747  /**
1748  * Tries to parse the string |json_string| and returns it as value if
1749  * successful.
1750  *
1751  * \param json_string The string to parse.
1752  * \return The corresponding value if successfully parsed.
1753  */
1754  static V8_DEPRECATED("Use the maybe version taking context",
1755  Local<Value> Parse(Local<String> json_string));
1756  static V8_DEPRECATE_SOON("Use the maybe version taking context",
1757  MaybeLocal<Value> Parse(Isolate* isolate,
1758  Local<String> json_string));
1759  static V8_WARN_UNUSED_RESULT MaybeLocal<Value> Parse(
1760  Local<Context> context, Local<String> json_string);
1761 
1762  /**
1763  * Tries to stringify the JSON-serializable object |json_object| and returns
1764  * it as string if successful.
1765  *
1766  * \param json_object The JSON-serializable object to stringify.
1767  * \return The corresponding string if successfully stringified.
1768  */
1769  static V8_WARN_UNUSED_RESULT MaybeLocal<String> Stringify(
1770  Local<Context> context, Local<Object> json_object,
1771  Local<String> gap = Local<String>());
1772 };
1773 
1774 /**
1775  * Value serialization compatible with the HTML structured clone algorithm.
1776  * The format is backward-compatible (i.e. safe to store to disk).
1777  *
1778  * WARNING: This API is under development, and changes (including incompatible
1779  * changes to the API or wire format) may occur without notice until this
1780  * warning is removed.
1781  */
1783  public:
1785  public:
1786  virtual ~Delegate() {}
1787 
1788  /**
1789  * Handles the case where a DataCloneError would be thrown in the structured
1790  * clone spec. Other V8 embedders may throw some other appropriate exception
1791  * type.
1792  */
1793  virtual void ThrowDataCloneError(Local<String> message) = 0;
1794 
1795  /**
1796  * The embedder overrides this method to write some kind of host object, if
1797  * possible. If not, a suitable exception should be thrown and
1798  * Nothing<bool>() returned.
1799  */
1800  virtual Maybe<bool> WriteHostObject(Isolate* isolate, Local<Object> object);
1801 
1802  /**
1803  * Called when the ValueSerializer is going to serialize a
1804  * SharedArrayBuffer object. The embedder must return an ID for the
1805  * object, using the same ID if this SharedArrayBuffer has already been
1806  * serialized in this buffer. When deserializing, this ID will be passed to
1807  * ValueDeserializer::TransferSharedArrayBuffer as |transfer_id|.
1808  *
1809  * If the object cannot be serialized, an
1810  * exception should be thrown and Nothing<uint32_t>() returned.
1811  */
1812  virtual Maybe<uint32_t> GetSharedArrayBufferId(
1813  Isolate* isolate, Local<SharedArrayBuffer> shared_array_buffer);
1814 
1815  virtual Maybe<uint32_t> GetWasmModuleTransferId(
1816  Isolate* isolate, Local<WasmCompiledModule> module);
1817  /**
1818  * Allocates memory for the buffer of at least the size provided. The actual
1819  * size (which may be greater or equal) is written to |actual_size|. If no
1820  * buffer has been allocated yet, nullptr will be provided.
1821  *
1822  * If the memory cannot be allocated, nullptr should be returned.
1823  * |actual_size| will be ignored. It is assumed that |old_buffer| is still
1824  * valid in this case and has not been modified.
1825  */
1826  virtual void* ReallocateBufferMemory(void* old_buffer, size_t size,
1827  size_t* actual_size);
1828 
1829  /**
1830  * Frees a buffer allocated with |ReallocateBufferMemory|.
1831  */
1832  virtual void FreeBufferMemory(void* buffer);
1833  };
1834 
1835  explicit ValueSerializer(Isolate* isolate);
1836  ValueSerializer(Isolate* isolate, Delegate* delegate);
1837  ~ValueSerializer();
1838 
1839  /**
1840  * Writes out a header, which includes the format version.
1841  */
1842  void WriteHeader();
1843 
1844  /**
1845  * Serializes a JavaScript value into the buffer.
1846  */
1847  V8_WARN_UNUSED_RESULT Maybe<bool> WriteValue(Local<Context> context,
1848  Local<Value> value);
1849 
1850  /**
1851  * Returns the stored data. This serializer should not be used once the buffer
1852  * is released. The contents are undefined if a previous write has failed.
1853  */
1854  V8_DEPRECATE_SOON("Use Release()", std::vector<uint8_t> ReleaseBuffer());
1855 
1856  /**
1857  * Returns the stored data (allocated using the delegate's
1858  * AllocateBufferMemory) and its size. This serializer should not be used once
1859  * the buffer is released. The contents are undefined if a previous write has
1860  * failed.
1861  */
1863 
1864  /**
1865  * Marks an ArrayBuffer as havings its contents transferred out of band.
1866  * Pass the corresponding ArrayBuffer in the deserializing context to
1867  * ValueDeserializer::TransferArrayBuffer.
1868  */
1869  void TransferArrayBuffer(uint32_t transfer_id,
1870  Local<ArrayBuffer> array_buffer);
1871 
1872  /**
1873  * Similar to TransferArrayBuffer, but for SharedArrayBuffer.
1874  */
1875  V8_DEPRECATE_SOON("Use Delegate::GetSharedArrayBufferId",
1876  void TransferSharedArrayBuffer(
1877  uint32_t transfer_id,
1878  Local<SharedArrayBuffer> shared_array_buffer));
1879 
1880  /**
1881  * Indicate whether to treat ArrayBufferView objects as host objects,
1882  * i.e. pass them to Delegate::WriteHostObject. This should not be
1883  * called when no Delegate was passed.
1884  *
1885  * The default is not to treat ArrayBufferViews as host objects.
1886  */
1887  void SetTreatArrayBufferViewsAsHostObjects(bool mode);
1888 
1889  /**
1890  * Write raw data in various common formats to the buffer.
1891  * Note that integer types are written in base-128 varint format, not with a
1892  * binary copy. For use during an override of Delegate::WriteHostObject.
1893  */
1894  void WriteUint32(uint32_t value);
1895  void WriteUint64(uint64_t value);
1896  void WriteDouble(double value);
1897  void WriteRawBytes(const void* source, size_t length);
1898 
1899  private:
1900  ValueSerializer(const ValueSerializer&) = delete;
1901  void operator=(const ValueSerializer&) = delete;
1902 
1903  struct PrivateData;
1904  PrivateData* private_;
1905 };
1906 
1907 /**
1908  * Deserializes values from data written with ValueSerializer, or a compatible
1909  * implementation.
1910  *
1911  * WARNING: This API is under development, and changes (including incompatible
1912  * changes to the API or wire format) may occur without notice until this
1913  * warning is removed.
1914  */
1916  public:
1918  public:
1919  virtual ~Delegate() {}
1920 
1921  /**
1922  * The embedder overrides this method to read some kind of host object, if
1923  * possible. If not, a suitable exception should be thrown and
1924  * MaybeLocal<Object>() returned.
1925  */
1926  virtual MaybeLocal<Object> ReadHostObject(Isolate* isolate);
1927 
1928  /**
1929  * Get a WasmCompiledModule given a transfer_id previously provided
1930  * by ValueSerializer::GetWasmModuleTransferId
1931  */
1932  virtual MaybeLocal<WasmCompiledModule> GetWasmModuleFromId(
1933  Isolate* isolate, uint32_t transfer_id);
1934  };
1935 
1936  ValueDeserializer(Isolate* isolate, const uint8_t* data, size_t size);
1937  ValueDeserializer(Isolate* isolate, const uint8_t* data, size_t size,
1938  Delegate* delegate);
1939  ~ValueDeserializer();
1940 
1941  /**
1942  * Reads and validates a header (including the format version).
1943  * May, for example, reject an invalid or unsupported wire format.
1944  */
1945  V8_WARN_UNUSED_RESULT Maybe<bool> ReadHeader(Local<Context> context);
1946 
1947  /**
1948  * Deserializes a JavaScript value from the buffer.
1949  */
1950  V8_WARN_UNUSED_RESULT MaybeLocal<Value> ReadValue(Local<Context> context);
1951 
1952  /**
1953  * Accepts the array buffer corresponding to the one passed previously to
1954  * ValueSerializer::TransferArrayBuffer.
1955  */
1956  void TransferArrayBuffer(uint32_t transfer_id,
1957  Local<ArrayBuffer> array_buffer);
1958 
1959  /**
1960  * Similar to TransferArrayBuffer, but for SharedArrayBuffer.
1961  * The id is not necessarily in the same namespace as unshared ArrayBuffer
1962  * objects.
1963  */
1964  void TransferSharedArrayBuffer(uint32_t id,
1965  Local<SharedArrayBuffer> shared_array_buffer);
1966 
1967  /**
1968  * Must be called before ReadHeader to enable support for reading the legacy
1969  * wire format (i.e., which predates this being shipped).
1970  *
1971  * Don't use this unless you need to read data written by previous versions of
1972  * blink::ScriptValueSerializer.
1973  */
1974  void SetSupportsLegacyWireFormat(bool supports_legacy_wire_format);
1975 
1976  /**
1977  * Expect inline wasm in the data stream (rather than in-memory transfer)
1978  */
1979  void SetExpectInlineWasm(bool allow_inline_wasm);
1980 
1981  /**
1982  * Reads the underlying wire format version. Likely mostly to be useful to
1983  * legacy code reading old wire format versions. Must be called after
1984  * ReadHeader.
1985  */
1986  uint32_t GetWireFormatVersion() const;
1987 
1988  /**
1989  * Reads raw data in various common formats to the buffer.
1990  * Note that integer types are read in base-128 varint format, not with a
1991  * binary copy. For use during an override of Delegate::ReadHostObject.
1992  */
1993  V8_WARN_UNUSED_RESULT bool ReadUint32(uint32_t* value);
1994  V8_WARN_UNUSED_RESULT bool ReadUint64(uint64_t* value);
1995  V8_WARN_UNUSED_RESULT bool ReadDouble(double* value);
1996  V8_WARN_UNUSED_RESULT bool ReadRawBytes(size_t length, const void** data);
1997 
1998  private:
1999  ValueDeserializer(const ValueDeserializer&) = delete;
2000  void operator=(const ValueDeserializer&) = delete;
2001 
2002  struct PrivateData;
2003  PrivateData* private_;
2004 };
2005 
2006 /**
2007  * A map whose keys are referenced weakly. It is similar to JavaScript WeakMap
2008  * but can be created without entering a v8::Context and hence shouldn't
2009  * escape to JavaScript.
2010  */
2011 class V8_EXPORT NativeWeakMap : public Data {
2012  public:
2013  static Local<NativeWeakMap> New(Isolate* isolate);
2014  void Set(Local<Value> key, Local<Value> value);
2015  Local<Value> Get(Local<Value> key) const;
2016  bool Has(Local<Value> key);
2017  bool Delete(Local<Value> key);
2018 };
2019 
2020 
2021 // --- Value ---
2022 
2023 
2024 /**
2025  * The superclass of all JavaScript values and objects.
2026  */
2027 class V8_EXPORT Value : public Data {
2028  public:
2029  /**
2030  * Returns true if this value is the undefined value. See ECMA-262
2031  * 4.3.10.
2032  */
2033  V8_INLINE bool IsUndefined() const;
2034 
2035  /**
2036  * Returns true if this value is the null value. See ECMA-262
2037  * 4.3.11.
2038  */
2039  V8_INLINE bool IsNull() const;
2040 
2041  /**
2042  * Returns true if this value is either the null or the undefined value.
2043  * See ECMA-262
2044  * 4.3.11. and 4.3.12
2045  */
2046  V8_INLINE bool IsNullOrUndefined() const;
2047 
2048  /**
2049  * Returns true if this value is true.
2050  */
2051  bool IsTrue() const;
2052 
2053  /**
2054  * Returns true if this value is false.
2055  */
2056  bool IsFalse() const;
2057 
2058  /**
2059  * Returns true if this value is a symbol or a string.
2060  */
2061  bool IsName() const;
2062 
2063  /**
2064  * Returns true if this value is an instance of the String type.
2065  * See ECMA-262 8.4.
2066  */
2067  V8_INLINE bool IsString() const;
2068 
2069  /**
2070  * Returns true if this value is a symbol.
2071  */
2072  bool IsSymbol() const;
2073 
2074  /**
2075  * Returns true if this value is a function.
2076  */
2077  bool IsFunction() const;
2078 
2079  /**
2080  * Returns true if this value is an array. Note that it will return false for
2081  * an Proxy for an array.
2082  */
2083  bool IsArray() const;
2084 
2085  /**
2086  * Returns true if this value is an object.
2087  */
2088  bool IsObject() const;
2089 
2090  /**
2091  * Returns true if this value is boolean.
2092  */
2093  bool IsBoolean() const;
2094 
2095  /**
2096  * Returns true if this value is a number.
2097  */
2098  bool IsNumber() const;
2099 
2100  /**
2101  * Returns true if this value is external.
2102  */
2103  bool IsExternal() const;
2104 
2105  /**
2106  * Returns true if this value is a 32-bit signed integer.
2107  */
2108  bool IsInt32() const;
2109 
2110  /**
2111  * Returns true if this value is a 32-bit unsigned integer.
2112  */
2113  bool IsUint32() const;
2114 
2115  /**
2116  * Returns true if this value is a Date.
2117  */
2118  bool IsDate() const;
2119 
2120  /**
2121  * Returns true if this value is an Arguments object.
2122  */
2123  bool IsArgumentsObject() const;
2124 
2125  /**
2126  * Returns true if this value is a Boolean object.
2127  */
2128  bool IsBooleanObject() const;
2129 
2130  /**
2131  * Returns true if this value is a Number object.
2132  */
2133  bool IsNumberObject() const;
2134 
2135  /**
2136  * Returns true if this value is a String object.
2137  */
2138  bool IsStringObject() const;
2139 
2140  /**
2141  * Returns true if this value is a Symbol object.
2142  */
2143  bool IsSymbolObject() const;
2144 
2145  /**
2146  * Returns true if this value is a NativeError.
2147  */
2148  bool IsNativeError() const;
2149 
2150  /**
2151  * Returns true if this value is a RegExp.
2152  */
2153  bool IsRegExp() const;
2154 
2155  /**
2156  * Returns true if this value is an async function.
2157  */
2158  bool IsAsyncFunction() const;
2159 
2160  /**
2161  * Returns true if this value is a Generator function.
2162  */
2163  bool IsGeneratorFunction() const;
2164 
2165  /**
2166  * Returns true if this value is a Generator object (iterator).
2167  */
2168  bool IsGeneratorObject() const;
2169 
2170  /**
2171  * Returns true if this value is a Promise.
2172  */
2173  bool IsPromise() const;
2174 
2175  /**
2176  * Returns true if this value is a Map.
2177  */
2178  bool IsMap() const;
2179 
2180  /**
2181  * Returns true if this value is a Set.
2182  */
2183  bool IsSet() const;
2184 
2185  /**
2186  * Returns true if this value is a Map Iterator.
2187  */
2188  bool IsMapIterator() const;
2189 
2190  /**
2191  * Returns true if this value is a Set Iterator.
2192  */
2193  bool IsSetIterator() const;
2194 
2195  /**
2196  * Returns true if this value is a WeakMap.
2197  */
2198  bool IsWeakMap() const;
2199 
2200  /**
2201  * Returns true if this value is a WeakSet.
2202  */
2203  bool IsWeakSet() const;
2204 
2205  /**
2206  * Returns true if this value is an ArrayBuffer.
2207  */
2208  bool IsArrayBuffer() const;
2209 
2210  /**
2211  * Returns true if this value is an ArrayBufferView.
2212  */
2213  bool IsArrayBufferView() const;
2214 
2215  /**
2216  * Returns true if this value is one of TypedArrays.
2217  */
2218  bool IsTypedArray() const;
2219 
2220  /**
2221  * Returns true if this value is an Uint8Array.
2222  */
2223  bool IsUint8Array() const;
2224 
2225  /**
2226  * Returns true if this value is an Uint8ClampedArray.
2227  */
2228  bool IsUint8ClampedArray() const;
2229 
2230  /**
2231  * Returns true if this value is an Int8Array.
2232  */
2233  bool IsInt8Array() const;
2234 
2235  /**
2236  * Returns true if this value is an Uint16Array.
2237  */
2238  bool IsUint16Array() const;
2239 
2240  /**
2241  * Returns true if this value is an Int16Array.
2242  */
2243  bool IsInt16Array() const;
2244 
2245  /**
2246  * Returns true if this value is an Uint32Array.
2247  */
2248  bool IsUint32Array() const;
2249 
2250  /**
2251  * Returns true if this value is an Int32Array.
2252  */
2253  bool IsInt32Array() const;
2254 
2255  /**
2256  * Returns true if this value is a Float32Array.
2257  */
2258  bool IsFloat32Array() const;
2259 
2260  /**
2261  * Returns true if this value is a Float64Array.
2262  */
2263  bool IsFloat64Array() const;
2264 
2265  /**
2266  * Returns true if this value is a DataView.
2267  */
2268  bool IsDataView() const;
2269 
2270  /**
2271  * Returns true if this value is a SharedArrayBuffer.
2272  * This is an experimental feature.
2273  */
2274  bool IsSharedArrayBuffer() const;
2275 
2276  /**
2277  * Returns true if this value is a JavaScript Proxy.
2278  */
2279  bool IsProxy() const;
2280 
2281  bool IsWebAssemblyCompiledModule() const;
2282 
2284  Local<Context> context) const;
2286  Local<Context> context) const;
2288  Local<Context> context) const;
2290  Local<Context> context) const;
2292  Local<Context> context) const;
2294  Local<Context> context) const;
2296  Local<Context> context) const;
2297  V8_WARN_UNUSED_RESULT MaybeLocal<Int32> ToInt32(Local<Context> context) const;
2298 
2299  V8_DEPRECATE_SOON("Use maybe version",
2300  Local<Boolean> ToBoolean(Isolate* isolate) const);
2301  V8_DEPRECATE_SOON("Use maybe version",
2302  Local<Number> ToNumber(Isolate* isolate) const);
2303  V8_DEPRECATE_SOON("Use maybe version",
2304  Local<String> ToString(Isolate* isolate) const);
2305  V8_DEPRECATED("Use maybe version",
2306  Local<String> ToDetailString(Isolate* isolate) const);
2307  V8_DEPRECATE_SOON("Use maybe version",
2308  Local<Object> ToObject(Isolate* isolate) const);
2309  V8_DEPRECATE_SOON("Use maybe version",
2310  Local<Integer> ToInteger(Isolate* isolate) const);
2311  V8_DEPRECATED("Use maybe version",
2312  Local<Uint32> ToUint32(Isolate* isolate) const);
2313  V8_DEPRECATE_SOON("Use maybe version",
2314  Local<Int32> ToInt32(Isolate* isolate) const);
2315 
2316  inline V8_DEPRECATE_SOON("Use maybe version",
2317  Local<Boolean> ToBoolean() const);
2318  inline V8_DEPRECATED("Use maybe version", Local<Number> ToNumber() const);
2319  inline V8_DEPRECATE_SOON("Use maybe version", Local<String> ToString() const);
2320  inline V8_DEPRECATED("Use maybe version",
2321  Local<String> ToDetailString() const);
2322  inline V8_DEPRECATE_SOON("Use maybe version", Local<Object> ToObject() const);
2323  inline V8_DEPRECATE_SOON("Use maybe version",
2324  Local<Integer> ToInteger() const);
2325  inline V8_DEPRECATED("Use maybe version", Local<Uint32> ToUint32() const);
2326  inline V8_DEPRECATED("Use maybe version", Local<Int32> ToInt32() const);
2327 
2328  /**
2329  * Attempts to convert a string to an array index.
2330  * Returns an empty handle if the conversion fails.
2331  */
2332  V8_DEPRECATED("Use maybe version", Local<Uint32> ToArrayIndex() const);
2334  Local<Context> context) const;
2335 
2336  V8_WARN_UNUSED_RESULT Maybe<bool> BooleanValue(Local<Context> context) const;
2337  V8_WARN_UNUSED_RESULT Maybe<double> NumberValue(Local<Context> context) const;
2338  V8_WARN_UNUSED_RESULT Maybe<int64_t> IntegerValue(
2339  Local<Context> context) const;
2340  V8_WARN_UNUSED_RESULT Maybe<uint32_t> Uint32Value(
2341  Local<Context> context) const;
2342  V8_WARN_UNUSED_RESULT Maybe<int32_t> Int32Value(Local<Context> context) const;
2343 
2344  V8_DEPRECATE_SOON("Use maybe version", bool BooleanValue() const);
2345  V8_DEPRECATE_SOON("Use maybe version", double NumberValue() const);
2346  V8_DEPRECATE_SOON("Use maybe version", int64_t IntegerValue() const);
2347  V8_DEPRECATE_SOON("Use maybe version", uint32_t Uint32Value() const);
2348  V8_DEPRECATE_SOON("Use maybe version", int32_t Int32Value() const);
2349 
2350  /** JS == */
2351  V8_DEPRECATE_SOON("Use maybe version", bool Equals(Local<Value> that) const);
2352  V8_WARN_UNUSED_RESULT Maybe<bool> Equals(Local<Context> context,
2353  Local<Value> that) const;
2354  bool StrictEquals(Local<Value> that) const;
2355  bool SameValue(Local<Value> that) const;
2356 
2357  template <class T> V8_INLINE static Value* Cast(T* value);
2358 
2359  Local<String> TypeOf(Isolate*);
2360 
2361  Maybe<bool> InstanceOf(Local<Context> context, Local<Object> object);
2362 
2363  private:
2364  V8_INLINE bool QuickIsUndefined() const;
2365  V8_INLINE bool QuickIsNull() const;
2366  V8_INLINE bool QuickIsNullOrUndefined() const;
2367  V8_INLINE bool QuickIsString() const;
2368  bool FullIsUndefined() const;
2369  bool FullIsNull() const;
2370  bool FullIsString() const;
2371 };
2372 
2373 
2374 /**
2375  * The superclass of primitive values. See ECMA-262 4.3.2.
2376  */
2377 class V8_EXPORT Primitive : public Value { };
2378 
2379 
2380 /**
2381  * A primitive boolean value (ECMA-262, 4.3.14). Either the true
2382  * or false value.
2383  */
2384 class V8_EXPORT Boolean : public Primitive {
2385  public:
2386  bool Value() const;
2387  V8_INLINE static Boolean* Cast(v8::Value* obj);
2388  V8_INLINE static Local<Boolean> New(Isolate* isolate, bool value);
2389 
2390  private:
2391  static void CheckCast(v8::Value* obj);
2392 };
2393 
2394 
2395 /**
2396  * A superclass for symbols and strings.
2397  */
2398 class V8_EXPORT Name : public Primitive {
2399  public:
2400  /**
2401  * Returns the identity hash for this object. The current implementation
2402  * uses an inline property on the object to store the identity hash.
2403  *
2404  * The return value will never be 0. Also, it is not guaranteed to be
2405  * unique.
2406  */
2407  int GetIdentityHash();
2408 
2409  V8_INLINE static Name* Cast(Value* obj);
2410 
2411  private:
2412  static void CheckCast(Value* obj);
2413 };
2414 
2415 /**
2416  * A flag describing different modes of string creation.
2417  *
2418  * Aside from performance implications there are no differences between the two
2419  * creation modes.
2420  */
2421 enum class NewStringType {
2422  /**
2423  * Create a new string, always allocating new storage memory.
2424  */
2425  kNormal,
2426 
2427  /**
2428  * Acts as a hint that the string should be created in the
2429  * old generation heap space and be deduplicated if an identical string
2430  * already exists.
2431  */
2433 };
2434 
2435 /**
2436  * A JavaScript string value (ECMA-262, 4.3.17).
2437  */
2438 class V8_EXPORT String : public Name {
2439  public:
2440  static const int kMaxLength = (1 << 28) - 16;
2441 
2442  enum Encoding {
2446  };
2447  /**
2448  * Returns the number of characters (UTF-16 code units) in this string.
2449  */
2450  int Length() const;
2451 
2452  /**
2453  * Returns the number of bytes in the UTF-8 encoded
2454  * representation of this string.
2455  */
2456  int Utf8Length() const;
2457 
2458  /**
2459  * Returns whether this string is known to contain only one byte data,
2460  * i.e. ISO-8859-1 code points.
2461  * Does not read the string.
2462  * False negatives are possible.
2463  */
2464  bool IsOneByte() const;
2465 
2466  /**
2467  * Returns whether this string contain only one byte data,
2468  * i.e. ISO-8859-1 code points.
2469  * Will read the entire string in some cases.
2470  */
2471  bool ContainsOnlyOneByte() const;
2472 
2473  /**
2474  * Write the contents of the string to an external buffer.
2475  * If no arguments are given, expects the buffer to be large
2476  * enough to hold the entire string and NULL terminator. Copies
2477  * the contents of the string and the NULL terminator into the
2478  * buffer.
2479  *
2480  * WriteUtf8 will not write partial UTF-8 sequences, preferring to stop
2481  * before the end of the buffer.
2482  *
2483  * Copies up to length characters into the output buffer.
2484  * Only null-terminates if there is enough space in the buffer.
2485  *
2486  * \param buffer The buffer into which the string will be copied.
2487  * \param start The starting position within the string at which
2488  * copying begins.
2489  * \param length The number of characters to copy from the string. For
2490  * WriteUtf8 the number of bytes in the buffer.
2491  * \param nchars_ref The number of characters written, can be NULL.
2492  * \param options Various options that might affect performance of this or
2493  * subsequent operations.
2494  * \return The number of characters copied to the buffer excluding the null
2495  * terminator. For WriteUtf8: The number of bytes copied to the buffer
2496  * including the null terminator (if written).
2497  */
2503  // Used by WriteUtf8 to replace orphan surrogate code units with the
2504  // unicode replacement character. Needs to be set to guarantee valid UTF-8
2505  // output.
2507  };
2508 
2509  // 16-bit character codes.
2510  int Write(uint16_t* buffer,
2511  int start = 0,
2512  int length = -1,
2513  int options = NO_OPTIONS) const;
2514  // One byte characters.
2515  int WriteOneByte(uint8_t* buffer,
2516  int start = 0,
2517  int length = -1,
2518  int options = NO_OPTIONS) const;
2519  // UTF-8 encoded characters.
2520  int WriteUtf8(char* buffer,
2521  int length = -1,
2522  int* nchars_ref = NULL,
2523  int options = NO_OPTIONS) const;
2524 
2525  /**
2526  * A zero length string.
2527  */
2528  V8_INLINE static Local<String> Empty(Isolate* isolate);
2529 
2530  /**
2531  * Returns true if the string is external
2532  */
2533  bool IsExternal() const;
2534 
2535  /**
2536  * Returns true if the string is both external and one-byte.
2537  */
2538  bool IsExternalOneByte() const;
2539 
2541  public:
2543 
2544  virtual bool IsCompressible() const { return false; }
2545 
2546  protected:
2548 
2549  /**
2550  * Internally V8 will call this Dispose method when the external string
2551  * resource is no longer needed. The default implementation will use the
2552  * delete operator. This method can be overridden in subclasses to
2553  * control how allocated external string resources are disposed.
2554  */
2555  virtual void Dispose() { delete this; }
2556 
2557  // Disallow copying and assigning.
2559  void operator=(const ExternalStringResourceBase&) = delete;
2560 
2561  private:
2562  friend class internal::Heap;
2563  friend class v8::String;
2564  };
2565 
2566  /**
2567  * An ExternalStringResource is a wrapper around a two-byte string
2568  * buffer that resides outside V8's heap. Implement an
2569  * ExternalStringResource to manage the life cycle of the underlying
2570  * buffer. Note that the string data must be immutable.
2571  */
2573  : public ExternalStringResourceBase {
2574  public:
2575  /**
2576  * Override the destructor to manage the life cycle of the underlying
2577  * buffer.
2578  */
2580 
2581  /**
2582  * The string data from the underlying buffer.
2583  */
2584  virtual const uint16_t* data() const = 0;
2585 
2586  /**
2587  * The length of the string. That is, the number of two-byte characters.
2588  */
2589  virtual size_t length() const = 0;
2590 
2591  protected:
2593  };
2594 
2595  /**
2596  * An ExternalOneByteStringResource is a wrapper around an one-byte
2597  * string buffer that resides outside V8's heap. Implement an
2598  * ExternalOneByteStringResource to manage the life cycle of the
2599  * underlying buffer. Note that the string data must be immutable
2600  * and that the data must be Latin-1 and not UTF-8, which would require
2601  * special treatment internally in the engine and do not allow efficient
2602  * indexing. Use String::New or convert to 16 bit data for non-Latin1.
2603  */
2604 
2606  : public ExternalStringResourceBase {
2607  public:
2608  /**
2609  * Override the destructor to manage the life cycle of the underlying
2610  * buffer.
2611  */
2613  /** The string data from the underlying buffer.*/
2614  virtual const char* data() const = 0;
2615  /** The number of Latin-1 characters in the string.*/
2616  virtual size_t length() const = 0;
2617  protected:
2619  };
2620 
2621  /**
2622  * If the string is an external string, return the ExternalStringResourceBase
2623  * regardless of the encoding, otherwise return NULL. The encoding of the
2624  * string is returned in encoding_out.
2625  */
2627  Encoding* encoding_out) const;
2628 
2629  /**
2630  * Get the ExternalStringResource for an external string. Returns
2631  * NULL if IsExternal() doesn't return true.
2632  */
2634 
2635  /**
2636  * Get the ExternalOneByteStringResource for an external one-byte string.
2637  * Returns NULL if IsExternalOneByte() doesn't return true.
2638  */
2640 
2641  V8_INLINE static String* Cast(v8::Value* obj);
2642 
2643  // TODO(dcarney): remove with deprecation of New functions.
2645  kNormalString = static_cast<int>(v8::NewStringType::kNormal),
2647  };
2648 
2649  /** Allocates a new string from UTF-8 data.*/
2650  static V8_DEPRECATE_SOON(
2651  "Use maybe version",
2652  Local<String> NewFromUtf8(Isolate* isolate, const char* data,
2654  int length = -1));
2655 
2656  /** Allocates a new string from UTF-8 data. Only returns an empty value when
2657  * length > kMaxLength. **/
2658  static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewFromUtf8(
2659  Isolate* isolate, const char* data, v8::NewStringType type,
2660  int length = -1);
2661 
2662  /** Allocates a new string from Latin-1 data.*/
2663  static V8_DEPRECATED(
2664  "Use maybe version",
2665  Local<String> NewFromOneByte(Isolate* isolate, const uint8_t* data,
2667  int length = -1));
2668 
2669  /** Allocates a new string from Latin-1 data. Only returns an empty value
2670  * when length > kMaxLength. **/
2671  static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewFromOneByte(
2672  Isolate* isolate, const uint8_t* data, v8::NewStringType type,
2673  int length = -1);
2674 
2675  /** Allocates a new string from UTF-16 data.*/
2676  static V8_DEPRECATE_SOON(
2677  "Use maybe version",
2678  Local<String> NewFromTwoByte(Isolate* isolate, const uint16_t* data,
2680  int length = -1));
2681 
2682  /** Allocates a new string from UTF-16 data. Only returns an empty value when
2683  * length > kMaxLength. **/
2684  static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewFromTwoByte(
2685  Isolate* isolate, const uint16_t* data, v8::NewStringType type,
2686  int length = -1);
2687 
2688  /**
2689  * Creates a new string by concatenating the left and the right strings
2690  * passed in as parameters.
2691  */
2692  static Local<String> Concat(Local<String> left, Local<String> right);
2693 
2694  /**
2695  * Creates a new external string using the data defined in the given
2696  * resource. When the external string is no longer live on V8's heap the
2697  * resource will be disposed by calling its Dispose method. The caller of
2698  * this function should not otherwise delete or modify the resource. Neither
2699  * should the underlying buffer be deallocated or modified except through the
2700  * destructor of the external string resource.
2701  */
2702  static V8_DEPRECATED("Use maybe version",
2703  Local<String> NewExternal(
2704  Isolate* isolate, ExternalStringResource* resource));
2705  static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewExternalTwoByte(
2706  Isolate* isolate, ExternalStringResource* resource);
2707 
2708  /**
2709  * Associate an external string resource with this string by transforming it
2710  * in place so that existing references to this string in the JavaScript heap
2711  * will use the external string resource. The external string resource's
2712  * character contents need to be equivalent to this string.
2713  * Returns true if the string has been changed to be an external string.
2714  * The string is not modified if the operation fails. See NewExternal for
2715  * information on the lifetime of the resource.
2716  */
2717  bool MakeExternal(ExternalStringResource* resource);
2718 
2719  /**
2720  * Creates a new external string using the one-byte data defined in the given
2721  * resource. When the external string is no longer live on V8's heap the
2722  * resource will be disposed by calling its Dispose method. The caller of
2723  * this function should not otherwise delete or modify the resource. Neither
2724  * should the underlying buffer be deallocated or modified except through the
2725  * destructor of the external string resource.
2726  */
2727  static V8_DEPRECATE_SOON(
2728  "Use maybe version",
2729  Local<String> NewExternal(Isolate* isolate,
2730  ExternalOneByteStringResource* resource));
2731  static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewExternalOneByte(
2732  Isolate* isolate, ExternalOneByteStringResource* resource);
2733 
2734  /**
2735  * Associate an external string resource with this string by transforming it
2736  * in place so that existing references to this string in the JavaScript heap
2737  * will use the external string resource. The external string resource's
2738  * character contents need to be equivalent to this string.
2739  * Returns true if the string has been changed to be an external string.
2740  * The string is not modified if the operation fails. See NewExternal for
2741  * information on the lifetime of the resource.
2742  */
2744 
2745  /**
2746  * Returns true if this string can be made external.
2747  */
2748  bool CanMakeExternal();
2749 
2750  /**
2751  * Converts an object to a UTF-8-encoded character array. Useful if
2752  * you want to print the object. If conversion to a string fails
2753  * (e.g. due to an exception in the toString() method of the object)
2754  * then the length() method returns 0 and the * operator returns
2755  * NULL.
2756  */
2758  public:
2759  explicit Utf8Value(Local<v8::Value> obj);
2760  ~Utf8Value();
2761  char* operator*() { return str_; }
2762  const char* operator*() const { return str_; }
2763  int length() const { return length_; }
2764 
2765  // Disallow copying and assigning.
2766  Utf8Value(const Utf8Value&) = delete;
2767  void operator=(const Utf8Value&) = delete;
2768 
2769  private:
2770  char* str_;
2771  int length_;
2772  };
2773 
2774  /**
2775  * Converts an object to a two-byte (UTF-16-encoded) string.
2776  * If conversion to a string fails (eg. due to an exception in the toString()
2777  * method of the object) then the length() method returns 0 and the * operator
2778  * returns NULL.
2779  */
2781  public:
2782  explicit Value(Local<v8::Value> obj);
2783  ~Value();
2784  uint16_t* operator*() { return str_; }
2785  const uint16_t* operator*() const { return str_; }
2786  int length() const { return length_; }
2787 
2788  // Disallow copying and assigning.
2789  Value(const Value&) = delete;
2790  void operator=(const Value&) = delete;
2791 
2792  private:
2793  uint16_t* str_;
2794  int length_;
2795  };
2796 
2797  private:
2798  void VerifyExternalStringResourceBase(ExternalStringResourceBase* v,
2799  Encoding encoding) const;
2800  void VerifyExternalStringResource(ExternalStringResource* val) const;
2801  static void CheckCast(v8::Value* obj);
2802 };
2803 
2804 
2805 /**
2806  * A JavaScript symbol (ECMA-262 edition 6)
2807  */
2808 class V8_EXPORT Symbol : public Name {
2809  public:
2810  /**
2811  * Returns the print name string of the symbol, or undefined if none.
2812  */
2813  Local<Value> Name() const;
2814 
2815  /**
2816  * Create a symbol. If name is not empty, it will be used as the description.
2817  */
2818  static Local<Symbol> New(Isolate* isolate,
2819  Local<String> name = Local<String>());
2820 
2821  /**
2822  * Access global symbol registry.
2823  * Note that symbols created this way are never collected, so
2824  * they should only be used for statically fixed properties.
2825  * Also, there is only one global name space for the names used as keys.
2826  * To minimize the potential for clashes, use qualified names as keys.
2827  */
2828  static Local<Symbol> For(Isolate *isolate, Local<String> name);
2829 
2830  /**
2831  * Retrieve a global symbol. Similar to |For|, but using a separate
2832  * registry that is not accessible by (and cannot clash with) JavaScript code.
2833  */
2834  static Local<Symbol> ForApi(Isolate *isolate, Local<String> name);
2835 
2836  // Well-known symbols
2837  static Local<Symbol> GetHasInstance(Isolate* isolate);
2838  static Local<Symbol> GetIsConcatSpreadable(Isolate* isolate);
2839  static Local<Symbol> GetIterator(Isolate* isolate);
2840  static Local<Symbol> GetMatch(Isolate* isolate);
2841  static Local<Symbol> GetReplace(Isolate* isolate);
2842  static Local<Symbol> GetSearch(Isolate* isolate);
2843  static Local<Symbol> GetSplit(Isolate* isolate);
2844  static Local<Symbol> GetToPrimitive(Isolate* isolate);
2845  static Local<Symbol> GetToStringTag(Isolate* isolate);
2846  static Local<Symbol> GetUnscopables(Isolate* isolate);
2847 
2848  V8_INLINE static Symbol* Cast(Value* obj);
2849 
2850  private:
2851  Symbol();
2852  static void CheckCast(Value* obj);
2853 };
2854 
2855 
2856 /**
2857  * A private symbol
2858  *
2859  * This is an experimental feature. Use at your own risk.
2860  */
2861 class V8_EXPORT Private : public Data {
2862  public:
2863  /**
2864  * Returns the print name string of the private symbol, or undefined if none.
2865  */
2866  Local<Value> Name() const;
2867 
2868  /**
2869  * Create a private symbol. If name is not empty, it will be the description.
2870  */
2871  static Local<Private> New(Isolate* isolate,
2872  Local<String> name = Local<String>());
2873 
2874  /**
2875  * Retrieve a global private symbol. If a symbol with this name has not
2876  * been retrieved in the same isolate before, it is created.
2877  * Note that private symbols created this way are never collected, so
2878  * they should only be used for statically fixed properties.
2879  * Also, there is only one global name space for the names used as keys.
2880  * To minimize the potential for clashes, use qualified names as keys,
2881  * e.g., "Class#property".
2882  */
2883  static Local<Private> ForApi(Isolate* isolate, Local<String> name);
2884 
2885  private:
2886  Private();
2887 };
2888 
2889 
2890 /**
2891  * A JavaScript number value (ECMA-262, 4.3.20)
2892  */
2893 class V8_EXPORT Number : public Primitive {
2894  public:
2895  double Value() const;
2896  static Local<Number> New(Isolate* isolate, double value);
2897  V8_INLINE static Number* Cast(v8::Value* obj);
2898  private:
2899  Number();
2900  static void CheckCast(v8::Value* obj);
2901 };
2902 
2903 
2904 /**
2905  * A JavaScript value representing a signed integer.
2906  */
2907 class V8_EXPORT Integer : public Number {
2908  public:
2909  static Local<Integer> New(Isolate* isolate, int32_t value);
2910  static Local<Integer> NewFromUnsigned(Isolate* isolate, uint32_t value);
2911  int64_t Value() const;
2912  V8_INLINE static Integer* Cast(v8::Value* obj);
2913  private:
2914  Integer();
2915  static void CheckCast(v8::Value* obj);
2916 };
2917 
2918 
2919 /**
2920  * A JavaScript value representing a 32-bit signed integer.
2921  */
2922 class V8_EXPORT Int32 : public Integer {
2923  public:
2924  int32_t Value() const;
2925  V8_INLINE static Int32* Cast(v8::Value* obj);
2926 
2927  private:
2928  Int32();
2929  static void CheckCast(v8::Value* obj);
2930 };
2931 
2932 
2933 /**
2934  * A JavaScript value representing a 32-bit unsigned integer.
2935  */
2936 class V8_EXPORT Uint32 : public Integer {
2937  public:
2938  uint32_t Value() const;
2939  V8_INLINE static Uint32* Cast(v8::Value* obj);
2940 
2941  private:
2942  Uint32();
2943  static void CheckCast(v8::Value* obj);
2944 };
2945 
2946 /**
2947  * PropertyAttribute.
2948  */
2950  /** None. **/
2951  None = 0,
2952  /** ReadOnly, i.e., not writable. **/
2953  ReadOnly = 1 << 0,
2954  /** DontEnum, i.e., not enumerable. **/
2955  DontEnum = 1 << 1,
2956  /** DontDelete, i.e., not configurable. **/
2957  DontDelete = 1 << 2
2958 };
2959 
2960 /**
2961  * Accessor[Getter|Setter] are used as callback functions when
2962  * setting|getting a particular property. See Object and ObjectTemplate's
2963  * method SetAccessor.
2964  */
2965 typedef void (*AccessorGetterCallback)(
2966  Local<String> property,
2967  const PropertyCallbackInfo<Value>& info);
2969  Local<Name> property,
2970  const PropertyCallbackInfo<Value>& info);
2971 
2972 
2973 typedef void (*AccessorSetterCallback)(
2974  Local<String> property,
2975  Local<Value> value,
2976  const PropertyCallbackInfo<void>& info);
2978  Local<Name> property,
2979  Local<Value> value,
2980  const PropertyCallbackInfo<void>& info);
2981 
2982 
2983 /**
2984  * Access control specifications.
2985  *
2986  * Some accessors should be accessible across contexts. These
2987  * accessors have an explicit access control parameter which specifies
2988  * the kind of cross-context access that should be allowed.
2989  *
2990  * TODO(dcarney): Remove PROHIBITS_OVERWRITING as it is now unused.
2991  */
2993  DEFAULT = 0,
2995  ALL_CAN_WRITE = 1 << 1,
2997 };
2998 
2999 /**
3000  * Property filter bits. They can be or'ed to build a composite filter.
3001  */
3009 };
3010 
3011 /**
3012  * Keys/Properties filter enums:
3013  *
3014  * KeyCollectionMode limits the range of collected properties. kOwnOnly limits
3015  * the collected properties to the given Object only. kIncludesPrototypes will
3016  * include all keys of the objects's prototype chain as well.
3017  */
3019 
3020 /**
3021  * kIncludesIndices allows for integer indices to be collected, while
3022  * kSkipIndices will exclude integer indicies from being collected.
3023  */
3025 
3026 /**
3027  * Integrity level for objects.
3028  */
3030 
3031 /**
3032  * A JavaScript object (ECMA-262, 4.3.3)
3033  */
3034 class V8_EXPORT Object : public Value {
3035  public:
3036  V8_DEPRECATE_SOON("Use maybe version",
3037  bool Set(Local<Value> key, Local<Value> value));
3038  V8_WARN_UNUSED_RESULT Maybe<bool> Set(Local<Context> context,
3039  Local<Value> key, Local<Value> value);
3040 
3041  V8_DEPRECATE_SOON("Use maybe version",
3042  bool Set(uint32_t index, Local<Value> value));
3043  V8_WARN_UNUSED_RESULT Maybe<bool> Set(Local<Context> context, uint32_t index,
3044  Local<Value> value);
3045 
3046  // Implements CreateDataProperty (ECMA-262, 7.3.4).
3047  //
3048  // Defines a configurable, writable, enumerable property with the given value
3049  // on the object unless the property already exists and is not configurable
3050  // or the object is not extensible.
3051  //
3052  // Returns true on success.
3053  V8_WARN_UNUSED_RESULT Maybe<bool> CreateDataProperty(Local<Context> context,
3054  Local<Name> key,
3055  Local<Value> value);
3056  V8_WARN_UNUSED_RESULT Maybe<bool> CreateDataProperty(Local<Context> context,
3057  uint32_t index,
3058  Local<Value> value);
3059 
3060  // Implements DefineOwnProperty.
3061  //
3062  // In general, CreateDataProperty will be faster, however, does not allow
3063  // for specifying attributes.
3064  //
3065  // Returns true on success.
3067  Local<Context> context, Local<Name> key, Local<Value> value,
3068  PropertyAttribute attributes = None);
3069 
3070  // Implements Object.DefineProperty(O, P, Attributes), see Ecma-262 19.1.2.4.
3071  //
3072  // The defineProperty function is used to add an own property or
3073  // update the attributes of an existing own property of an object.
3074  //
3075  // Both data and accessor descriptors can be used.
3076  //
3077  // In general, CreateDataProperty is faster, however, does not allow
3078  // for specifying attributes or an accessor descriptor.
3079  //
3080  // The PropertyDescriptor can change when redefining a property.
3081  //
3082  // Returns true on success.
3084  Local<Context> context, Local<Name> key, PropertyDescriptor& descriptor);
3085 
3086  // Sets an own property on this object bypassing interceptors and
3087  // overriding accessors or read-only properties.
3088  //
3089  // Note that if the object has an interceptor the property will be set
3090  // locally, but since the interceptor takes precedence the local property
3091  // will only be returned if the interceptor doesn't return a value.
3092  //
3093  // Note also that this only works for named properties.
3094  V8_DEPRECATED("Use CreateDataProperty / DefineOwnProperty",
3095  Maybe<bool> ForceSet(Local<Context> context, Local<Value> key,
3096  Local<Value> value,
3097  PropertyAttribute attribs = None));
3098 
3099  V8_DEPRECATE_SOON("Use maybe version", Local<Value> Get(Local<Value> key));
3100  V8_WARN_UNUSED_RESULT MaybeLocal<Value> Get(Local<Context> context,
3101  Local<Value> key);
3102 
3103  V8_DEPRECATE_SOON("Use maybe version", Local<Value> Get(uint32_t index));
3104  V8_WARN_UNUSED_RESULT MaybeLocal<Value> Get(Local<Context> context,
3105  uint32_t index);
3106 
3107  /**
3108  * Gets the property attributes of a property which can be None or
3109  * any combination of ReadOnly, DontEnum and DontDelete. Returns
3110  * None when the property doesn't exist.
3111  */
3112  V8_DEPRECATED("Use maybe version",
3113  PropertyAttribute GetPropertyAttributes(Local<Value> key));
3115  Local<Context> context, Local<Value> key);
3116 
3117  /**
3118  * Returns Object.getOwnPropertyDescriptor as per ES2016 section 19.1.2.6.
3119  */
3120  V8_DEPRECATED("Use maybe version",
3121  Local<Value> GetOwnPropertyDescriptor(Local<Name> key));
3123  Local<Context> context, Local<Name> key);
3124 
3125  V8_DEPRECATE_SOON("Use maybe version", bool Has(Local<Value> key));
3126  /**
3127  * Object::Has() calls the abstract operation HasProperty(O, P) described
3128  * in ECMA-262, 7.3.10. Has() returns
3129  * true, if the object has the property, either own or on the prototype chain.
3130  * Interceptors, i.e., PropertyQueryCallbacks, are called if present.
3131  *
3132  * Has() has the same side effects as JavaScript's `variable in object`.
3133  * For example, calling Has() on a revoked proxy will throw an exception.
3134  *
3135  * \note Has() converts the key to a name, which possibly calls back into
3136  * JavaScript.
3137  *
3138  * See also v8::Object::HasOwnProperty() and
3139  * v8::Object::HasRealNamedProperty().
3140  */
3141  V8_WARN_UNUSED_RESULT Maybe<bool> Has(Local<Context> context,
3142  Local<Value> key);
3143 
3144  V8_DEPRECATE_SOON("Use maybe version", bool Delete(Local<Value> key));
3145  V8_WARN_UNUSED_RESULT Maybe<bool> Delete(Local<Context> context,
3146  Local<Value> key);
3147 
3148  V8_DEPRECATED("Use maybe version", bool Has(uint32_t index));
3149  V8_WARN_UNUSED_RESULT Maybe<bool> Has(Local<Context> context,
3150  uint32_t index);
3151 
3152  V8_DEPRECATED("Use maybe version", bool Delete(uint32_t index));
3153  V8_WARN_UNUSED_RESULT Maybe<bool> Delete(Local<Context> context,
3154  uint32_t index);
3155 
3156  V8_DEPRECATED("Use maybe version",
3157  bool SetAccessor(Local<String> name,
3158  AccessorGetterCallback getter,
3159  AccessorSetterCallback setter = 0,
3160  Local<Value> data = Local<Value>(),
3161  AccessControl settings = DEFAULT,
3162  PropertyAttribute attribute = None));
3163  V8_DEPRECATED("Use maybe version",
3164  bool SetAccessor(Local<Name> name,
3166  AccessorNameSetterCallback setter = 0,
3167  Local<Value> data = Local<Value>(),
3168  AccessControl settings = DEFAULT,
3169  PropertyAttribute attribute = None));
3170  V8_WARN_UNUSED_RESULT Maybe<bool> SetAccessor(Local<Context> context,
3171  Local<Name> name,
3173  AccessorNameSetterCallback setter = 0,
3174  MaybeLocal<Value> data = MaybeLocal<Value>(),
3175  AccessControl settings = DEFAULT,
3176  PropertyAttribute attribute = None);
3177 
3178  void SetAccessorProperty(Local<Name> name, Local<Function> getter,
3179  Local<Function> setter = Local<Function>(),
3180  PropertyAttribute attribute = None,
3181  AccessControl settings = DEFAULT);
3182 
3183  /**
3184  * Sets a native data property like Template::SetNativeDataProperty, but
3185  * this method sets on this object directly.
3186  */
3188  Local<Context> context, Local<Name> name,
3191  Local<Value> data = Local<Value>(), PropertyAttribute attributes = None);
3192 
3193  /**
3194  * Functionality for private properties.
3195  * This is an experimental feature, use at your own risk.
3196  * Note: Private properties are not inherited. Do not rely on this, since it
3197  * may change.
3198  */
3199  Maybe<bool> HasPrivate(Local<Context> context, Local<Private> key);
3200  Maybe<bool> SetPrivate(Local<Context> context, Local<Private> key,
3201  Local<Value> value);
3202  Maybe<bool> DeletePrivate(Local<Context> context, Local<Private> key);
3203  MaybeLocal<Value> GetPrivate(Local<Context> context, Local<Private> key);
3204 
3205  /**
3206  * Returns an array containing the names of the enumerable properties
3207  * of this object, including properties from prototype objects. The
3208  * array returned by this method contains the same values as would
3209  * be enumerated by a for-in statement over this object.
3210  */
3211  V8_DEPRECATE_SOON("Use maybe version", Local<Array> GetPropertyNames());
3213  Local<Context> context);
3215  Local<Context> context, KeyCollectionMode mode,
3216  PropertyFilter property_filter, IndexFilter index_filter);
3217 
3218  /**
3219  * This function has the same functionality as GetPropertyNames but
3220  * the returned array doesn't contain the names of properties from
3221  * prototype objects.
3222  */
3223  V8_DEPRECATE_SOON("Use maybe version", Local<Array> GetOwnPropertyNames());
3225  Local<Context> context);
3226 
3227  /**
3228  * Returns an array containing the names of the filtered properties
3229  * of this object, including properties from prototype objects. The
3230  * array returned by this method contains the same values as would
3231  * be enumerated by a for-in statement over this object.
3232  */
3234  Local<Context> context, PropertyFilter filter);
3235 
3236  /**
3237  * Get the prototype object. This does not skip objects marked to
3238  * be skipped by __proto__ and it does not consult the security
3239  * handler.
3240  */
3241  Local<Value> GetPrototype();
3242 
3243  /**
3244  * Set the prototype object. This does not skip objects marked to
3245  * be skipped by __proto__ and it does not consult the security
3246  * handler.
3247  */
3248  V8_DEPRECATED("Use maybe version", bool SetPrototype(Local<Value> prototype));
3249  V8_WARN_UNUSED_RESULT Maybe<bool> SetPrototype(Local<Context> context,
3250  Local<Value> prototype);
3251 
3252  /**
3253  * Finds an instance of the given function template in the prototype
3254  * chain.
3255  */
3257 
3258  /**
3259  * Call builtin Object.prototype.toString on this object.
3260  * This is different from Value::ToString() that may call
3261  * user-defined toString function. This one does not.
3262  */
3263  V8_DEPRECATED("Use maybe version", Local<String> ObjectProtoToString());
3265  Local<Context> context);
3266 
3267  /**
3268  * Returns the name of the function invoked as a constructor for this object.
3269  */
3270  Local<String> GetConstructorName();
3271 
3272  /**
3273  * Sets the integrity level of the object.
3274  */
3275  Maybe<bool> SetIntegrityLevel(Local<Context> context, IntegrityLevel level);
3276 
3277  /** Gets the number of internal fields for this Object. */
3278  int InternalFieldCount();
3279 
3280  /** Same as above, but works for Persistents */
3282  const PersistentBase<Object>& object) {
3283  return object.val_->InternalFieldCount();
3284  }
3285 
3286  /** Gets the value from an internal field. */
3287  V8_INLINE Local<Value> GetInternalField(int index);
3288 
3289  /** Sets the value in an internal field. */
3290  void SetInternalField(int index, Local<Value> value);
3291 
3292  /**
3293  * Gets a 2-byte-aligned native pointer from an internal field. This field
3294  * must have been set by SetAlignedPointerInInternalField, everything else
3295  * leads to undefined behavior.
3296  */
3298 
3299  /** Same as above, but works for Persistents */
3301  const PersistentBase<Object>& object, int index) {
3302  return object.val_->GetAlignedPointerFromInternalField(index);
3303  }
3304 
3305  /**
3306  * Sets a 2-byte-aligned native pointer in an internal field. To retrieve such
3307  * a field, GetAlignedPointerFromInternalField must be used, everything else
3308  * leads to undefined behavior.
3309  */
3310  void SetAlignedPointerInInternalField(int index, void* value);
3311  void SetAlignedPointerInInternalFields(int argc, int indices[],
3312  void* values[]);
3313 
3314  // Testers for local properties.
3315  V8_DEPRECATED("Use maybe version", bool HasOwnProperty(Local<String> key));
3316 
3317  /**
3318  * HasOwnProperty() is like JavaScript's Object.prototype.hasOwnProperty().
3319  *
3320  * See also v8::Object::Has() and v8::Object::HasRealNamedProperty().
3321  */
3322  V8_WARN_UNUSED_RESULT Maybe<bool> HasOwnProperty(Local<Context> context,
3323  Local<Name> key);
3324  V8_WARN_UNUSED_RESULT Maybe<bool> HasOwnProperty(Local<Context> context,
3325  uint32_t index);
3326  V8_DEPRECATE_SOON("Use maybe version",
3327  bool HasRealNamedProperty(Local<String> key));
3328  /**
3329  * Use HasRealNamedProperty() if you want to check if an object has an own
3330  * property without causing side effects, i.e., without calling interceptors.
3331  *
3332  * This function is similar to v8::Object::HasOwnProperty(), but it does not
3333  * call interceptors.
3334  *
3335  * \note Consider using non-masking interceptors, i.e., the interceptors are
3336  * not called if the receiver has the real named property. See
3337  * `v8::PropertyHandlerFlags::kNonMasking`.
3338  *
3339  * See also v8::Object::Has().
3340  */
3341  V8_WARN_UNUSED_RESULT Maybe<bool> HasRealNamedProperty(Local<Context> context,
3342  Local<Name> key);
3343  V8_DEPRECATE_SOON("Use maybe version",
3344  bool HasRealIndexedProperty(uint32_t index));
3346  Local<Context> context, uint32_t index);
3347  V8_DEPRECATE_SOON("Use maybe version",
3348  bool HasRealNamedCallbackProperty(Local<String> key));
3350  Local<Context> context, Local<Name> key);
3351 
3352  /**
3353  * If result.IsEmpty() no real property was located in the prototype chain.
3354  * This means interceptors in the prototype chain are not called.
3355  */
3356  V8_DEPRECATED(
3357  "Use maybe version",
3358  Local<Value> GetRealNamedPropertyInPrototypeChain(Local<String> key));
3360  Local<Context> context, Local<Name> key);
3361 
3362  /**
3363  * Gets the property attributes of a real property in the prototype chain,
3364  * which can be None or any combination of ReadOnly, DontEnum and DontDelete.
3365  * Interceptors in the prototype chain are not called.
3366  */
3367  V8_DEPRECATED(
3368  "Use maybe version",
3369  Maybe<PropertyAttribute> GetRealNamedPropertyAttributesInPrototypeChain(
3370  Local<String> key));
3373  Local<Name> key);
3374 
3375  /**
3376  * If result.IsEmpty() no real property was located on the object or
3377  * in the prototype chain.
3378  * This means interceptors in the prototype chain are not called.
3379  */
3380  V8_DEPRECATED("Use maybe version",
3381  Local<Value> GetRealNamedProperty(Local<String> key));
3383  Local<Context> context, Local<Name> key);
3384 
3385  /**
3386  * Gets the property attributes of a real property which can be
3387  * None or any combination of ReadOnly, DontEnum and DontDelete.
3388  * Interceptors in the prototype chain are not called.
3389  */
3390  V8_DEPRECATED("Use maybe version",
3391  Maybe<PropertyAttribute> GetRealNamedPropertyAttributes(
3392  Local<String> key));
3394  Local<Context> context, Local<Name> key);
3395 
3396  /** Tests for a named lookup interceptor.*/
3398 
3399  /** Tests for an index lookup interceptor.*/
3401 
3402  /**
3403  * Returns the identity hash for this object. The current implementation
3404  * uses a hidden property on the object to store the identity hash.
3405  *
3406  * The return value will never be 0. Also, it is not guaranteed to be
3407  * unique.
3408  */
3409  int GetIdentityHash();
3410 
3411  /**
3412  * Clone this object with a fast but shallow copy. Values will point
3413  * to the same values as the original object.
3414  */
3415  // TODO(dcarney): take an isolate and optionally bail out?
3416  Local<Object> Clone();
3417 
3418  /**
3419  * Returns the context in which the object was created.
3420  */
3421  Local<Context> CreationContext();
3422 
3423  /** Same as above, but works for Persistents */
3425  const PersistentBase<Object>& object) {
3426  return object.val_->CreationContext();
3427  }
3428 
3429  /**
3430  * Checks whether a callback is set by the
3431  * ObjectTemplate::SetCallAsFunctionHandler method.
3432  * When an Object is callable this method returns true.
3433  */
3434  bool IsCallable();
3435 
3436  /**
3437  * True if this object is a constructor.
3438  */
3439  bool IsConstructor();
3440 
3441  /**
3442  * Call an Object as a function if a callback is set by the
3443  * ObjectTemplate::SetCallAsFunctionHandler method.
3444  */
3445  V8_DEPRECATED("Use maybe version",
3446  Local<Value> CallAsFunction(Local<Value> recv, int argc,
3447  Local<Value> argv[]));
3448  V8_WARN_UNUSED_RESULT MaybeLocal<Value> CallAsFunction(Local<Context> context,
3449  Local<Value> recv,
3450  int argc,
3451  Local<Value> argv[]);
3452 
3453  /**
3454  * Call an Object as a constructor if a callback is set by the
3455  * ObjectTemplate::SetCallAsFunctionHandler method.
3456  * Note: This method behaves like the Function::NewInstance method.
3457  */
3458  V8_DEPRECATED("Use maybe version",
3459  Local<Value> CallAsConstructor(int argc, Local<Value> argv[]));
3461  Local<Context> context, int argc, Local<Value> argv[]);
3462 
3463  /**
3464  * Return the isolate to which the Object belongs to.
3465  */
3466  V8_DEPRECATE_SOON("Keep track of isolate correctly", Isolate* GetIsolate());
3467 
3468  static Local<Object> New(Isolate* isolate);
3469 
3470  V8_INLINE static Object* Cast(Value* obj);
3471 
3472  private:
3473  Object();
3474  static void CheckCast(Value* obj);
3475  Local<Value> SlowGetInternalField(int index);
3476  void* SlowGetAlignedPointerFromInternalField(int index);
3477 };
3478 
3479 
3480 /**
3481  * An instance of the built-in array constructor (ECMA-262, 15.4.2).
3482  */
3483 class V8_EXPORT Array : public Object {
3484  public:
3485  uint32_t Length() const;
3486 
3487  /**
3488  * Clones an element at index |index|. Returns an empty
3489  * handle if cloning fails (for any reason).
3490  */
3491  V8_DEPRECATED("Cloning is not supported.",
3492  Local<Object> CloneElementAt(uint32_t index));
3493  V8_DEPRECATED("Cloning is not supported.",
3494  MaybeLocal<Object> CloneElementAt(Local<Context> context,
3495  uint32_t index));
3496 
3497  /**
3498  * Creates a JavaScript array with the given length. If the length
3499  * is negative the returned array will have length 0.
3500  */
3501  static Local<Array> New(Isolate* isolate, int length = 0);
3502 
3503  V8_INLINE static Array* Cast(Value* obj);
3504  private:
3505  Array();
3506  static void CheckCast(Value* obj);
3507 };
3508 
3509 
3510 /**
3511  * An instance of the built-in Map constructor (ECMA-262, 6th Edition, 23.1.1).
3512  */
3513 class V8_EXPORT Map : public Object {
3514  public:
3515  size_t Size() const;
3516  void Clear();
3517  V8_WARN_UNUSED_RESULT MaybeLocal<Value> Get(Local<Context> context,
3518  Local<Value> key);
3519  V8_WARN_UNUSED_RESULT MaybeLocal<Map> Set(Local<Context> context,
3520  Local<Value> key,
3521  Local<Value> value);
3522  V8_WARN_UNUSED_RESULT Maybe<bool> Has(Local<Context> context,
3523  Local<Value> key);
3524  V8_WARN_UNUSED_RESULT Maybe<bool> Delete(Local<Context> context,
3525  Local<Value> key);
3526 
3527  /**
3528  * Returns an array of length Size() * 2, where index N is the Nth key and
3529  * index N + 1 is the Nth value.
3530  */
3531  Local<Array> AsArray() const;
3532 
3533  /**
3534  * Creates a new empty Map.
3535  */
3536  static Local<Map> New(Isolate* isolate);
3537 
3538  V8_INLINE static Map* Cast(Value* obj);
3539 
3540  private:
3541  Map();
3542  static void CheckCast(Value* obj);
3543 };
3544 
3545 
3546 /**
3547  * An instance of the built-in Set constructor (ECMA-262, 6th Edition, 23.2.1).
3548  */
3549 class V8_EXPORT Set : public Object {
3550  public:
3551  size_t Size() const;
3552  void Clear();
3553  V8_WARN_UNUSED_RESULT MaybeLocal<Set> Add(Local<Context> context,
3554  Local<Value> key);
3555  V8_WARN_UNUSED_RESULT Maybe<bool> Has(Local<Context> context,
3556  Local<Value> key);
3557  V8_WARN_UNUSED_RESULT Maybe<bool> Delete(Local<Context> context,
3558  Local<Value> key);
3559 
3560  /**
3561  * Returns an array of the keys in this Set.
3562  */
3563  Local<Array> AsArray() const;
3564 
3565  /**
3566  * Creates a new empty Set.
3567  */
3568  static Local<Set> New(Isolate* isolate);
3569 
3570  V8_INLINE static Set* Cast(Value* obj);
3571 
3572  private:
3573  Set();
3574  static void CheckCast(Value* obj);
3575 };
3576 
3577 
3578 template<typename T>
3579 class ReturnValue {
3580  public:
3581  template <class S> V8_INLINE ReturnValue(const ReturnValue<S>& that)
3582  : value_(that.value_) {
3583  TYPE_CHECK(T, S);
3584  }
3585  // Local setters
3586  template <typename S>
3587  V8_INLINE V8_DEPRECATE_SOON("Use Global<> instead",
3588  void Set(const Persistent<S>& handle));
3589  template <typename S>
3590  V8_INLINE void Set(const Global<S>& handle);
3591  template <typename S>
3592  V8_INLINE void Set(const Local<S> handle);
3593  // Fast primitive setters
3594  V8_INLINE void Set(bool value);
3595  V8_INLINE void Set(double i);
3596  V8_INLINE void Set(int32_t i);
3597  V8_INLINE void Set(uint32_t i);
3598  // Fast JS primitive setters
3599  V8_INLINE void SetNull();
3600  V8_INLINE void SetUndefined();
3601  V8_INLINE void SetEmptyString();
3602  // Convenience getter for Isolate
3603  V8_INLINE Isolate* GetIsolate() const;
3604 
3605  // Pointer setter: Uncompilable to prevent inadvertent misuse.
3606  template <typename S>
3607  V8_INLINE void Set(S* whatever);
3608 
3609  // Getter. Creates a new Local<> so it comes with a certain performance
3610  // hit. If the ReturnValue was not yet set, this will return the undefined
3611  // value.
3612  V8_INLINE Local<Value> Get() const;
3613 
3614  private:
3615  template<class F> friend class ReturnValue;
3616  template<class F> friend class FunctionCallbackInfo;
3617  template<class F> friend class PropertyCallbackInfo;
3618  template <class F, class G, class H>
3620  V8_INLINE void SetInternal(internal::Object* value) { *value_ = value; }
3621  V8_INLINE internal::Object* GetDefaultValue();
3622  V8_INLINE explicit ReturnValue(internal::Object** slot);
3623  internal::Object** value_;
3624 };
3625 
3626 
3627 /**
3628  * The argument information given to function call callbacks. This
3629  * class provides access to information about the context of the call,
3630  * including the receiver, the number and values of arguments, and
3631  * the holder of the function.
3632  */
3633 template<typename T>
3634 class FunctionCallbackInfo {
3635  public:
3636  /** The number of available arguments. */
3637  V8_INLINE int Length() const;
3638  /** Accessor for the available arguments. */
3639  V8_INLINE Local<Value> operator[](int i) const;
3640  V8_INLINE V8_DEPRECATED("Use Data() to explicitly pass Callee instead",
3641  Local<Function> Callee() const);
3642  /** Returns the receiver. This corresponds to the "this" value. */
3643  V8_INLINE Local<Object> This() const;
3644  /**
3645  * If the callback was created without a Signature, this is the same
3646  * value as This(). If there is a signature, and the signature didn't match
3647  * This() but one of its hidden prototypes, this will be the respective
3648  * hidden prototype.
3649  *
3650  * Note that this is not the prototype of This() on which the accessor
3651  * referencing this callback was found (which in V8 internally is often
3652  * referred to as holder [sic]).
3653  */
3654  V8_INLINE Local<Object> Holder() const;
3655  /** For construct calls, this returns the "new.target" value. */
3656  V8_INLINE Local<Value> NewTarget() const;
3657  /** Indicates whether this is a regular call or a construct call. */
3658  V8_INLINE bool IsConstructCall() const;
3659  /** The data argument specified when creating the callback. */
3660  V8_INLINE Local<Value> Data() const;
3661  /** The current Isolate. */
3662  V8_INLINE Isolate* GetIsolate() const;
3663  /** The ReturnValue for the call. */
3664  V8_INLINE ReturnValue<T> GetReturnValue() const;
3665  // This shouldn't be public, but the arm compiler needs it.
3666  static const int kArgsLength = 8;
3667 
3668  protected:
3672  static const int kHolderIndex = 0;
3673  static const int kIsolateIndex = 1;
3674  static const int kReturnValueDefaultValueIndex = 2;
3675  static const int kReturnValueIndex = 3;
3676  static const int kDataIndex = 4;
3677  static const int kCalleeIndex = 5;
3678  static const int kContextSaveIndex = 6;
3679  static const int kNewTargetIndex = 7;
3680 
3681  V8_INLINE FunctionCallbackInfo(internal::Object** implicit_args,
3682  internal::Object** values, int length);
3684  internal::Object** values_;
3685  int length_;
3686 };
3687 
3688 
3689 /**
3690  * The information passed to a property callback about the context
3691  * of the property access.
3692  */
3693 template<typename T>
3694 class PropertyCallbackInfo {
3695  public:
3696  /**
3697  * \return The isolate of the property access.
3698  */
3699  V8_INLINE Isolate* GetIsolate() const;
3700 
3701  /**
3702  * \return The data set in the configuration, i.e., in
3703  * `NamedPropertyHandlerConfiguration` or
3704  * `IndexedPropertyHandlerConfiguration.`
3705  */
3706  V8_INLINE Local<Value> Data() const;
3707 
3708  /**
3709  * \return The receiver. In many cases, this is the object on which the
3710  * property access was intercepted. When using
3711  * `Reflect.get`, `Function.prototype.call`, or similar functions, it is the
3712  * object passed in as receiver or thisArg.
3713  *
3714  * \code
3715  * void GetterCallback(Local<Name> name,
3716  * const v8::PropertyCallbackInfo<v8::Value>& info) {
3717  * auto context = info.GetIsolate()->GetCurrentContext();
3718  *
3719  * v8::Local<v8::Value> a_this =
3720  * info.This()
3721  * ->GetRealNamedProperty(context, v8_str("a"))
3722  * .ToLocalChecked();
3723  * v8::Local<v8::Value> a_holder =
3724  * info.Holder()
3725  * ->GetRealNamedProperty(context, v8_str("a"))
3726  * .ToLocalChecked();
3727  *
3728  * CHECK(v8_str("r")->Equals(context, a_this).FromJust());
3729  * CHECK(v8_str("obj")->Equals(context, a_holder).FromJust());
3730  *
3731  * info.GetReturnValue().Set(name);
3732  * }
3733  *
3734  * v8::Local<v8::FunctionTemplate> templ =
3735  * v8::FunctionTemplate::New(isolate);
3736  * templ->InstanceTemplate()->SetHandler(
3737  * v8::NamedPropertyHandlerConfiguration(GetterCallback));
3738  * LocalContext env;
3739  * env->Global()
3740  * ->Set(env.local(), v8_str("obj"), templ->GetFunction(env.local())
3741  * .ToLocalChecked()
3742  * ->NewInstance(env.local())
3743  * .ToLocalChecked())
3744  * .FromJust();
3745  *
3746  * CompileRun("obj.a = 'obj'; var r = {a: 'r'}; Reflect.get(obj, 'x', r)");
3747  * \endcode
3748  */
3749  V8_INLINE Local<Object> This() const;
3750 
3751  /**
3752  * \return The object in the prototype chain of the receiver that has the
3753  * interceptor. Suppose you have `x` and its prototype is `y`, and `y`
3754  * has an interceptor. Then `info.This()` is `x` and `info.Holder()` is `y`.
3755  * The Holder() could be a hidden object (the global object, rather
3756  * than the global proxy).
3757  *
3758  * \note For security reasons, do not pass the object back into the runtime.
3759  */
3760  V8_INLINE Local<Object> Holder() const;
3761 
3762  /**
3763  * \return The return value of the callback.
3764  * Can be changed by calling Set().
3765  * \code
3766  * info.GetReturnValue().Set(...)
3767  * \endcode
3768  *
3769  */
3770  V8_INLINE ReturnValue<T> GetReturnValue() const;
3771 
3772  /**
3773  * \return True if the intercepted function should throw if an error occurs.
3774  * Usually, `true` corresponds to `'use strict'`.
3775  *
3776  * \note Always `false` when intercepting `Reflect.set()`
3777  * independent of the language mode.
3778  */
3779  V8_INLINE bool ShouldThrowOnError() const;
3780 
3781  // This shouldn't be public, but the arm compiler needs it.
3782  static const int kArgsLength = 7;
3783 
3784  protected:
3785  friend class MacroAssembler;
3788  static const int kShouldThrowOnErrorIndex = 0;
3789  static const int kHolderIndex = 1;
3790  static const int kIsolateIndex = 2;
3791  static const int kReturnValueDefaultValueIndex = 3;
3792  static const int kReturnValueIndex = 4;
3793  static const int kDataIndex = 5;
3794  static const int kThisIndex = 6;
3795 
3796  V8_INLINE PropertyCallbackInfo(internal::Object** args) : args_(args) {}
3797  internal::Object** args_;
3798 };
3799 
3800 
3801 typedef void (*FunctionCallback)(const FunctionCallbackInfo<Value>& info);
3802 
3804 
3805 /**
3806  * A JavaScript function object (ECMA-262, 15.3).
3807  */
3808 class V8_EXPORT Function : public Object {
3809  public:
3810  /**
3811  * Create a function in the current execution context
3812  * for a given FunctionCallback.
3813  */
3814  static MaybeLocal<Function> New(
3815  Local<Context> context, FunctionCallback callback,
3816  Local<Value> data = Local<Value>(), int length = 0,
3818  static V8_DEPRECATE_SOON(
3819  "Use maybe version",
3820  Local<Function> New(Isolate* isolate, FunctionCallback callback,
3821  Local<Value> data = Local<Value>(), int length = 0));
3822 
3823  V8_DEPRECATED("Use maybe version",
3824  Local<Object> NewInstance(int argc, Local<Value> argv[]) const);
3826  Local<Context> context, int argc, Local<Value> argv[]) const;
3827 
3828  V8_DEPRECATED("Use maybe version", Local<Object> NewInstance() const);
3830  Local<Context> context) const {
3831  return NewInstance(context, 0, nullptr);
3832  }
3833 
3834  V8_DEPRECATE_SOON("Use maybe version",
3835  Local<Value> Call(Local<Value> recv, int argc,
3836  Local<Value> argv[]));
3837  V8_WARN_UNUSED_RESULT MaybeLocal<Value> Call(Local<Context> context,
3838  Local<Value> recv, int argc,
3839  Local<Value> argv[]);
3840 
3841  void SetName(Local<String> name);
3842  Local<Value> GetName() const;
3843 
3844  /**
3845  * Name inferred from variable or property assignment of this function.
3846  * Used to facilitate debugging and profiling of JavaScript code written
3847  * in an OO style, where many functions are anonymous but are assigned
3848  * to object properties.
3849  */
3850  Local<Value> GetInferredName() const;
3851 
3852  /**
3853  * displayName if it is set, otherwise name if it is configured, otherwise
3854  * function name, otherwise inferred name.
3855  */
3856  Local<Value> GetDebugName() const;
3857 
3858  /**
3859  * User-defined name assigned to the "displayName" property of this function.
3860  * Used to facilitate debugging and profiling of JavaScript code.
3861  */
3862  Local<Value> GetDisplayName() const;
3863 
3864  /**
3865  * Returns zero based line number of function body and
3866  * kLineOffsetNotFound if no information available.
3867  */
3868  int GetScriptLineNumber() const;
3869  /**
3870  * Returns zero based column number of function body and
3871  * kLineOffsetNotFound if no information available.
3872  */
3873  int GetScriptColumnNumber() const;
3874 
3875  /**
3876  * Tells whether this function is builtin.
3877  */
3878  V8_DEPRECATED("this should no longer be used.", bool IsBuiltin() const);
3879 
3880  /**
3881  * Returns scriptId.
3882  */
3883  int ScriptId() const;
3884 
3885  /**
3886  * Returns the original function if this function is bound, else returns
3887  * v8::Undefined.
3888  */
3889  Local<Value> GetBoundFunction() const;
3890 
3891  ScriptOrigin GetScriptOrigin() const;
3892  V8_INLINE static Function* Cast(Value* obj);
3893  static const int kLineOffsetNotFound;
3894 
3895  private:
3896  Function();
3897  static void CheckCast(Value* obj);
3898 };
3899 
3900 #ifndef V8_PROMISE_INTERNAL_FIELD_COUNT
3901 // The number of required internal fields can be defined by embedder.
3902 #define V8_PROMISE_INTERNAL_FIELD_COUNT 0
3903 #endif
3904 
3905 /**
3906  * An instance of the built-in Promise constructor (ES6 draft).
3907  */
3908 class V8_EXPORT Promise : public Object {
3909  public:
3910  /**
3911  * State of the promise. Each value corresponds to one of the possible values
3912  * of the [[PromiseState]] field.
3913  */
3915 
3916  class V8_EXPORT Resolver : public Object {
3917  public:
3918  /**
3919  * Create a new resolver, along with an associated promise in pending state.
3920  */
3921  static V8_DEPRECATE_SOON("Use maybe version",
3922  Local<Resolver> New(Isolate* isolate));
3923  static V8_WARN_UNUSED_RESULT MaybeLocal<Resolver> New(
3924  Local<Context> context);
3925 
3926  /**
3927  * Extract the associated promise.
3928  */
3929  Local<Promise> GetPromise();
3930 
3931  /**
3932  * Resolve/reject the associated promise with a given value.
3933  * Ignored if the promise is no longer pending.
3934  */
3935  V8_DEPRECATE_SOON("Use maybe version", void Resolve(Local<Value> value));
3936  V8_WARN_UNUSED_RESULT Maybe<bool> Resolve(Local<Context> context,
3937  Local<Value> value);
3938 
3939  V8_DEPRECATE_SOON("Use maybe version", void Reject(Local<Value> value));
3940  V8_WARN_UNUSED_RESULT Maybe<bool> Reject(Local<Context> context,
3941  Local<Value> value);
3942 
3943  V8_INLINE static Resolver* Cast(Value* obj);
3944 
3945  private:
3946  Resolver();
3947  static void CheckCast(Value* obj);
3948  };
3949 
3950  /**
3951  * Register a resolution/rejection handler with a promise.
3952  * The handler is given the respective resolution/rejection value as
3953  * an argument. If the promise is already resolved/rejected, the handler is
3954  * invoked at the end of turn.
3955  */
3956  V8_DEPRECATED("Use maybe version",
3957  Local<Promise> Catch(Local<Function> handler));
3958  V8_WARN_UNUSED_RESULT MaybeLocal<Promise> Catch(Local<Context> context,
3959  Local<Function> handler);
3960 
3961  V8_DEPRECATED("Use maybe version",
3962  Local<Promise> Then(Local<Function> handler));
3963  V8_WARN_UNUSED_RESULT MaybeLocal<Promise> Then(Local<Context> context,
3964  Local<Function> handler);
3965 
3966  /**
3967  * Returns true if the promise has at least one derived promise, and
3968  * therefore resolve/reject handlers (including default handler).
3969  */
3970  bool HasHandler();
3971 
3972  /**
3973  * Returns the content of the [[PromiseResult]] field. The Promise must not
3974  * be pending.
3975  */
3976  Local<Value> Result();
3977 
3978  /**
3979  * Returns the value of the [[PromiseState]] field.
3980  */
3981  PromiseState State();
3982 
3983  V8_INLINE static Promise* Cast(Value* obj);
3984 
3986 
3987  private:
3988  Promise();
3989  static void CheckCast(Value* obj);
3990 };
3991 
3992 /**
3993  * An instance of a Property Descriptor, see Ecma-262 6.2.4.
3994  *
3995  * Properties in a descriptor are present or absent. If you do not set
3996  * `enumerable`, `configurable`, and `writable`, they are absent. If `value`,
3997  * `get`, or `set` are absent, but you must specify them in the constructor, use
3998  * empty handles.
3999  *
4000  * Accessors `get` and `set` must be callable or undefined if they are present.
4001  *
4002  * \note Only query properties if they are present, i.e., call `x()` only if
4003  * `has_x()` returns true.
4004  *
4005  * \code
4006  * // var desc = {writable: false}
4007  * v8::PropertyDescriptor d(Local<Value>()), false);
4008  * d.value(); // error, value not set
4009  * if (d.has_writable()) {
4010  * d.writable(); // false
4011  * }
4012  *
4013  * // var desc = {value: undefined}
4014  * v8::PropertyDescriptor d(v8::Undefined(isolate));
4015  *
4016  * // var desc = {get: undefined}
4017  * v8::PropertyDescriptor d(v8::Undefined(isolate), Local<Value>()));
4018  * \endcode
4019  */
4021  public:
4022  // GenericDescriptor
4024 
4025  // DataDescriptor
4026  PropertyDescriptor(Local<Value> value);
4027 
4028  // DataDescriptor with writable property
4029  PropertyDescriptor(Local<Value> value, bool writable);
4030 
4031  // AccessorDescriptor
4032  PropertyDescriptor(Local<Value> get, Local<Value> set);
4033 
4034  ~PropertyDescriptor();
4035 
4036  Local<Value> value() const;
4037  bool has_value() const;
4038 
4039  Local<Value> get() const;
4040  bool has_get() const;
4041  Local<Value> set() const;
4042  bool has_set() const;
4043 
4044  void set_enumerable(bool enumerable);
4045  bool enumerable() const;
4046  bool has_enumerable() const;
4047 
4048  void set_configurable(bool configurable);
4049  bool configurable() const;
4050  bool has_configurable() const;
4051 
4052  bool writable() const;
4053  bool has_writable() const;
4054 
4055  struct PrivateData;
4056  PrivateData* get_private() const { return private_; }
4057 
4058  PropertyDescriptor(const PropertyDescriptor&) = delete;
4059  void operator=(const PropertyDescriptor&) = delete;
4060 
4061  private:
4062  PrivateData* private_;
4063 };
4064 
4065 /**
4066  * An instance of the built-in Proxy constructor (ECMA-262, 6th Edition,
4067  * 26.2.1).
4068  */
4069 class V8_EXPORT Proxy : public Object {
4070  public:
4071  Local<Object> GetTarget();
4072  Local<Value> GetHandler();
4073  bool IsRevoked();
4074  void Revoke();
4075 
4076  /**
4077  * Creates a new Proxy for the target object.
4078  */
4079  static MaybeLocal<Proxy> New(Local<Context> context,
4080  Local<Object> local_target,
4081  Local<Object> local_handler);
4082 
4083  V8_INLINE static Proxy* Cast(Value* obj);
4084 
4085  private:
4086  Proxy();
4087  static void CheckCast(Value* obj);
4088 };
4089 
4090 // TODO(mtrofin): rename WasmCompiledModule to WasmModuleObject, for
4091 // consistency with internal APIs.
4093  public:
4095  // A buffer that is owned by the caller.
4097 
4098  // An opaque, native heap object for transferring wasm modules. It
4099  // supports move semantics, and does not support copy semantics.
4100  class TransferrableModule final {
4101  public:
4102  TransferrableModule(TransferrableModule&& src) = default;
4103  TransferrableModule(const TransferrableModule& src) = delete;
4104 
4105  TransferrableModule& operator=(TransferrableModule&& src) = default;
4106  TransferrableModule& operator=(const TransferrableModule& src) = delete;
4107 
4108  private:
4109  typedef std::pair<std::unique_ptr<const uint8_t[]>, size_t> OwnedBuffer;
4110  friend class WasmCompiledModule;
4111  TransferrableModule(OwnedBuffer&& code, OwnedBuffer&& bytes)
4112  : compiled_code(std::move(code)), wire_bytes(std::move(bytes)) {}
4113 
4114  OwnedBuffer compiled_code = {nullptr, 0};
4115  OwnedBuffer wire_bytes = {nullptr, 0};
4116  };
4117 
4118  // Get an in-memory, non-persistable, and context-independent (meaning,
4119  // suitable for transfer to another Isolate and Context) representation
4120  // of this wasm compiled module.
4121  TransferrableModule GetTransferrableModule();
4122 
4123  // Efficiently re-create a WasmCompiledModule, without recompiling, from
4124  // a TransferrableModule.
4125  static MaybeLocal<WasmCompiledModule> FromTransferrableModule(
4126  Isolate* isolate, const TransferrableModule&);
4127 
4128  // Get the wasm-encoded bytes that were used to compile this module.
4129  Local<String> GetWasmWireBytes();
4130 
4131  // Serialize the compiled module. The serialized data does not include the
4132  // uncompiled bytes.
4134 
4135  // If possible, deserialize the module, otherwise compile it from the provided
4136  // uncompiled bytes.
4137  static MaybeLocal<WasmCompiledModule> DeserializeOrCompile(
4138  Isolate* isolate, const CallerOwnedBuffer& serialized_module,
4139  const CallerOwnedBuffer& wire_bytes);
4140  V8_INLINE static WasmCompiledModule* Cast(Value* obj);
4141 
4142  private:
4143  // TODO(ahaas): please remove the friend once streamed compilation is
4144  // implemented
4146 
4147  static MaybeLocal<WasmCompiledModule> Deserialize(
4148  Isolate* isolate, const CallerOwnedBuffer& serialized_module,
4149  const CallerOwnedBuffer& wire_bytes);
4150  static MaybeLocal<WasmCompiledModule> Compile(Isolate* isolate,
4151  const uint8_t* start,
4152  size_t length);
4153  static CallerOwnedBuffer AsCallerOwned(
4154  const TransferrableModule::OwnedBuffer& buff) {
4155  return {buff.first.get(), buff.second};
4156  }
4157 
4158  WasmCompiledModule();
4159  static void CheckCast(Value* obj);
4160 };
4161 
4162 class V8_EXPORT WasmModuleObjectBuilder final {
4163  public:
4165  // The buffer passed into OnBytesReceived is owned by the caller.
4166  void OnBytesReceived(const uint8_t*, size_t size);
4167  MaybeLocal<WasmCompiledModule> Finish();
4168 
4169  private:
4170  Isolate* isolate_ = nullptr;
4171  // TODO(ahaas): We probably need none of this below here once streamed
4172  // compilation is implemented.
4173  typedef std::pair<std::unique_ptr<const uint8_t[]>, size_t> Buffer;
4174 
4175  // Disable copy semantics *in this implementation*. We can choose to
4176  // relax this, albeit it's not clear why.
4177  WasmModuleObjectBuilder(const WasmModuleObjectBuilder&) = delete;
4178  WasmModuleObjectBuilder(WasmModuleObjectBuilder&&) = default;
4179  WasmModuleObjectBuilder& operator=(const WasmModuleObjectBuilder&) = delete;
4180  WasmModuleObjectBuilder& operator=(WasmModuleObjectBuilder&&) = default;
4181 
4182  std::vector<Buffer> received_buffers_;
4183  size_t total_size_ = 0;
4184 };
4185 
4186 #ifndef V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT
4187 // The number of required internal fields can be defined by embedder.
4188 #define V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT 2
4189 #endif
4190 
4191 
4193 
4194 
4195 /**
4196  * An instance of the built-in ArrayBuffer constructor (ES6 draft 15.13.5).
4197  */
4198 class V8_EXPORT ArrayBuffer : public Object {
4199  public:
4200  /**
4201  * A thread-safe allocator that V8 uses to allocate |ArrayBuffer|'s memory.
4202  * The allocator is a global V8 setting. It has to be set via
4203  * Isolate::CreateParams.
4204  *
4205  * Memory allocated through this allocator by V8 is accounted for as external
4206  * memory by V8. Note that V8 keeps track of the memory for all internalized
4207  * |ArrayBuffer|s. Responsibility for tracking external memory (using
4208  * Isolate::AdjustAmountOfExternalAllocatedMemory) is handed over to the
4209  * embedder upon externalization and taken over upon internalization (creating
4210  * an internalized buffer from an existing buffer).
4211  *
4212  * Note that it is unsafe to call back into V8 from any of the allocator
4213  * functions.
4214  */
4215  class V8_EXPORT Allocator { // NOLINT
4216  public:
4217  virtual ~Allocator() {}
4218 
4219  /**
4220  * Allocate |length| bytes. Return NULL if allocation is not successful.
4221  * Memory should be initialized to zeroes.
4222  */
4223  virtual void* Allocate(size_t length) = 0;
4224 
4225  /**
4226  * Allocate |length| bytes. Return NULL if allocation is not successful.
4227  * Memory does not have to be initialized.
4228  */
4229  virtual void* AllocateUninitialized(size_t length) = 0;
4230 
4231  /**
4232  * Reserved |length| bytes, but do not commit the memory. Must call
4233  * |SetProtection| to make memory accessible.
4234  */
4235  // TODO(eholk): make this pure virtual once blink implements this.
4236  virtual void* Reserve(size_t length);
4237 
4238  /**
4239  * Free the memory block of size |length|, pointed to by |data|.
4240  * That memory is guaranteed to be previously allocated by |Allocate|.
4241  */
4242  virtual void Free(void* data, size_t length) = 0;
4243 
4245 
4246  /**
4247  * Free the memory block of size |length|, pointed to by |data|.
4248  * That memory is guaranteed to be previously allocated by |Allocate| or
4249  * |Reserve|, depending on |mode|.
4250  */
4251  // TODO(eholk): make this pure virtual once blink implements this.
4252  virtual void Free(void* data, size_t length, AllocationMode mode);
4253 
4255 
4256  /**
4257  * Change the protection on a region of memory.
4258  *
4259  * On platforms that make a distinction between reserving and committing
4260  * memory, changing the protection to kReadWrite must also ensure the memory
4261  * is committed.
4262  */
4263  // TODO(eholk): make this pure virtual once blink implements this.
4264  virtual void SetProtection(void* data, size_t length,
4265  Protection protection);
4266 
4267  /**
4268  * malloc/free based convenience allocator.
4269  *
4270  * Caller takes ownership, i.e. the returned object needs to be freed using
4271  * |delete allocator| once it is no longer in use.
4272  */
4273  static Allocator* NewDefaultAllocator();
4274  };
4275 
4276  /**
4277  * The contents of an |ArrayBuffer|. Externalization of |ArrayBuffer|
4278  * returns an instance of this class, populated, with a pointer to data
4279  * and byte length.
4280  *
4281  * The Data pointer of ArrayBuffer::Contents is always allocated with
4282  * Allocator::Allocate that is set via Isolate::CreateParams.
4283  */
4284  class V8_EXPORT Contents { // NOLINT
4285  public:
4287  : data_(nullptr),
4288  byte_length_(0),
4290  allocation_length_(0),
4292 
4293  void* AllocationBase() const { return allocation_base_; }
4294  size_t AllocationLength() const { return allocation_length_; }
4295  Allocator::AllocationMode AllocationMode() const {
4296  return allocation_mode_;
4297  }
4298 
4299  void* Data() const { return data_; }
4300  size_t ByteLength() const { return byte_length_; }
4301 
4302  private:
4303  void* data_;
4304  size_t byte_length_;
4305  void* allocation_base_;
4306  size_t allocation_length_;
4307  Allocator::AllocationMode allocation_mode_;
4308 
4309  friend class ArrayBuffer;
4310  };
4311 
4312 
4313  /**
4314  * Data length in bytes.
4315  */
4316  size_t ByteLength() const;
4317 
4318  /**
4319  * Create a new ArrayBuffer. Allocate |byte_length| bytes.
4320  * Allocated memory will be owned by a created ArrayBuffer and
4321  * will be deallocated when it is garbage-collected,
4322  * unless the object is externalized.
4323  */
4324  static Local<ArrayBuffer> New(Isolate* isolate, size_t byte_length);
4325 
4326  /**
4327  * Create a new ArrayBuffer over an existing memory block.
4328  * The created array buffer is by default immediately in externalized state.
4329  * In externalized state, the memory block will not be reclaimed when a
4330  * created ArrayBuffer is garbage-collected.
4331  * In internalized state, the memory block will be released using
4332  * |Allocator::Free| once all ArrayBuffers referencing it are collected by
4333  * the garbage collector.
4334  */
4335  static Local<ArrayBuffer> New(
4336  Isolate* isolate, void* data, size_t byte_length,
4338 
4339  /**
4340  * Returns true if ArrayBuffer is externalized, that is, does not
4341  * own its memory block.
4342  */
4343  bool IsExternal() const;
4344 
4345  /**
4346  * Returns true if this ArrayBuffer may be neutered.
4347  */
4348  bool IsNeuterable() const;
4349 
4350  /**
4351  * Neuters this ArrayBuffer and all its views (typed arrays).
4352  * Neutering sets the byte length of the buffer and all typed arrays to zero,
4353  * preventing JavaScript from ever accessing underlying backing store.
4354  * ArrayBuffer should have been externalized and must be neuterable.
4355  */
4356  void Neuter();
4357 
4358  /**
4359  * Make this ArrayBuffer external. The pointer to underlying memory block
4360  * and byte length are returned as |Contents| structure. After ArrayBuffer
4361  * had been externalized, it does no longer own the memory block. The caller
4362  * should take steps to free memory when it is no longer needed.
4363  *
4364  * The memory block is guaranteed to be allocated with |Allocator::Allocate|
4365  * that has been set via Isolate::CreateParams.
4366  */
4368 
4369  /**
4370  * Get a pointer to the ArrayBuffer's underlying memory block without
4371  * externalizing it. If the ArrayBuffer is not externalized, this pointer
4372  * will become invalid as soon as the ArrayBuffer gets garbage collected.
4373  *
4374  * The embedder should make sure to hold a strong reference to the
4375  * ArrayBuffer while accessing this pointer.
4376  *
4377  * The memory block is guaranteed to be allocated with |Allocator::Allocate|.
4378  */
4380 
4381  V8_INLINE static ArrayBuffer* Cast(Value* obj);
4382 
4385 
4386  private:
4387  ArrayBuffer();
4388  static void CheckCast(Value* obj);
4389 };
4390 
4391 
4392 #ifndef V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT
4393 // The number of required internal fields can be defined by embedder.
4394 #define V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT 2
4395 #endif
4396 
4397 
4398 /**
4399  * A base class for an instance of one of "views" over ArrayBuffer,
4400  * including TypedArrays and DataView (ES6 draft 15.13).
4401  */
4403  public:
4404  /**
4405  * Returns underlying ArrayBuffer.
4406  */
4407  Local<ArrayBuffer> Buffer();
4408  /**
4409  * Byte offset in |Buffer|.
4410  */
4411  size_t ByteOffset();
4412  /**
4413  * Size of a view in bytes.
4414  */
4415  size_t ByteLength();
4416 
4417  /**
4418  * Copy the contents of the ArrayBufferView's buffer to an embedder defined
4419  * memory without additional overhead that calling ArrayBufferView::Buffer
4420  * might incur.
4421  *
4422  * Will write at most min(|byte_length|, ByteLength) bytes starting at
4423  * ByteOffset of the underlying buffer to the memory starting at |dest|.
4424  * Returns the number of bytes actually written.
4425  */
4427 
4428  /**
4429  * Returns true if ArrayBufferView's backing ArrayBuffer has already been
4430  * allocated.
4431  */
4432  bool HasBuffer() const;
4433 
4434  V8_INLINE static ArrayBufferView* Cast(Value* obj);
4435 
4436  static const int kInternalFieldCount =
4438  static const int kEmbedderFieldCount =
4440 
4441  private:
4442  ArrayBufferView();
4443  static void CheckCast(Value* obj);
4444 };
4445 
4446 
4447 /**
4448  * A base class for an instance of TypedArray series of constructors
4449  * (ES6 draft 15.13.6).
4450  */
4452  public:
4453  /**
4454  * Number of elements in this typed array
4455  * (e.g. for Int16Array, |ByteLength|/2).
4456  */
4457  size_t Length();
4458 
4459  V8_INLINE static TypedArray* Cast(Value* obj);
4460 
4461  private:
4462  TypedArray();
4463  static void CheckCast(Value* obj);
4464 };
4465 
4466 
4467 /**
4468  * An instance of Uint8Array constructor (ES6 draft 15.13.6).
4469  */
4471  public:
4472  static Local<Uint8Array> New(Local<ArrayBuffer> array_buffer,
4473  size_t byte_offset, size_t length);
4474  static Local<Uint8Array> New(Local<SharedArrayBuffer> shared_array_buffer,
4475  size_t byte_offset, size_t length);
4476  V8_INLINE static Uint8Array* Cast(Value* obj);
4477 
4478  private:
4479  Uint8Array();
4480  static void CheckCast(Value* obj);
4481 };
4482 
4483 
4484 /**
4485  * An instance of Uint8ClampedArray constructor (ES6 draft 15.13.6).
4486  */
4488  public:
4489  static Local<Uint8ClampedArray> New(Local<ArrayBuffer> array_buffer,
4490  size_t byte_offset, size_t length);
4491  static Local<Uint8ClampedArray> New(
4492  Local<SharedArrayBuffer> shared_array_buffer, size_t byte_offset,
4493  size_t length);
4494  V8_INLINE static Uint8ClampedArray* Cast(Value* obj);
4495 
4496  private:
4497  Uint8ClampedArray();
4498  static void CheckCast(Value* obj);
4499 };
4500 
4501 /**
4502  * An instance of Int8Array constructor (ES6 draft 15.13.6).
4503  */
4505  public:
4506  static Local<Int8Array> New(Local<ArrayBuffer> array_buffer,
4507  size_t byte_offset, size_t length);
4508  static Local<Int8Array> New(Local<SharedArrayBuffer> shared_array_buffer,
4509  size_t byte_offset, size_t length);
4510  V8_INLINE static Int8Array* Cast(Value* obj);
4511 
4512  private:
4513  Int8Array();
4514  static void CheckCast(Value* obj);
4515 };
4516 
4517 
4518 /**
4519  * An instance of Uint16Array constructor (ES6 draft 15.13.6).
4520  */
4522  public:
4523  static Local<Uint16Array> New(Local<ArrayBuffer> array_buffer,
4524  size_t byte_offset, size_t length);
4525  static Local<Uint16Array> New(Local<SharedArrayBuffer> shared_array_buffer,
4526  size_t byte_offset, size_t length);
4527  V8_INLINE static Uint16Array* Cast(Value* obj);
4528 
4529  private:
4530  Uint16Array();
4531  static void CheckCast(Value* obj);
4532 };
4533 
4534 
4535 /**
4536  * An instance of Int16Array constructor (ES6 draft 15.13.6).
4537  */
4539  public:
4540  static Local<Int16Array> New(Local<ArrayBuffer> array_buffer,
4541  size_t byte_offset, size_t length);
4542  static Local<Int16Array> New(Local<SharedArrayBuffer> shared_array_buffer,
4543  size_t byte_offset, size_t length);
4544  V8_INLINE static Int16Array* Cast(Value* obj);
4545 
4546  private:
4547  Int16Array();
4548  static void CheckCast(Value* obj);
4549 };
4550 
4551 
4552 /**
4553  * An instance of Uint32Array constructor (ES6 draft 15.13.6).
4554  */
4556  public:
4557  static Local<Uint32Array> New(Local<ArrayBuffer> array_buffer,
4558  size_t byte_offset, size_t length);
4559  static Local<Uint32Array> New(Local<SharedArrayBuffer> shared_array_buffer,
4560  size_t byte_offset, size_t length);
4561  V8_INLINE static Uint32Array* Cast(Value* obj);
4562 
4563  private:
4564  Uint32Array();
4565  static void CheckCast(Value* obj);
4566 };
4567 
4568 
4569 /**
4570  * An instance of Int32Array constructor (ES6 draft 15.13.6).
4571  */
4573  public:
4574  static Local<Int32Array> New(Local<ArrayBuffer> array_buffer,
4575  size_t byte_offset, size_t length);
4576  static Local<Int32Array> New(Local<SharedArrayBuffer> shared_array_buffer,
4577  size_t byte_offset, size_t length);
4578  V8_INLINE static Int32Array* Cast(Value* obj);
4579 
4580  private:
4581  Int32Array();
4582  static void CheckCast(Value* obj);
4583 };
4584 
4585 
4586 /**
4587  * An instance of Float32Array constructor (ES6 draft 15.13.6).
4588  */
4590  public:
4591  static Local<Float32Array> New(Local<ArrayBuffer> array_buffer,
4592  size_t byte_offset, size_t length);
4593  static Local<Float32Array> New(Local<SharedArrayBuffer> shared_array_buffer,
4594  size_t byte_offset, size_t length);
4595  V8_INLINE static Float32Array* Cast(Value* obj);
4596 
4597  private:
4598  Float32Array();
4599  static void CheckCast(Value* obj);
4600 };
4601 
4602 
4603 /**
4604  * An instance of Float64Array constructor (ES6 draft 15.13.6).
4605  */
4607  public:
4608  static Local<Float64Array> New(Local<ArrayBuffer> array_buffer,
4609  size_t byte_offset, size_t length);
4610  static Local<Float64Array> New(Local<SharedArrayBuffer> shared_array_buffer,
4611  size_t byte_offset, size_t length);
4612  V8_INLINE static Float64Array* Cast(Value* obj);
4613 
4614  private:
4615  Float64Array();
4616  static void CheckCast(Value* obj);
4617 };
4618 
4619 
4620 /**
4621  * An instance of DataView constructor (ES6 draft 15.13.7).
4622  */
4624  public:
4625  static Local<DataView> New(Local<ArrayBuffer> array_buffer,
4626  size_t byte_offset, size_t length);
4627  static Local<DataView> New(Local<SharedArrayBuffer> shared_array_buffer,
4628  size_t byte_offset, size_t length);
4629  V8_INLINE static DataView* Cast(Value* obj);
4630 
4631  private:
4632  DataView();
4633  static void CheckCast(Value* obj);
4634 };
4635 
4636 
4637 /**
4638  * An instance of the built-in SharedArrayBuffer constructor.
4639  * This API is experimental and may change significantly.
4640  */
4642  public:
4643  /**
4644  * The contents of an |SharedArrayBuffer|. Externalization of
4645  * |SharedArrayBuffer| returns an instance of this class, populated, with a
4646  * pointer to data and byte length.
4647  *
4648  * The Data pointer of SharedArrayBuffer::Contents is always allocated with
4649  * |ArrayBuffer::Allocator::Allocate| by the allocator specified in
4650  * v8::Isolate::CreateParams::array_buffer_allocator.
4651  *
4652  * This API is experimental and may change significantly.
4653  */
4654  class V8_EXPORT Contents { // NOLINT
4655  public:
4657  : data_(nullptr),
4658  byte_length_(0),
4660  allocation_length_(0),
4662 
4663  void* AllocationBase() const { return allocation_base_; }
4664  size_t AllocationLength() const { return allocation_length_; }
4665  ArrayBuffer::Allocator::AllocationMode AllocationMode() const {
4666  return allocation_mode_;
4667  }
4668 
4669  void* Data() const { return data_; }
4670  size_t ByteLength() const { return byte_length_; }
4671 
4672  private:
4673  void* data_;
4674  size_t byte_length_;
4675  void* allocation_base_;
4676  size_t allocation_length_;
4677  ArrayBuffer::Allocator::AllocationMode allocation_mode_;
4678 
4679  friend class SharedArrayBuffer;
4680  };
4681 
4682 
4683  /**
4684  * Data length in bytes.
4685  */
4686  size_t ByteLength() const;
4687 
4688  /**
4689  * Create a new SharedArrayBuffer. Allocate |byte_length| bytes.
4690  * Allocated memory will be owned by a created SharedArrayBuffer and
4691  * will be deallocated when it is garbage-collected,
4692  * unless the object is externalized.
4693  */
4694  static Local<SharedArrayBuffer> New(Isolate* isolate, size_t byte_length);
4695 
4696  /**
4697  * Create a new SharedArrayBuffer over an existing memory block. The created
4698  * array buffer is immediately in externalized state unless otherwise
4699  * specified. The memory block will not be reclaimed when a created
4700  * SharedArrayBuffer is garbage-collected.
4701  */
4702  static Local<SharedArrayBuffer> New(
4703  Isolate* isolate, void* data, size_t byte_length,
4705 
4706  /**
4707  * Returns true if SharedArrayBuffer is externalized, that is, does not
4708  * own its memory block.
4709  */
4710  bool IsExternal() const;
4711 
4712  /**
4713  * Make this SharedArrayBuffer external. The pointer to underlying memory
4714  * block and byte length are returned as |Contents| structure. After
4715  * SharedArrayBuffer had been externalized, it does no longer own the memory
4716  * block. The caller should take steps to free memory when it is no longer
4717  * needed.
4718  *
4719  * The memory block is guaranteed to be allocated with |Allocator::Allocate|
4720  * by the allocator specified in
4721  * v8::Isolate::CreateParams::array_buffer_allocator.
4722  *
4723  */
4725 
4726  /**
4727  * Get a pointer to the ArrayBuffer's underlying memory block without
4728  * externalizing it. If the ArrayBuffer is not externalized, this pointer
4729  * will become invalid as soon as the ArrayBuffer became garbage collected.
4730  *
4731  * The embedder should make sure to hold a strong reference to the
4732  * ArrayBuffer while accessing this pointer.
4733  *
4734  * The memory block is guaranteed to be allocated with |Allocator::Allocate|
4735  * by the allocator specified in
4736  * v8::Isolate::CreateParams::array_buffer_allocator.
4737  */
4739 
4740  V8_INLINE static SharedArrayBuffer* Cast(Value* obj);
4741 
4743 
4744  private:
4745  SharedArrayBuffer();
4746  static void CheckCast(Value* obj);
4747 };
4748 
4749 
4750 /**
4751  * An instance of the built-in Date constructor (ECMA-262, 15.9).
4752  */
4753 class V8_EXPORT Date : public Object {
4754  public:
4755  static V8_DEPRECATE_SOON("Use maybe version.",
4756  Local<Value> New(Isolate* isolate, double time));
4757  static V8_WARN_UNUSED_RESULT MaybeLocal<Value> New(Local<Context> context,
4758  double time);
4759 
4760  /**
4761  * A specialization of Value::NumberValue that is more efficient
4762  * because we know the structure of this object.
4763  */
4764  double ValueOf() const;
4765 
4766  V8_INLINE static Date* Cast(Value* obj);
4767 
4768  /**
4769  * Notification that the embedder has changed the time zone,
4770  * daylight savings time, or other date / time configuration
4771  * parameters. V8 keeps a cache of various values used for
4772  * date / time computation. This notification will reset
4773  * those cached values for the current context so that date /
4774  * time configuration changes would be reflected in the Date
4775  * object.
4776  *
4777  * This API should not be called more than needed as it will
4778  * negatively impact the performance of date operations.
4779  */
4780  static void DateTimeConfigurationChangeNotification(Isolate* isolate);
4781 
4782  private:
4783  static void CheckCast(Value* obj);
4784 };
4785 
4786 
4787 /**
4788  * A Number object (ECMA-262, 4.3.21).
4789  */
4791  public:
4792  static Local<Value> New(Isolate* isolate, double value);
4793 
4794  double ValueOf() const;
4795 
4796  V8_INLINE static NumberObject* Cast(Value* obj);
4797 
4798  private:
4799  static void CheckCast(Value* obj);
4800 };
4801 
4802 
4803 /**
4804  * A Boolean object (ECMA-262, 4.3.15).
4805  */
4807  public:
4808  static Local<Value> New(Isolate* isolate, bool value);
4809  V8_DEPRECATED("Pass an isolate", static Local<Value> New(bool value));
4810 
4811  bool ValueOf() const;
4812 
4813  V8_INLINE static BooleanObject* Cast(Value* obj);
4814 
4815  private:
4816  static void CheckCast(Value* obj);
4817 };
4818 
4819 
4820 /**
4821  * A String object (ECMA-262, 4.3.18).
4822  */
4824  public:
4825  static Local<Value> New(Local<String> value);
4826 
4827  Local<String> ValueOf() const;
4828 
4829  V8_INLINE static StringObject* Cast(Value* obj);
4830 
4831  private:
4832  static void CheckCast(Value* obj);
4833 };
4834 
4835 
4836 /**
4837  * A Symbol object (ECMA-262 edition 6).
4838  */
4840  public:
4841  static Local<Value> New(Isolate* isolate, Local<Symbol> value);
4842 
4843  Local<Symbol> ValueOf() const;
4844 
4845  V8_INLINE static SymbolObject* Cast(Value* obj);
4846 
4847  private:
4848  static void CheckCast(Value* obj);
4849 };
4850 
4851 
4852 /**
4853  * An instance of the built-in RegExp constructor (ECMA-262, 15.10).
4854  */
4855 class V8_EXPORT RegExp : public Object {
4856  public:
4857  /**
4858  * Regular expression flag bits. They can be or'ed to enable a set
4859  * of flags.
4860  */
4861  enum Flags {
4862  kNone = 0,
4863  kGlobal = 1 << 0,
4864  kIgnoreCase = 1 << 1,
4865  kMultiline = 1 << 2,
4866  kSticky = 1 << 3,
4867  kUnicode = 1 << 4,
4868  kDotAll = 1 << 5,
4869  };
4870 
4871  /**
4872  * Creates a regular expression from the given pattern string and
4873  * the flags bit field. May throw a JavaScript exception as
4874  * described in ECMA-262, 15.10.4.1.
4875  *
4876  * For example,
4877  * RegExp::New(v8::String::New("foo"),
4878  * static_cast<RegExp::Flags>(kGlobal | kMultiline))
4879  * is equivalent to evaluating "/foo/gm".
4880  */
4881  static V8_DEPRECATE_SOON("Use maybe version",
4882  Local<RegExp> New(Local<String> pattern,
4883  Flags flags));
4884  static V8_WARN_UNUSED_RESULT MaybeLocal<RegExp> New(Local<Context> context,
4885  Local<String> pattern,
4886  Flags flags);
4887 
4888  /**
4889  * Returns the value of the source property: a string representing
4890  * the regular expression.
4891  */
4892  Local<String> GetSource() const;
4893 
4894  /**
4895  * Returns the flags bit field.
4896  */
4897  Flags GetFlags() const;
4898 
4899  V8_INLINE static RegExp* Cast(Value* obj);
4900 
4901  private:
4902  static void CheckCast(Value* obj);
4903 };
4904 
4905 
4906 /**
4907  * A JavaScript value that wraps a C++ void*. This type of value is mainly used
4908  * to associate C++ data structures with JavaScript objects.
4909  */
4910 class V8_EXPORT External : public Value {
4911  public:
4912  static Local<External> New(Isolate* isolate, void* value);
4913  V8_INLINE static External* Cast(Value* obj);
4914  void* Value() const;
4915  private:
4916  static void CheckCast(v8::Value* obj);
4917 };
4918 
4919 #define V8_INTRINSICS_LIST(F)
4920  F(ArrayProto_entries, array_entries_iterator)
4921  F(ArrayProto_forEach, array_for_each_iterator)
4922  F(ArrayProto_keys, array_keys_iterator)
4923  F(ArrayProto_values, array_values_iterator)
4924  F(ErrorPrototype, initial_error_prototype)
4925  F(IteratorPrototype, initial_iterator_prototype)
4926 
4928 #define V8_DECL_INTRINSIC(name, iname) k##name,
4930 #undef V8_DECL_INTRINSIC
4931 };
4932 
4933 
4934 // --- Templates ---
4935 
4936 
4937 /**
4938  * The superclass of object and function templates.
4939  */
4940 class V8_EXPORT Template : public Data {
4941  public:
4942  /**
4943  * Adds a property to each instance created by this template.
4944  *
4945  * The property must be defined either as a primitive value, or a template.
4946  */
4947  void Set(Local<Name> name, Local<Data> value,
4948  PropertyAttribute attributes = None);
4949  void SetPrivate(Local<Private> name, Local<Data> value,
4950  PropertyAttribute attributes = None);
4951  V8_INLINE void Set(Isolate* isolate, const char* name, Local<Data> value);
4952 
4953  void SetAccessorProperty(
4954  Local<Name> name,
4955  Local<FunctionTemplate> getter = Local<FunctionTemplate>(),
4956  Local<FunctionTemplate> setter = Local<FunctionTemplate>(),
4957  PropertyAttribute attribute = None,
4958  AccessControl settings = DEFAULT);
4959 
4960  /**
4961  * Whenever the property with the given name is accessed on objects
4962  * created from this Template the getter and setter callbacks
4963  * are called instead of getting and setting the property directly
4964  * on the JavaScript object.
4965  *
4966  * \param name The name of the property for which an accessor is added.
4967  * \param getter The callback to invoke when getting the property.
4968  * \param setter The callback to invoke when setting the property.
4969  * \param data A piece of data that will be passed to the getter and setter
4970  * callbacks whenever they are invoked.
4971  * \param settings Access control settings for the accessor. This is a bit
4972  * field consisting of one of more of
4973  * DEFAULT = 0, ALL_CAN_READ = 1, or ALL_CAN_WRITE = 2.
4974  * The default is to not allow cross-context access.
4975  * ALL_CAN_READ means that all cross-context reads are allowed.
4976  * ALL_CAN_WRITE means that all cross-context writes are allowed.
4977  * The combination ALL_CAN_READ | ALL_CAN_WRITE can be used to allow all
4978  * cross-context access.
4979  * \param attribute The attributes of the property for which an accessor
4980  * is added.
4981  * \param signature The signature describes valid receivers for the accessor
4982  * and is used to perform implicit instance checks against them. If the
4983  * receiver is incompatible (i.e. is not an instance of the constructor as
4984  * defined by FunctionTemplate::HasInstance()), an implicit TypeError is
4985  * thrown and no callback is invoked.
4986  */
4987  void SetNativeDataProperty(
4988  Local<String> name, AccessorGetterCallback getter,
4989  AccessorSetterCallback setter = 0,
4990  // TODO(dcarney): gcc can't handle Local below
4991  Local<Value> data = Local<Value>(), PropertyAttribute attribute = None,
4992  Local<AccessorSignature> signature = Local<AccessorSignature>(),
4993  AccessControl settings = DEFAULT);
4994  void SetNativeDataProperty(
4995  Local<Name> name, AccessorNameGetterCallback getter,
4996  AccessorNameSetterCallback setter = 0,
4997  // TODO(dcarney): gcc can't handle Local below
4998  Local<Value> data = Local<Value>(), PropertyAttribute attribute = None,
4999  Local<AccessorSignature> signature = Local<AccessorSignature>(),
5000  AccessControl settings = DEFAULT);
5001 
5002  /**
5003  * Like SetNativeDataProperty, but V8 will replace the native data property
5004  * with a real data property on first access.
5005  */
5006  void SetLazyDataProperty(Local<Name> name, AccessorNameGetterCallback getter,
5007  Local<Value> data = Local<Value>(),
5008  PropertyAttribute attribute = None);
5009 
5010  /**
5011  * During template instantiation, sets the value with the intrinsic property
5012  * from the correct context.
5013  */
5014  void SetIntrinsicDataProperty(Local<Name> name, Intrinsic intrinsic,
5015  PropertyAttribute attribute = None);
5016 
5017  private:
5018  Template();
5019 
5020  friend class ObjectTemplate;
5021  friend class FunctionTemplate;
5022 };
5023 
5024 
5025 /**
5026  * NamedProperty[Getter|Setter] are used as interceptors on object.
5027  * See ObjectTemplate::SetNamedPropertyHandler.
5028  */
5030  Local<String> property,
5031  const PropertyCallbackInfo<Value>& info);
5032 
5033 
5034 /**
5035  * Returns the value if the setter intercepts the request.
5036  * Otherwise, returns an empty handle.
5037  */
5039  Local<String> property,
5040  Local<Value> value,
5041  const PropertyCallbackInfo<Value>& info);
5042 
5043 
5044 /**
5045  * Returns a non-empty handle if the interceptor intercepts the request.
5046  * The result is an integer encoding property attributes (like v8::None,
5047  * v8::DontEnum, etc.)
5048  */
5050  Local<String> property,
5051  const PropertyCallbackInfo<Integer>& info);
5052 
5053 
5054 /**
5055  * Returns a non-empty handle if the deleter intercepts the request.
5056  * The return value is true if the property could be deleted and false
5057  * otherwise.
5058  */
5060  Local<String> property,
5061  const PropertyCallbackInfo<Boolean>& info);
5062 
5063 
5064 /**
5065  * Returns an array containing the names of the properties the named
5066  * property getter intercepts.
5067  */
5069  const PropertyCallbackInfo<Array>& info);
5070 
5071 
5072 // TODO(dcarney): Deprecate and remove previous typedefs, and replace
5073 // GenericNamedPropertyFooCallback with just NamedPropertyFooCallback.
5074 
5075 /**
5076  * Interceptor for get requests on an object.
5077  *
5078  * Use `info.GetReturnValue().Set()` to set the return value of the
5079  * intercepted get request.
5080  *
5081  * \param property The name of the property for which the request was
5082  * intercepted.
5083  * \param info Information about the intercepted request, such as
5084  * isolate, receiver, return value, or whether running in `'use strict`' mode.
5085  * See `PropertyCallbackInfo`.
5086  *
5087  * \code
5088  * void GetterCallback(
5089  * Local<Name> name,
5090  * const v8::PropertyCallbackInfo<v8::Value>& info) {
5091  * info.GetReturnValue().Set(v8_num(42));
5092  * }
5093  *
5094  * v8::Local<v8::FunctionTemplate> templ =
5095  * v8::FunctionTemplate::New(isolate);
5096  * templ->InstanceTemplate()->SetHandler(
5097  * v8::NamedPropertyHandlerConfiguration(GetterCallback));
5098  * LocalContext env;
5099  * env->Global()
5100  * ->Set(env.local(), v8_str("obj"), templ->GetFunction(env.local())
5101  * .ToLocalChecked()
5102  *