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