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.
5 /** \mainpage V8 API Reference Guide
7 * V8 is Google's open source JavaScript engine.
9 * This set of documents provides reference material generated from the
10 * V8 header file, include/v8.h.
12 * For other documentation see http://code.google.com/apis/v8/
22 #include "v8-version.h" // NOLINT(build/include)
23 #include "v8config.h" // NOLINT(build/include)
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.
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
40 #ifdef BUILDING_V8_SHARED
41 # define V8_EXPORT __declspec(dllexport)
43 # define V8_EXPORT __declspec(dllimport)
46 #endif // BUILDING_V8_SHARED
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")))
64 * The v8 JavaScript engine.
68 class AccessorSignature;
78 class FunctionTemplate;
80 class ImplementationUtilities;
90 class ObjectOperationDescriptor;
95 class RawOperationDescriptor;
97 class SharedArrayBuffer;
109 template <class T> class Local;
112 template <class T> class Eternal;
113 template<class T> class NonCopyablePersistentTraits;
114 template<class T> class PersistentBase;
115 template <class T, class M = NonCopyablePersistentTraits<T> >
119 template<class K, class V, class T> class PersistentValueMap;
120 template <class K, class V, class T>
121 class PersistentValueMapBase;
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;
129 template<typename T> class FunctionCallbackInfo;
130 template<typename T> class PropertyCallbackInfo;
134 class CallHandlerHelper;
135 class EscapableHandleScope;
136 template<typename T> class ReturnValue;
144 struct StreamedSource;
145 template<typename T> class CustomArguments;
146 class PropertyCallbackArguments;
147 class FunctionCallbackArguments;
149 } // namespace internal
153 * General purpose unique identifier.
157 explicit UniqueId(intptr_t data)
160 bool operator==(const UniqueId& other) const {
161 return data_ == other.data_;
164 bool operator!=(const UniqueId& other) const {
165 return data_ != other.data_;
168 bool operator<(const UniqueId& other) const {
169 return data_ < other.data_;
178 #define TYPE_CHECK(T, S) \
180 *(static_cast<T* volatile*>(0)) = static_cast<S*>(0); \
185 * An object reference managed by the v8 garbage collector.
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.
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
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
212 V8_INLINE Local() : val_(0) {}
214 V8_INLINE Local(Local<S> that)
215 : val_(reinterpret_cast<T*>(*that)) {
217 * This check fails when trying to convert between incompatible
218 * handles. For example, converting from a Local<String> to a
225 * Returns true if the handle is empty.
227 V8_INLINE bool IsEmpty() const { return val_ == 0; }
230 * Sets the handle to be empty. IsEmpty() will then return true.
232 V8_INLINE void Clear() { val_ = 0; }
234 V8_INLINE T* operator->() const { return val_; }
236 V8_INLINE T* operator*() const { return val_; }
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.
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;
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;
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.
269 V8_INLINE bool operator!=(const Local<S>& that) const {
270 return !operator==(that);
273 template <class S> V8_INLINE bool operator!=(
274 const Persistent<S>& that) const {
275 return !operator==(that);
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>();
284 return Local<T>(T::Cast(*that));
288 template <class S> V8_INLINE Local<S> As() {
289 return Local<S>::Cast(*this);
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.
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);
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;
308 friend class MaybeLocal;
309 template<class F> friend class FunctionCallbackInfo;
310 template<class F> friend class PropertyCallbackInfo;
313 friend class Context;
314 template<class F> friend class internal::CustomArguments;
315 friend Local<Primitive> Undefined(Isolate* isolate);
316 friend Local<Primitive> Null(Isolate* isolate);
317 friend Local<Boolean> True(Isolate* isolate);
318 friend Local<Boolean> False(Isolate* isolate);
319 friend class HandleScope;
320 friend class EscapableHandleScope;
321 template <class F1, class F2, class F3>
322 friend class PersistentValueMapBase;
323 template<class F1, class F2> friend class PersistentValueVector;
326 V8_INLINE Local(S* that)
328 V8_INLINE static Local<T> New(Isolate* isolate, T* that);
333 #if !defined(V8_IMMINENT_DEPRECATION_WARNINGS)
334 // Local is an alias for Local for historical reasons.
336 using Handle = Local<T>;
341 * A MaybeLocal<> is a wrapper around Local<> that enforces a check whether
342 * the Local<> is empty before it can be used.
344 * If an API method returns a MaybeLocal<>, the API method can potentially fail
345 * either because an exception is thrown, or because an exception is pending,
346 * e.g. because a previous API call threw an exception that hasn't been caught
347 * yet, or because a TerminateExecution exception was thrown. In that case, an
348 * empty MaybeLocal is returned.
353 V8_INLINE MaybeLocal() : val_(nullptr) {}
355 V8_INLINE MaybeLocal(Local<S> that)
356 : val_(reinterpret_cast<T*>(*that)) {
360 V8_INLINE bool IsEmpty() const { return val_ == nullptr; }
363 V8_WARN_UNUSED_RESULT V8_INLINE bool ToLocal(Local<S>* out) const {
364 out->val_ = IsEmpty() ? nullptr : this->val_;
368 // Will crash if the MaybeLocal<> is empty.
369 V8_INLINE Local<T> ToLocalChecked();
372 V8_INLINE Local<S> FromMaybe(Local<S> default_value) const {
373 return IsEmpty() ? default_value : Local<S>(val_);
381 // Eternal handles are set-once handles that live for the life of the isolate.
382 template <class T> class Eternal {
384 V8_INLINE Eternal() : index_(kInitialValue) { }
386 V8_INLINE Eternal(Isolate* isolate, Local<S> handle) : index_(kInitialValue) {
387 Set(isolate, handle);
389 // Can only be safely called if already set.
390 V8_INLINE Local<T> Get(Isolate* isolate);
391 V8_INLINE bool IsEmpty() { return index_ == kInitialValue; }
392 template<class S> V8_INLINE void Set(Isolate* isolate, Local<S> handle);
395 static const int kInitialValue = -1;
400 static const int kInternalFieldsInWeakCallback = 2;
403 template <typename T>
404 class WeakCallbackInfo {
406 typedef void (*Callback)(const WeakCallbackInfo<T>& data);
408 WeakCallbackInfo(Isolate* isolate, T* parameter,
409 void* internal_fields[kInternalFieldsInWeakCallback],
411 : isolate_(isolate), parameter_(parameter), callback_(callback) {
412 for (int i = 0; i < kInternalFieldsInWeakCallback; ++i) {
413 internal_fields_[i] = internal_fields[i];
417 V8_INLINE Isolate* GetIsolate() const { return isolate_; }
418 V8_INLINE T* GetParameter() const { return parameter_; }
419 V8_INLINE void* GetInternalField(int index) const;
421 V8_INLINE V8_DEPRECATE_SOON("use indexed version",
422 void* GetInternalField1() const) {
423 return internal_fields_[0];
425 V8_INLINE V8_DEPRECATE_SOON("use indexed version",
426 void* GetInternalField2() const) {
427 return internal_fields_[1];
430 bool IsFirstPass() const { return callback_ != nullptr; }
432 // When first called, the embedder MUST Reset() the Global which triggered the
433 // callback. The Global itself is unusable for anything else. No v8 other api
434 // calls may be called in the first callback. Should additional work be
435 // required, the embedder must set a second pass callback, which will be
436 // called after all the initial callbacks are processed.
437 // Calling SetSecondPassCallback on the second pass will immediately crash.
438 void SetSecondPassCallback(Callback callback) const { *callback_ = callback; }
444 void* internal_fields_[kInternalFieldsInWeakCallback];
448 template <class T, class P>
449 class WeakCallbackData {
451 typedef void (*Callback)(const WeakCallbackData<T, P>& data);
453 WeakCallbackData(Isolate* isolate, P* parameter, Local<T> handle)
454 : isolate_(isolate), parameter_(parameter), handle_(handle) {}
456 V8_INLINE Isolate* GetIsolate() const { return isolate_; }
457 V8_INLINE P* GetParameter() const { return parameter_; }
458 V8_INLINE Local<T> GetValue() const { return handle_; }
467 // TODO(dcarney): delete this with WeakCallbackData
469 using PhantomCallbackData = WeakCallbackInfo<T>;
472 enum class WeakCallbackType { kParameter, kInternalFields };
476 * An object reference that is independent of any handle scope. Where
477 * a Local handle only lives as long as the HandleScope in which it was
478 * allocated, a PersistentBase handle remains valid until it is explicitly
481 * A persistent handle contains a reference to a storage cell within
482 * the v8 engine which holds an object value and which is updated by
483 * the garbage collector whenever the object is moved. A new storage
484 * cell can be created using the constructor or PersistentBase::Reset and
485 * existing handles can be disposed using PersistentBase::Reset.
488 template <class T> class PersistentBase {
491 * If non-empty, destroy the underlying storage cell
492 * IsEmpty() will return true after this call.
494 V8_INLINE void Reset();
496 * If non-empty, destroy the underlying storage cell
497 * and create a new one with the contents of other if other is non empty
500 V8_INLINE void Reset(Isolate* isolate, const Local<S>& other);
503 * If non-empty, destroy the underlying storage cell
504 * and create a new one with the contents of other if other is non empty
507 V8_INLINE void Reset(Isolate* isolate, const PersistentBase<S>& other);
509 V8_INLINE bool IsEmpty() const { return val_ == NULL; }
510 V8_INLINE void Empty() { val_ = 0; }
512 V8_INLINE Local<T> Get(Isolate* isolate) const {
513 return Local<T>::New(isolate, *this);
517 V8_INLINE bool operator==(const PersistentBase<S>& that) const {
518 internal::Object** a = reinterpret_cast<internal::Object**>(this->val_);
519 internal::Object** b = reinterpret_cast<internal::Object**>(that.val_);
520 if (a == NULL) return b == NULL;
521 if (b == NULL) return false;
526 V8_INLINE bool operator==(const Local<S>& that) const {
527 internal::Object** a = reinterpret_cast<internal::Object**>(this->val_);
528 internal::Object** b = reinterpret_cast<internal::Object**>(that.val_);
529 if (a == NULL) return b == NULL;
530 if (b == NULL) return false;
535 V8_INLINE bool operator!=(const PersistentBase<S>& that) const {
536 return !operator==(that);
540 V8_INLINE bool operator!=(const Local<S>& that) const {
541 return !operator==(that);
545 * Install a finalization callback on this object.
546 * NOTE: There is no guarantee as to *when* or even *if* the callback is
547 * invoked. The invocation is performed solely on a best effort basis.
548 * As always, GC-based finalization should *not* be relied upon for any
549 * critical form of resource management!
551 template <typename P>
552 V8_INLINE V8_DEPRECATE_SOON(
553 "use WeakCallbackInfo version",
554 void SetWeak(P* parameter,
555 typename WeakCallbackData<T, P>::Callback callback));
557 template <typename S, typename P>
558 V8_INLINE V8_DEPRECATE_SOON(
559 "use WeakCallbackInfo version",
560 void SetWeak(P* parameter,
561 typename WeakCallbackData<S, P>::Callback callback));
563 // Phantom persistents work like weak persistents, except that the pointer to
564 // the object being collected is not available in the finalization callback.
565 // This enables the garbage collector to collect the object and any objects
566 // it references transitively in one GC cycle. At the moment you can either
567 // specify a parameter for the callback or the location of two internal
568 // fields in the dying object.
569 template <typename P>
570 V8_INLINE V8_DEPRECATE_SOON(
572 void SetPhantom(P* parameter,
573 typename WeakCallbackInfo<P>::Callback callback,
574 int internal_field_index1 = -1,
575 int internal_field_index2 = -1));
577 template <typename P>
578 V8_INLINE void SetWeak(P* parameter,
579 typename WeakCallbackInfo<P>::Callback callback,
580 WeakCallbackType type);
583 V8_INLINE P* ClearWeak();
585 // TODO(dcarney): remove this.
586 V8_INLINE void ClearWeak() { ClearWeak<void>(); }
589 * Marks the reference to this object independent. Garbage collector is free
590 * to ignore any object groups containing this object. Weak callback for an
591 * independent handle should not assume that it will be preceded by a global
592 * GC prologue callback or followed by a global GC epilogue callback.
594 V8_INLINE void MarkIndependent();
597 * Marks the reference to this object partially dependent. Partially dependent
598 * handles only depend on other partially dependent handles and these
599 * dependencies are provided through object groups. It provides a way to build
600 * smaller object groups for young objects that represent only a subset of all
601 * external dependencies. This mark is automatically cleared after each
602 * garbage collection.
604 V8_INLINE void MarkPartiallyDependent();
606 V8_INLINE bool IsIndependent() const;
608 /** Checks if the handle holds the only reference to an object. */
609 V8_INLINE bool IsNearDeath() const;
611 /** Returns true if the handle's reference is weak. */
612 V8_INLINE bool IsWeak() const;
615 * Assigns a wrapper class ID to the handle. See RetainedObjectInfo interface
616 * description in v8-profiler.h for details.
618 V8_INLINE void SetWrapperClassId(uint16_t class_id);
621 * Returns the class ID previously assigned to this handle or 0 if no class ID
622 * was previously assigned.
624 V8_INLINE uint16_t WrapperClassId() const;
627 friend class Isolate;
629 template<class F> friend class Local;
630 template<class F1, class F2> friend class Persistent;
633 template<class F> friend class PersistentBase;
634 template<class F> friend class ReturnValue;
635 template <class F1, class F2, class F3>
636 friend class PersistentValueMapBase;
637 template<class F1, class F2> friend class PersistentValueVector;
640 explicit V8_INLINE PersistentBase(T* val) : val_(val) {}
641 PersistentBase(const PersistentBase& other) = delete; // NOLINT
642 void operator=(const PersistentBase&) = delete;
643 V8_INLINE static T* New(Isolate* isolate, T* that);
650 * Default traits for Persistent. This class does not allow
651 * use of the copy constructor or assignment operator.
652 * At present kResetInDestructor is not set, but that will change in a future
656 class NonCopyablePersistentTraits {
658 typedef Persistent<T, NonCopyablePersistentTraits<T> > NonCopyablePersistent;
659 static const bool kResetInDestructor = false;
660 template<class S, class M>
661 V8_INLINE static void Copy(const Persistent<S, M>& source,
662 NonCopyablePersistent* dest) {
663 Uncompilable<Object>();
665 // TODO(dcarney): come up with a good compile error here.
666 template<class O> V8_INLINE static void Uncompilable() {
667 TYPE_CHECK(O, Primitive);
673 * Helper class traits to allow copying and assignment of Persistent.
674 * This will clone the contents of storage cell, but not any of the flags, etc.
677 struct CopyablePersistentTraits {
678 typedef Persistent<T, CopyablePersistentTraits<T> > CopyablePersistent;
679 static const bool kResetInDestructor = true;
680 template<class S, class M>
681 static V8_INLINE void Copy(const Persistent<S, M>& source,
682 CopyablePersistent* dest) {
683 // do nothing, just allow copy
689 * A PersistentBase which allows copy and assignment.
691 * Copy, assignment and destructor bevavior is controlled by the traits
694 * Note: Persistent class hierarchy is subject to future changes.
696 template <class T, class M> class Persistent : public PersistentBase<T> {
699 * A Persistent with no storage cell.
701 V8_INLINE Persistent() : PersistentBase<T>(0) { }
703 * Construct a Persistent from a Local.
704 * When the Local is non-empty, a new storage cell is created
705 * pointing to the same object, and no flags are set.
708 V8_INLINE Persistent(Isolate* isolate, Local<S> that)
709 : PersistentBase<T>(PersistentBase<T>::New(isolate, *that)) {
713 * Construct a Persistent from a Persistent.
714 * When the Persistent is non-empty, a new storage cell is created
715 * pointing to the same object, and no flags are set.
717 template <class S, class M2>
718 V8_INLINE Persistent(Isolate* isolate, const Persistent<S, M2>& that)
719 : PersistentBase<T>(PersistentBase<T>::New(isolate, *that)) {
723 * The copy constructors and assignment operator create a Persistent
724 * exactly as the Persistent constructor, but the Copy function from the
725 * traits class is called, allowing the setting of flags based on the
728 V8_INLINE Persistent(const Persistent& that) : PersistentBase<T>(0) {
731 template <class S, class M2>
732 V8_INLINE Persistent(const Persistent<S, M2>& that) : PersistentBase<T>(0) {
735 V8_INLINE Persistent& operator=(const Persistent& that) { // NOLINT
739 template <class S, class M2>
740 V8_INLINE Persistent& operator=(const Persistent<S, M2>& that) { // NOLINT
745 * The destructor will dispose the Persistent based on the
746 * kResetInDestructor flags in the traits class. Since not calling dispose
747 * can result in a memory leak, it is recommended to always set this flag.
749 V8_INLINE ~Persistent() {
750 if (M::kResetInDestructor) this->Reset();
753 // TODO(dcarney): this is pretty useless, fix or remove
755 V8_INLINE static Persistent<T>& Cast(Persistent<S>& that) { // NOLINT
756 #ifdef V8_ENABLE_CHECKS
757 // If we're going to perform the type check then we have to check
758 // that the handle isn't empty before doing the checked cast.
759 if (!that.IsEmpty()) T::Cast(*that);
761 return reinterpret_cast<Persistent<T>&>(that);
764 // TODO(dcarney): this is pretty useless, fix or remove
765 template <class S> V8_INLINE Persistent<S>& As() { // NOLINT
766 return Persistent<S>::Cast(*this);
770 friend class Isolate;
772 template<class F> friend class Local;
773 template<class F1, class F2> friend class Persistent;
774 template<class F> friend class ReturnValue;
776 template <class S> V8_INLINE Persistent(S* that) : PersistentBase<T>(that) { }
777 V8_INLINE T* operator*() const { return this->val_; }
778 template<class S, class M2>
779 V8_INLINE void Copy(const Persistent<S, M2>& that);
784 * A PersistentBase which has move semantics.
786 * Note: Persistent class hierarchy is subject to future changes.
789 class Global : public PersistentBase<T> {
792 * A Global with no storage cell.
794 V8_INLINE Global() : PersistentBase<T>(nullptr) {}
796 * Construct a Global from a Local.
797 * When the Local is non-empty, a new storage cell is created
798 * pointing to the same object, and no flags are set.
801 V8_INLINE Global(Isolate* isolate, Local<S> that)
802 : PersistentBase<T>(PersistentBase<T>::New(isolate, *that)) {
806 * Construct a Global from a PersistentBase.
807 * When the Persistent is non-empty, a new storage cell is created
808 * pointing to the same object, and no flags are set.
811 V8_INLINE Global(Isolate* isolate, const PersistentBase<S>& that)
812 : PersistentBase<T>(PersistentBase<T>::New(isolate, that.val_)) {
818 V8_INLINE Global(Global&& other) : PersistentBase<T>(other.val_) { // NOLINT
819 other.val_ = nullptr;
821 V8_INLINE ~Global() { this->Reset(); }
823 * Move via assignment.
826 V8_INLINE Global& operator=(Global<S>&& rhs) { // NOLINT
830 this->val_ = rhs.val_;
836 * Pass allows returning uniques from functions, etc.
838 Global Pass() { return static_cast<Global&&>(*this); } // NOLINT
841 * For compatibility with Chromium's base::Bind (base::Passed).
843 typedef void MoveOnlyTypeForCPP03;
847 friend class ReturnValue;
848 Global(const Global&) = delete;
849 void operator=(const Global&) = delete;
850 V8_INLINE T* operator*() const { return this->val_; }
854 // UniquePersistent is an alias for Global for historical reason.
856 using UniquePersistent = Global<T>;
860 * A stack-allocated class that governs a number of local handles.
861 * After a handle scope has been created, all local handles will be
862 * allocated within that handle scope until either the handle scope is
863 * deleted or another handle scope is created. If there is already a
864 * handle scope and a new one is created, all allocations will take
865 * place in the new handle scope until it is deleted. After that,
866 * new handles will again be allocated in the original handle scope.
868 * After the handle scope of a local handle has been deleted the
869 * garbage collector will no longer track the object stored in the
870 * handle and may deallocate it. The behavior of accessing a handle
871 * for which the handle scope has been deleted is undefined.
873 class V8_EXPORT HandleScope {
875 HandleScope(Isolate* isolate);
880 * Counts the number of allocated handles.
882 static int NumberOfHandles(Isolate* isolate);
884 V8_INLINE Isolate* GetIsolate() const {
885 return reinterpret_cast<Isolate*>(isolate_);
889 V8_INLINE HandleScope() {}
891 void Initialize(Isolate* isolate);
893 static internal::Object** CreateHandle(internal::Isolate* isolate,
894 internal::Object* value);
897 // Uses heap_object to obtain the current Isolate.
898 static internal::Object** CreateHandle(internal::HeapObject* heap_object,
899 internal::Object* value);
901 // Make it hard to create heap-allocated or illegal handle scopes by
902 // disallowing certain operations.
903 HandleScope(const HandleScope&);
904 void operator=(const HandleScope&);
905 void* operator new(size_t size);
906 void operator delete(void*, size_t);
908 internal::Isolate* isolate_;
909 internal::Object** prev_next_;
910 internal::Object** prev_limit_;
912 // Local::New uses CreateHandle with an Isolate* parameter.
913 template<class F> friend class Local;
915 // Object::GetInternalField and Context::GetEmbedderData use CreateHandle with
916 // a HeapObject* in their shortcuts.
918 friend class Context;
923 * A HandleScope which first allocates a handle in the current scope
924 * which will be later filled with the escape value.
926 class V8_EXPORT EscapableHandleScope : public HandleScope {
928 EscapableHandleScope(Isolate* isolate);
929 V8_INLINE ~EscapableHandleScope() {}
932 * Pushes the value into the previous scope and returns a handle to it.
933 * Cannot be called twice.
936 V8_INLINE Local<T> Escape(Local<T> value) {
937 internal::Object** slot =
938 Escape(reinterpret_cast<internal::Object**>(*value));
939 return Local<T>(reinterpret_cast<T*>(slot));
943 internal::Object** Escape(internal::Object** escape_value);
945 // Make it hard to create heap-allocated or illegal handle scopes by
946 // disallowing certain operations.
947 EscapableHandleScope(const EscapableHandleScope&);
948 void operator=(const EscapableHandleScope&);
949 void* operator new(size_t size);
950 void operator delete(void*, size_t);
952 internal::Object** escape_slot_;
955 class V8_EXPORT SealHandleScope {
957 SealHandleScope(Isolate* isolate);
961 // Make it hard to create heap-allocated or illegal handle scopes by
962 // disallowing certain operations.
963 SealHandleScope(const SealHandleScope&);
964 void operator=(const SealHandleScope&);
965 void* operator new(size_t size);
966 void operator delete(void*, size_t);
968 internal::Isolate* isolate_;
970 internal::Object** prev_limit_;
974 // --- Special objects ---
978 * The superclass of values and API object templates.
980 class V8_EXPORT Data {
987 * The optional attributes of ScriptOrigin.
989 class ScriptOriginOptions {
991 V8_INLINE ScriptOriginOptions(bool is_embedder_debug_script = false,
992 bool is_shared_cross_origin = false,
993 bool is_opaque = false)
994 : flags_((is_embedder_debug_script ? kIsEmbedderDebugScript : 0) |
995 (is_shared_cross_origin ? kIsSharedCrossOrigin : 0) |
996 (is_opaque ? kIsOpaque : 0)) {}
997 V8_INLINE ScriptOriginOptions(int flags)
999 (kIsEmbedderDebugScript | kIsSharedCrossOrigin | kIsOpaque)) {}
1000 bool IsEmbedderDebugScript() const {
1001 return (flags_ & kIsEmbedderDebugScript) != 0;
1003 bool IsSharedCrossOrigin() const {
1004 return (flags_ & kIsSharedCrossOrigin) != 0;
1006 bool IsOpaque() const { return (flags_ & kIsOpaque) != 0; }
1007 int Flags() const { return flags_; }
1011 kIsEmbedderDebugScript = 1,
1012 kIsSharedCrossOrigin = 1 << 1,
1019 * The origin, within a file, of a script.
1021 class ScriptOrigin {
1023 V8_INLINE ScriptOrigin(
1024 Local<Value> resource_name,
1025 Local<Integer> resource_line_offset = Local<Integer>(),
1026 Local<Integer> resource_column_offset = Local<Integer>(),
1027 Local<Boolean> resource_is_shared_cross_origin = Local<Boolean>(),
1028 Local<Integer> script_id = Local<Integer>(),
1029 Local<Boolean> resource_is_embedder_debug_script = Local<Boolean>(),
1030 Local<Value> source_map_url = Local<Value>(),
1031 Local<Boolean> resource_is_opaque = Local<Boolean>());
1032 V8_INLINE Local<Value> ResourceName() const;
1033 V8_INLINE Local<Integer> ResourceLineOffset() const;
1034 V8_INLINE Local<Integer> ResourceColumnOffset() const;
1036 * Returns true for embedder's debugger scripts
1038 V8_INLINE Local<Integer> ScriptID() const;
1039 V8_INLINE Local<Value> SourceMapUrl() const;
1040 V8_INLINE ScriptOriginOptions Options() const { return options_; }
1043 Local<Value> resource_name_;
1044 Local<Integer> resource_line_offset_;
1045 Local<Integer> resource_column_offset_;
1046 ScriptOriginOptions options_;
1047 Local<Integer> script_id_;
1048 Local<Value> source_map_url_;
1053 * A compiled JavaScript script, not yet tied to a Context.
1055 class V8_EXPORT UnboundScript {
1058 * Binds the script to the currently entered context.
1060 Local<Script> BindToCurrentContext();
1063 Local<Value> GetScriptName();
1066 * Data read from magic sourceURL comments.
1068 Local<Value> GetSourceURL();
1070 * Data read from magic sourceMappingURL comments.
1072 Local<Value> GetSourceMappingURL();
1075 * Returns zero based line number of the code_pos location in the script.
1076 * -1 will be returned if no information available.
1078 int GetLineNumber(int code_pos);
1080 static const int kNoScriptId = 0;
1085 * A compiled JavaScript script, tied to a Context which was active when the
1086 * script was compiled.
1088 class V8_EXPORT Script {
1091 * A shorthand for ScriptCompiler::Compile().
1093 static V8_DEPRECATE_SOON(
1094 "Use maybe version",
1095 Local<Script> Compile(Local<String> source,
1096 ScriptOrigin* origin = nullptr));
1097 static V8_WARN_UNUSED_RESULT MaybeLocal<Script> Compile(
1098 Local<Context> context, Local<String> source,
1099 ScriptOrigin* origin = nullptr);
1101 static Local<Script> V8_DEPRECATE_SOON("Use maybe version",
1102 Compile(Local<String> source,
1103 Local<String> file_name));
1106 * Runs the script returning the resulting value. It will be run in the
1107 * context in which it was created (ScriptCompiler::CompileBound or
1108 * UnboundScript::BindToCurrentContext()).
1110 V8_DEPRECATE_SOON("Use maybe version", Local<Value> Run());
1111 V8_WARN_UNUSED_RESULT MaybeLocal<Value> Run(Local<Context> context);
1114 * Returns the corresponding context-unbound script.
1116 Local<UnboundScript> GetUnboundScript();
1121 * For compiling scripts.
1123 class V8_EXPORT ScriptCompiler {
1126 * Compilation data that the embedder can cache and pass back to speed up
1127 * future compilations. The data is produced if the CompilerOptions passed to
1128 * the compilation functions in ScriptCompiler contains produce_data_to_cache
1129 * = true. The data to cache can then can be retrieved from
1132 struct V8_EXPORT CachedData {
1142 buffer_policy(BufferNotOwned) {}
1144 // If buffer_policy is BufferNotOwned, the caller keeps the ownership of
1145 // data and guarantees that it stays alive until the CachedData object is
1146 // destroyed. If the policy is BufferOwned, the given data will be deleted
1147 // (with delete[]) when the CachedData object is destroyed.
1148 CachedData(const uint8_t* data, int length,
1149 BufferPolicy buffer_policy = BufferNotOwned);
1151 // TODO(marja): Async compilation; add constructors which take a callback
1152 // which will be called when V8 no longer needs the data.
1153 const uint8_t* data;
1156 BufferPolicy buffer_policy;
1159 // Prevent copying. Not implemented.
1160 CachedData(const CachedData&);
1161 CachedData& operator=(const CachedData&);
1165 * Source code which can be then compiled to a UnboundScript or Script.
1169 // Source takes ownership of CachedData.
1170 V8_INLINE Source(Local<String> source_string, const ScriptOrigin& origin,
1171 CachedData* cached_data = NULL);
1172 V8_INLINE Source(Local<String> source_string,
1173 CachedData* cached_data = NULL);
1174 V8_INLINE ~Source();
1176 // Ownership of the CachedData or its buffers is *not* transferred to the
1177 // caller. The CachedData object is alive as long as the Source object is
1179 V8_INLINE const CachedData* GetCachedData() const;
1182 friend class ScriptCompiler;
1183 // Prevent copying. Not implemented.
1184 Source(const Source&);
1185 Source& operator=(const Source&);
1187 Local<String> source_string;
1189 // Origin information
1190 Local<Value> resource_name;
1191 Local<Integer> resource_line_offset;
1192 Local<Integer> resource_column_offset;
1193 ScriptOriginOptions resource_options;
1194 Local<Value> source_map_url;
1196 // Cached data from previous compilation (if a kConsume*Cache flag is
1197 // set), or hold newly generated cache data (kProduce*Cache flags) are
1198 // set when calling a compile method.
1199 CachedData* cached_data;
1203 * For streaming incomplete script data to V8. The embedder should implement a
1204 * subclass of this class.
1206 class V8_EXPORT ExternalSourceStream {
1208 virtual ~ExternalSourceStream() {}
1211 * V8 calls this to request the next chunk of data from the embedder. This
1212 * function will be called on a background thread, so it's OK to block and
1213 * wait for the data, if the embedder doesn't have data yet. Returns the
1214 * length of the data returned. When the data ends, GetMoreData should
1215 * return 0. Caller takes ownership of the data.
1217 * When streaming UTF-8 data, V8 handles multi-byte characters split between
1218 * two data chunks, but doesn't handle multi-byte characters split between
1219 * more than two data chunks. The embedder can avoid this problem by always
1220 * returning at least 2 bytes of data.
1222 * If the embedder wants to cancel the streaming, they should make the next
1223 * GetMoreData call return 0. V8 will interpret it as end of data (and most
1224 * probably, parsing will fail). The streaming task will return as soon as
1225 * V8 has parsed the data it received so far.
1227 virtual size_t GetMoreData(const uint8_t** src) = 0;
1230 * V8 calls this method to set a 'bookmark' at the current position in
1231 * the source stream, for the purpose of (maybe) later calling
1232 * ResetToBookmark. If ResetToBookmark is called later, then subsequent
1233 * calls to GetMoreData should return the same data as they did when
1234 * SetBookmark was called earlier.
1236 * The embedder may return 'false' to indicate it cannot provide this
1239 virtual bool SetBookmark();
1242 * V8 calls this to return to a previously set bookmark.
1244 virtual void ResetToBookmark();
1249 * Source code which can be streamed into V8 in pieces. It will be parsed
1250 * while streaming. It can be compiled after the streaming is complete.
1251 * StreamedSource must be kept alive while the streaming task is ran (see
1252 * ScriptStreamingTask below).
1254 class V8_EXPORT StreamedSource {
1256 enum Encoding { ONE_BYTE, TWO_BYTE, UTF8 };
1258 StreamedSource(ExternalSourceStream* source_stream, Encoding encoding);
1261 // Ownership of the CachedData or its buffers is *not* transferred to the
1262 // caller. The CachedData object is alive as long as the StreamedSource
1264 const CachedData* GetCachedData() const;
1266 internal::StreamedSource* impl() const { return impl_; }
1269 // Prevent copying. Not implemented.
1270 StreamedSource(const StreamedSource&);
1271 StreamedSource& operator=(const StreamedSource&);
1273 internal::StreamedSource* impl_;
1277 * A streaming task which the embedder must run on a background thread to
1278 * stream scripts into V8. Returned by ScriptCompiler::StartStreamingScript.
1280 class ScriptStreamingTask {
1282 virtual ~ScriptStreamingTask() {}
1283 virtual void Run() = 0;
1286 enum CompileOptions {
1287 kNoCompileOptions = 0,
1288 kProduceParserCache,
1289 kConsumeParserCache,
1295 * Compiles the specified script (context-independent).
1296 * Cached data as part of the source object can be optionally produced to be
1297 * consumed later to speed up compilation of identical source scripts.
1299 * Note that when producing cached data, the source must point to NULL for
1300 * cached data. When consuming cached data, the cached data must have been
1301 * produced by the same version of V8.
1303 * \param source Script source code.
1304 * \return Compiled script object (context independent; for running it must be
1305 * bound to a context).
1307 static V8_DEPRECATE_SOON("Use maybe version",
1308 Local<UnboundScript> CompileUnbound(
1309 Isolate* isolate, Source* source,
1310 CompileOptions options = kNoCompileOptions));
1311 static V8_WARN_UNUSED_RESULT MaybeLocal<UnboundScript> CompileUnboundScript(
1312 Isolate* isolate, Source* source,
1313 CompileOptions options = kNoCompileOptions);
1316 * Compiles the specified script (bound to current context).
1318 * \param source Script source code.
1319 * \param pre_data Pre-parsing data, as obtained by ScriptData::PreCompile()
1320 * using pre_data speeds compilation if it's done multiple times.
1321 * Owned by caller, no references are kept when this function returns.
1322 * \return Compiled script object, bound to the context that was active
1323 * when this function was called. When run it will always use this
1326 static V8_DEPRECATE_SOON(
1327 "Use maybe version",
1328 Local<Script> Compile(Isolate* isolate, Source* source,
1329 CompileOptions options = kNoCompileOptions));
1330 static V8_WARN_UNUSED_RESULT MaybeLocal<Script> Compile(
1331 Local<Context> context, Source* source,
1332 CompileOptions options = kNoCompileOptions);
1335 * Returns a task which streams script data into V8, or NULL if the script
1336 * cannot be streamed. The user is responsible for running the task on a
1337 * background thread and deleting it. When ran, the task starts parsing the
1338 * script, and it will request data from the StreamedSource as needed. When
1339 * ScriptStreamingTask::Run exits, all data has been streamed and the script
1340 * can be compiled (see Compile below).
1342 * This API allows to start the streaming with as little data as possible, and
1343 * the remaining data (for example, the ScriptOrigin) is passed to Compile.
1345 static ScriptStreamingTask* StartStreamingScript(
1346 Isolate* isolate, StreamedSource* source,
1347 CompileOptions options = kNoCompileOptions);
1350 * Compiles a streamed script (bound to current context).
1352 * This can only be called after the streaming has finished
1353 * (ScriptStreamingTask has been run). V8 doesn't construct the source string
1354 * during streaming, so the embedder needs to pass the full source here.
1356 static V8_DEPRECATE_SOON(
1357 "Use maybe version",
1358 Local<Script> Compile(Isolate* isolate, StreamedSource* source,
1359 Local<String> full_source_string,
1360 const ScriptOrigin& origin));
1361 static V8_WARN_UNUSED_RESULT MaybeLocal<Script> Compile(
1362 Local<Context> context, StreamedSource* source,
1363 Local<String> full_source_string, const ScriptOrigin& origin);
1366 * Return a version tag for CachedData for the current V8 version & flags.
1368 * This value is meant only for determining whether a previously generated
1369 * CachedData instance is still valid; the tag has no other meaing.
1371 * Background: The data carried by CachedData may depend on the exact
1372 * V8 version number or currently compiler flags. This means when
1373 * persisting CachedData, the embedder must take care to not pass in
1374 * data from another V8 version, or the same version with different
1377 * The easiest way to do so is to clear the embedder's cache on any
1380 * Alternatively, this tag can be stored alongside the cached data and
1381 * compared when it is being used.
1383 static uint32_t CachedDataVersionTag();
1386 * Compile an ES6 module.
1388 * This is an unfinished experimental feature, and is only exposed
1389 * here for internal testing purposes.
1390 * Only parsing works at the moment. Do not use.
1392 * TODO(adamk): Script is likely the wrong return value for this;
1393 * should return some new Module type.
1395 static V8_WARN_UNUSED_RESULT MaybeLocal<Script> CompileModule(
1396 Local<Context> context, Source* source,
1397 CompileOptions options = kNoCompileOptions);
1400 * Compile a function for a given context. This is equivalent to running
1403 * return function(args) { ... }
1406 * It is possible to specify multiple context extensions (obj in the above
1409 static V8_DEPRECATE_SOON("Use maybe version",
1410 Local<Function> CompileFunctionInContext(
1411 Isolate* isolate, Source* source,
1412 Local<Context> context, size_t arguments_count,
1413 Local<String> arguments[],
1414 size_t context_extension_count,
1415 Local<Object> context_extensions[]));
1416 static V8_WARN_UNUSED_RESULT MaybeLocal<Function> CompileFunctionInContext(
1417 Local<Context> context, Source* source, size_t arguments_count,
1418 Local<String> arguments[], size_t context_extension_count,
1419 Local<Object> context_extensions[]);
1422 static V8_WARN_UNUSED_RESULT MaybeLocal<UnboundScript> CompileUnboundInternal(
1423 Isolate* isolate, Source* source, CompileOptions options, bool is_module);
1430 class V8_EXPORT Message {
1432 Local<String> Get() const;
1434 V8_DEPRECATE_SOON("Use maybe version", Local<String> GetSourceLine() const);
1435 V8_WARN_UNUSED_RESULT MaybeLocal<String> GetSourceLine(
1436 Local<Context> context) const;
1439 * Returns the origin for the script from where the function causing the
1442 ScriptOrigin GetScriptOrigin() const;
1445 * Returns the resource name for the script from where the function causing
1446 * the error originates.
1448 Local<Value> GetScriptResourceName() const;
1451 * Exception stack trace. By default stack traces are not captured for
1452 * uncaught exceptions. SetCaptureStackTraceForUncaughtExceptions allows
1453 * to change this option.
1455 Local<StackTrace> GetStackTrace() const;
1458 * Returns the number, 1-based, of the line where the error occurred.
1460 V8_DEPRECATE_SOON("Use maybe version", int GetLineNumber() const);
1461 V8_WARN_UNUSED_RESULT Maybe<int> GetLineNumber(Local<Context> context) const;
1464 * Returns the index within the script of the first character where
1465 * the error occurred.
1467 int GetStartPosition() const;
1470 * Returns the index within the script of the last character where
1471 * the error occurred.
1473 int GetEndPosition() const;
1476 * Returns the index within the line of the first character where
1477 * the error occurred.
1479 V8_DEPRECATE_SOON("Use maybe version", int GetStartColumn() const);
1480 V8_WARN_UNUSED_RESULT Maybe<int> GetStartColumn(Local<Context> context) const;
1483 * Returns the index within the line of the last character where
1484 * the error occurred.
1486 V8_DEPRECATE_SOON("Use maybe version", int GetEndColumn() const);
1487 V8_WARN_UNUSED_RESULT Maybe<int> GetEndColumn(Local<Context> context) const;
1490 * Passes on the value set by the embedder when it fed the script from which
1491 * this Message was generated to V8.
1493 bool IsSharedCrossOrigin() const;
1494 bool IsOpaque() const;
1496 // TODO(1245381): Print to a string instead of on a FILE.
1497 static void PrintCurrentStackTrace(Isolate* isolate, FILE* out);
1499 static const int kNoLineNumberInfo = 0;
1500 static const int kNoColumnInfo = 0;
1501 static const int kNoScriptIdInfo = 0;
1506 * Representation of a JavaScript stack trace. The information collected is a
1507 * snapshot of the execution stack and the information remains valid after
1508 * execution continues.
1510 class V8_EXPORT StackTrace {
1513 * Flags that determine what information is placed captured for each
1514 * StackFrame when grabbing the current stack trace.
1516 enum StackTraceOptions {
1518 kColumnOffset = 1 << 1 | kLineNumber,
1519 kScriptName = 1 << 2,
1520 kFunctionName = 1 << 3,
1522 kIsConstructor = 1 << 5,
1523 kScriptNameOrSourceURL = 1 << 6,
1525 kExposeFramesAcrossSecurityOrigins = 1 << 8,
1526 kOverview = kLineNumber | kColumnOffset | kScriptName | kFunctionName,
1527 kDetailed = kOverview | kIsEval | kIsConstructor | kScriptNameOrSourceURL
1531 * Returns a StackFrame at a particular index.
1533 Local<StackFrame> GetFrame(uint32_t index) const;
1536 * Returns the number of StackFrames.
1538 int GetFrameCount() const;
1541 * Returns StackTrace as a v8::Array that contains StackFrame objects.
1543 Local<Array> AsArray();
1546 * Grab a snapshot of the current JavaScript execution stack.
1548 * \param frame_limit The maximum number of stack frames we want to capture.
1549 * \param options Enumerates the set of things we will capture for each
1552 static Local<StackTrace> CurrentStackTrace(
1555 StackTraceOptions options = kOverview);
1560 * A single JavaScript stack frame.
1562 class V8_EXPORT StackFrame {
1565 * Returns the number, 1-based, of the line for the associate function call.
1566 * This method will return Message::kNoLineNumberInfo if it is unable to
1567 * retrieve the line number, or if kLineNumber was not passed as an option
1568 * when capturing the StackTrace.
1570 int GetLineNumber() const;
1573 * Returns the 1-based column offset on the line for the associated function
1575 * This method will return Message::kNoColumnInfo if it is unable to retrieve
1576 * the column number, or if kColumnOffset was not passed as an option when
1577 * capturing the StackTrace.
1579 int GetColumn() const;
1582 * Returns the id of the script for the function for this StackFrame.
1583 * This method will return Message::kNoScriptIdInfo if it is unable to
1584 * retrieve the script id, or if kScriptId was not passed as an option when
1585 * capturing the StackTrace.
1587 int GetScriptId() const;
1590 * Returns the name of the resource that contains the script for the
1591 * function for this StackFrame.
1593 Local<String> GetScriptName() const;
1596 * Returns the name of the resource that contains the script for the
1597 * function for this StackFrame or sourceURL value if the script name
1598 * is undefined and its source ends with //# sourceURL=... string or
1599 * deprecated //@ sourceURL=... string.
1601 Local<String> GetScriptNameOrSourceURL() const;
1604 * Returns the name of the function associated with this stack frame.
1606 Local<String> GetFunctionName() const;
1609 * Returns whether or not the associated function is compiled via a call to
1612 bool IsEval() const;
1615 * Returns whether or not the associated function is called as a
1616 * constructor via "new".
1618 bool IsConstructor() const;
1622 // A StateTag represents a possible state of the VM.
1623 enum StateTag { JS, GC, COMPILER, OTHER, EXTERNAL, IDLE };
1626 // A RegisterState represents the current state of registers used
1627 // by the sampling profiler API.
1628 struct RegisterState {
1629 RegisterState() : pc(NULL), sp(NULL), fp(NULL) {}
1630 void* pc; // Instruction pointer.
1631 void* sp; // Stack pointer.
1632 void* fp; // Frame pointer.
1636 // The output structure filled up by GetStackSample API function.
1638 size_t frames_count;
1646 class V8_EXPORT JSON {
1649 * Tries to parse the string |json_string| and returns it as value if
1652 * \param json_string The string to parse.
1653 * \return The corresponding value if successfully parsed.
1655 static V8_DEPRECATE_SOON("Use maybe version",
1656 Local<Value> Parse(Local<String> json_string));
1657 static V8_WARN_UNUSED_RESULT MaybeLocal<Value> Parse(
1658 Isolate* isolate, Local<String> json_string);
1663 * A map whose keys are referenced weakly. It is similar to JavaScript WeakMap
1664 * but can be created without entering a v8::Context and hence shouldn't
1665 * escape to JavaScript.
1667 class V8_EXPORT NativeWeakMap : public Data {
1669 static Local<NativeWeakMap> New(Isolate* isolate);
1670 void Set(Local<Value> key, Local<Value> value);
1671 Local<Value> Get(Local<Value> key);
1672 bool Has(Local<Value> key);
1673 bool Delete(Local<Value> key);
1681 * The superclass of all JavaScript values and objects.
1683 class V8_EXPORT Value : public Data {
1686 * Returns true if this value is the undefined value. See ECMA-262
1689 V8_INLINE bool IsUndefined() const;
1692 * Returns true if this value is the null value. See ECMA-262
1695 V8_INLINE bool IsNull() const;
1698 * Returns true if this value is true.
1700 bool IsTrue() const;
1703 * Returns true if this value is false.
1705 bool IsFalse() const;
1708 * Returns true if this value is a symbol or a string.
1709 * This is an experimental feature.
1711 bool IsName() const;
1714 * Returns true if this value is an instance of the String type.
1717 V8_INLINE bool IsString() const;
1720 * Returns true if this value is a symbol.
1721 * This is an experimental feature.
1723 bool IsSymbol() const;
1726 * Returns true if this value is a function.
1728 bool IsFunction() const;
1731 * Returns true if this value is an array.
1733 bool IsArray() const;
1736 * Returns true if this value is an object.
1738 bool IsObject() const;
1741 * Returns true if this value is boolean.
1743 bool IsBoolean() const;
1746 * Returns true if this value is a number.
1748 bool IsNumber() const;
1751 * Returns true if this value is external.
1753 bool IsExternal() const;
1756 * Returns true if this value is a 32-bit signed integer.
1758 bool IsInt32() const;
1761 * Returns true if this value is a 32-bit unsigned integer.
1763 bool IsUint32() const;
1766 * Returns true if this value is a Date.
1768 bool IsDate() const;
1771 * Returns true if this value is an Arguments object.
1773 bool IsArgumentsObject() const;
1776 * Returns true if this value is a Boolean object.
1778 bool IsBooleanObject() const;
1781 * Returns true if this value is a Number object.
1783 bool IsNumberObject() const;
1786 * Returns true if this value is a String object.
1788 bool IsStringObject() const;
1791 * Returns true if this value is a Symbol object.
1792 * This is an experimental feature.
1794 bool IsSymbolObject() const;
1797 * Returns true if this value is a NativeError.
1799 bool IsNativeError() const;
1802 * Returns true if this value is a RegExp.
1804 bool IsRegExp() const;
1807 * Returns true if this value is a Generator function.
1808 * This is an experimental feature.
1810 bool IsGeneratorFunction() const;
1813 * Returns true if this value is a Generator object (iterator).
1814 * This is an experimental feature.
1816 bool IsGeneratorObject() const;
1819 * Returns true if this value is a Promise.
1820 * This is an experimental feature.
1822 bool IsPromise() const;
1825 * Returns true if this value is a Map.
1830 * Returns true if this value is a Set.
1835 * Returns true if this value is a Map Iterator.
1837 bool IsMapIterator() const;
1840 * Returns true if this value is a Set Iterator.
1842 bool IsSetIterator() const;
1845 * Returns true if this value is a WeakMap.
1847 bool IsWeakMap() const;
1850 * Returns true if this value is a WeakSet.
1852 bool IsWeakSet() const;
1855 * Returns true if this value is an ArrayBuffer.
1856 * This is an experimental feature.
1858 bool IsArrayBuffer() const;
1861 * Returns true if this value is an ArrayBufferView.
1862 * This is an experimental feature.
1864 bool IsArrayBufferView() const;
1867 * Returns true if this value is one of TypedArrays.
1868 * This is an experimental feature.
1870 bool IsTypedArray() const;
1873 * Returns true if this value is an Uint8Array.
1874 * This is an experimental feature.
1876 bool IsUint8Array() const;
1879 * Returns true if this value is an Uint8ClampedArray.
1880 * This is an experimental feature.
1882 bool IsUint8ClampedArray() const;
1885 * Returns true if this value is an Int8Array.
1886 * This is an experimental feature.
1888 bool IsInt8Array() const;
1891 * Returns true if this value is an Uint16Array.
1892 * This is an experimental feature.
1894 bool IsUint16Array() const;
1897 * Returns true if this value is an Int16Array.
1898 * This is an experimental feature.
1900 bool IsInt16Array() const;
1903 * Returns true if this value is an Uint32Array.
1904 * This is an experimental feature.
1906 bool IsUint32Array() const;
1909 * Returns true if this value is an Int32Array.
1910 * This is an experimental feature.
1912 bool IsInt32Array() const;
1915 * Returns true if this value is a Float32Array.
1916 * This is an experimental feature.
1918 bool IsFloat32Array() const;
1921 * Returns true if this value is a Float64Array.
1922 * This is an experimental feature.
1924 bool IsFloat64Array() const;
1927 * Returns true if this value is a SIMD Float32x4.
1928 * This is an experimental feature.
1930 bool IsFloat32x4() const;
1933 * Returns true if this value is a DataView.
1934 * This is an experimental feature.
1936 bool IsDataView() const;
1939 * Returns true if this value is a SharedArrayBuffer.
1940 * This is an experimental feature.
1942 bool IsSharedArrayBuffer() const;
1945 V8_WARN_UNUSED_RESULT MaybeLocal<Boolean> ToBoolean(
1946 Local<Context> context) const;
1947 V8_WARN_UNUSED_RESULT MaybeLocal<Number> ToNumber(
1948 Local<Context> context) const;
1949 V8_WARN_UNUSED_RESULT MaybeLocal<String> ToString(
1950 Local<Context> context) const;
1951 V8_WARN_UNUSED_RESULT MaybeLocal<String> ToDetailString(
1952 Local<Context> context) const;
1953 V8_WARN_UNUSED_RESULT MaybeLocal<Object> ToObject(
1954 Local<Context> context) const;
1955 V8_WARN_UNUSED_RESULT MaybeLocal<Integer> ToInteger(
1956 Local<Context> context) const;
1957 V8_WARN_UNUSED_RESULT MaybeLocal<Uint32> ToUint32(
1958 Local<Context> context) const;
1959 V8_WARN_UNUSED_RESULT MaybeLocal<Int32> ToInt32(Local<Context> context) const;
1961 V8_DEPRECATE_SOON("Use maybe version",
1962 Local<Boolean> ToBoolean(Isolate* isolate) const);
1963 V8_DEPRECATE_SOON("Use maybe version",
1964 Local<Number> ToNumber(Isolate* isolate) const);
1965 V8_DEPRECATE_SOON("Use maybe version",
1966 Local<String> ToString(Isolate* isolate) const);
1967 V8_DEPRECATE_SOON("Use maybe version",
1968 Local<String> ToDetailString(Isolate* isolate) const);
1969 V8_DEPRECATE_SOON("Use maybe version",
1970 Local<Object> ToObject(Isolate* isolate) const);
1971 V8_DEPRECATE_SOON("Use maybe version",
1972 Local<Integer> ToInteger(Isolate* isolate) const);
1973 V8_DEPRECATE_SOON("Use maybe version",
1974 Local<Uint32> ToUint32(Isolate* isolate) const);
1975 V8_DEPRECATE_SOON("Use maybe version",
1976 Local<Int32> ToInt32(Isolate* isolate) const);
1978 inline V8_DEPRECATE_SOON("Use maybe version",
1979 Local<Boolean> ToBoolean() const);
1980 inline V8_DEPRECATE_SOON("Use maybe version", Local<Number> ToNumber() const);
1981 inline V8_DEPRECATE_SOON("Use maybe version", Local<String> ToString() const);
1982 inline V8_DEPRECATE_SOON("Use maybe version",
1983 Local<String> ToDetailString() const);
1984 inline V8_DEPRECATE_SOON("Use maybe version", Local<Object> ToObject() const);
1985 inline V8_DEPRECATE_SOON("Use maybe version",
1986 Local<Integer> ToInteger() const);
1987 inline V8_DEPRECATE_SOON("Use maybe version", Local<Uint32> ToUint32() const);
1988 inline V8_DEPRECATE_SOON("Use maybe version", Local<Int32> ToInt32() const);
1991 * Attempts to convert a string to an array index.
1992 * Returns an empty handle if the conversion fails.
1994 V8_DEPRECATE_SOON("Use maybe version", Local<Uint32> ToArrayIndex() const);
1995 V8_WARN_UNUSED_RESULT MaybeLocal<Uint32> ToArrayIndex(
1996 Local<Context> context) const;
1998 V8_WARN_UNUSED_RESULT Maybe<bool> BooleanValue(Local<Context> context) const;
1999 V8_WARN_UNUSED_RESULT Maybe<double> NumberValue(Local<Context> context) const;
2000 V8_WARN_UNUSED_RESULT Maybe<int64_t> IntegerValue(
2001 Local<Context> context) const;
2002 V8_WARN_UNUSED_RESULT Maybe<uint32_t> Uint32Value(
2003 Local<Context> context) const;
2004 V8_WARN_UNUSED_RESULT Maybe<int32_t> Int32Value(Local<Context> context) const;
2006 V8_DEPRECATE_SOON("Use maybe version", bool BooleanValue() const);
2007 V8_DEPRECATE_SOON("Use maybe version", double NumberValue() const);
2008 V8_DEPRECATE_SOON("Use maybe version", int64_t IntegerValue() const);
2009 V8_DEPRECATE_SOON("Use maybe version", uint32_t Uint32Value() const);
2010 V8_DEPRECATE_SOON("Use maybe version", int32_t Int32Value() const);
2013 V8_DEPRECATE_SOON("Use maybe version", bool Equals(Local<Value> that) const);
2014 V8_WARN_UNUSED_RESULT Maybe<bool> Equals(Local<Context> context,
2015 Local<Value> that) const;
2016 bool StrictEquals(Local<Value> that) const;
2017 bool SameValue(Local<Value> that) const;
2019 template <class T> V8_INLINE static Value* Cast(T* value);
2022 V8_INLINE bool QuickIsUndefined() const;
2023 V8_INLINE bool QuickIsNull() const;
2024 V8_INLINE bool QuickIsString() const;
2025 bool FullIsUndefined() const;
2026 bool FullIsNull() const;
2027 bool FullIsString() const;
2032 * The superclass of primitive values. See ECMA-262 4.3.2.
2034 class V8_EXPORT Primitive : public Value { };
2038 * A primitive boolean value (ECMA-262, 4.3.14). Either the true
2041 class V8_EXPORT Boolean : public Primitive {
2044 V8_INLINE static Boolean* Cast(v8::Value* obj);
2045 V8_INLINE static Local<Boolean> New(Isolate* isolate, bool value);
2048 static void CheckCast(v8::Value* obj);
2053 * A superclass for symbols and strings.
2055 class V8_EXPORT Name : public Primitive {
2058 * Returns the identity hash for this object. The current implementation
2059 * uses an inline property on the object to store the identity hash.
2061 * The return value will never be 0. Also, it is not guaranteed to be
2064 int GetIdentityHash();
2066 V8_INLINE static Name* Cast(v8::Value* obj);
2068 static void CheckCast(v8::Value* obj);
2072 enum class NewStringType { kNormal, kInternalized };
2076 * A JavaScript string value (ECMA-262, 4.3.17).
2078 class V8_EXPORT String : public Name {
2080 static const int kMaxLength = (1 << 28) - 16;
2083 UNKNOWN_ENCODING = 0x1,
2084 TWO_BYTE_ENCODING = 0x0,
2085 ONE_BYTE_ENCODING = 0x4
2088 * Returns the number of characters in this string.
2093 * Returns the number of bytes in the UTF-8 encoded
2094 * representation of this string.
2096 int Utf8Length() const;
2099 * Returns whether this string is known to contain only one byte data.
2100 * Does not read the string.
2101 * False negatives are possible.
2103 bool IsOneByte() const;
2106 * Returns whether this string contain only one byte data.
2107 * Will read the entire string in some cases.
2109 bool ContainsOnlyOneByte() const;
2112 * Write the contents of the string to an external buffer.
2113 * If no arguments are given, expects the buffer to be large
2114 * enough to hold the entire string and NULL terminator. Copies
2115 * the contents of the string and the NULL terminator into the
2118 * WriteUtf8 will not write partial UTF-8 sequences, preferring to stop
2119 * before the end of the buffer.
2121 * Copies up to length characters into the output buffer.
2122 * Only null-terminates if there is enough space in the buffer.
2124 * \param buffer The buffer into which the string will be copied.
2125 * \param start The starting position within the string at which
2127 * \param length The number of characters to copy from the string. For
2128 * WriteUtf8 the number of bytes in the buffer.
2129 * \param nchars_ref The number of characters written, can be NULL.
2130 * \param options Various options that might affect performance of this or
2131 * subsequent operations.
2132 * \return The number of characters copied to the buffer excluding the null
2133 * terminator. For WriteUtf8: The number of bytes copied to the buffer
2134 * including the null terminator (if written).
2138 HINT_MANY_WRITES_EXPECTED = 1,
2139 NO_NULL_TERMINATION = 2,
2140 PRESERVE_ONE_BYTE_NULL = 4,
2141 // Used by WriteUtf8 to replace orphan surrogate code units with the
2142 // unicode replacement character. Needs to be set to guarantee valid UTF-8
2144 REPLACE_INVALID_UTF8 = 8
2147 // 16-bit character codes.
2148 int Write(uint16_t* buffer,
2151 int options = NO_OPTIONS) const;
2152 // One byte characters.
2153 int WriteOneByte(uint8_t* buffer,
2156 int options = NO_OPTIONS) const;
2157 // UTF-8 encoded characters.
2158 int WriteUtf8(char* buffer,
2160 int* nchars_ref = NULL,
2161 int options = NO_OPTIONS) const;
2164 * A zero length string.
2166 V8_INLINE static v8::Local<v8::String> Empty(Isolate* isolate);
2169 * Returns true if the string is external
2171 bool IsExternal() const;
2174 * Returns true if the string is both external and one-byte.
2176 bool IsExternalOneByte() const;
2178 class V8_EXPORT ExternalStringResourceBase { // NOLINT
2180 virtual ~ExternalStringResourceBase() {}
2183 ExternalStringResourceBase() {}
2186 * Internally V8 will call this Dispose method when the external string
2187 * resource is no longer needed. The default implementation will use the
2188 * delete operator. This method can be overridden in subclasses to
2189 * control how allocated external string resources are disposed.
2191 virtual void Dispose() { delete this; }
2194 // Disallow copying and assigning.
2195 ExternalStringResourceBase(const ExternalStringResourceBase&);
2196 void operator=(const ExternalStringResourceBase&);
2198 friend class v8::internal::Heap;
2202 * An ExternalStringResource is a wrapper around a two-byte string
2203 * buffer that resides outside V8's heap. Implement an
2204 * ExternalStringResource to manage the life cycle of the underlying
2205 * buffer. Note that the string data must be immutable.
2207 class V8_EXPORT ExternalStringResource
2208 : public ExternalStringResourceBase {
2211 * Override the destructor to manage the life cycle of the underlying
2214 virtual ~ExternalStringResource() {}
2217 * The string data from the underlying buffer.
2219 virtual const uint16_t* data() const = 0;
2222 * The length of the string. That is, the number of two-byte characters.
2224 virtual size_t length() const = 0;
2227 ExternalStringResource() {}
2231 * An ExternalOneByteStringResource is a wrapper around an one-byte
2232 * string buffer that resides outside V8's heap. Implement an
2233 * ExternalOneByteStringResource to manage the life cycle of the
2234 * underlying buffer. Note that the string data must be immutable
2235 * and that the data must be Latin-1 and not UTF-8, which would require
2236 * special treatment internally in the engine and do not allow efficient
2237 * indexing. Use String::New or convert to 16 bit data for non-Latin1.
2240 class V8_EXPORT ExternalOneByteStringResource
2241 : public ExternalStringResourceBase {
2244 * Override the destructor to manage the life cycle of the underlying
2247 virtual ~ExternalOneByteStringResource() {}
2248 /** The string data from the underlying buffer.*/
2249 virtual const char* data() const = 0;
2250 /** The number of Latin-1 characters in the string.*/
2251 virtual size_t length() const = 0;
2253 ExternalOneByteStringResource() {}
2257 * If the string is an external string, return the ExternalStringResourceBase
2258 * regardless of the encoding, otherwise return NULL. The encoding of the
2259 * string is returned in encoding_out.
2261 V8_INLINE ExternalStringResourceBase* GetExternalStringResourceBase(
2262 Encoding* encoding_out) const;
2265 * Get the ExternalStringResource for an external string. Returns
2266 * NULL if IsExternal() doesn't return true.
2268 V8_INLINE ExternalStringResource* GetExternalStringResource() const;
2271 * Get the ExternalOneByteStringResource for an external one-byte string.
2272 * Returns NULL if IsExternalOneByte() doesn't return true.
2274 const ExternalOneByteStringResource* GetExternalOneByteStringResource() const;
2276 V8_INLINE static String* Cast(v8::Value* obj);
2278 // TODO(dcarney): remove with deprecation of New functions.
2279 enum NewStringType {
2280 kNormalString = static_cast<int>(v8::NewStringType::kNormal),
2281 kInternalizedString = static_cast<int>(v8::NewStringType::kInternalized)
2284 /** Allocates a new string from UTF-8 data.*/
2285 static V8_DEPRECATE_SOON(
2286 "Use maybe version",
2287 Local<String> NewFromUtf8(Isolate* isolate, const char* data,
2288 NewStringType type = kNormalString,
2291 /** Allocates a new string from UTF-8 data. Only returns an empty value when
2292 * length > kMaxLength. **/
2293 static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewFromUtf8(
2294 Isolate* isolate, const char* data, v8::NewStringType type,
2297 /** Allocates a new string from Latin-1 data.*/
2298 static V8_DEPRECATE_SOON(
2299 "Use maybe version",
2300 Local<String> NewFromOneByte(Isolate* isolate, const uint8_t* data,
2301 NewStringType type = kNormalString,
2304 /** Allocates a new string from Latin-1 data. Only returns an empty value
2305 * when length > kMaxLength. **/
2306 static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewFromOneByte(
2307 Isolate* isolate, const uint8_t* data, v8::NewStringType type,
2310 /** Allocates a new string from UTF-16 data.*/
2311 static V8_DEPRECATE_SOON(
2312 "Use maybe version",
2313 Local<String> NewFromTwoByte(Isolate* isolate, const uint16_t* data,
2314 NewStringType type = kNormalString,
2317 /** Allocates a new string from UTF-16 data. Only returns an empty value when
2318 * length > kMaxLength. **/
2319 static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewFromTwoByte(
2320 Isolate* isolate, const uint16_t* data, v8::NewStringType type,
2324 * Creates a new string by concatenating the left and the right strings
2325 * passed in as parameters.
2327 static Local<String> Concat(Local<String> left, Local<String> right);
2330 * Creates a new external string using the data defined in the given
2331 * resource. When the external string is no longer live on V8's heap the
2332 * resource will be disposed by calling its Dispose method. The caller of
2333 * this function should not otherwise delete or modify the resource. Neither
2334 * should the underlying buffer be deallocated or modified except through the
2335 * destructor of the external string resource.
2337 static V8_DEPRECATE_SOON(
2338 "Use maybe version",
2339 Local<String> NewExternal(Isolate* isolate,
2340 ExternalStringResource* resource));
2341 static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewExternalTwoByte(
2342 Isolate* isolate, ExternalStringResource* resource);
2345 * Associate an external string resource with this string by transforming it
2346 * in place so that existing references to this string in the JavaScript heap
2347 * will use the external string resource. The external string resource's
2348 * character contents need to be equivalent to this string.
2349 * Returns true if the string has been changed to be an external string.
2350 * The string is not modified if the operation fails. See NewExternal for
2351 * information on the lifetime of the resource.
2353 bool MakeExternal(ExternalStringResource* resource);
2356 * Creates a new external string using the one-byte data defined in the given
2357 * resource. When the external string is no longer live on V8's heap the
2358 * resource will be disposed by calling its Dispose method. The caller of
2359 * this function should not otherwise delete or modify the resource. Neither
2360 * should the underlying buffer be deallocated or modified except through the
2361 * destructor of the external string resource.
2363 static V8_DEPRECATE_SOON(
2364 "Use maybe version",
2365 Local<String> NewExternal(Isolate* isolate,
2366 ExternalOneByteStringResource* resource));
2367 static V8_WARN_UNUSED_RESULT MaybeLocal<String> NewExternalOneByte(
2368 Isolate* isolate, ExternalOneByteStringResource* resource);
2371 * Associate an external string resource with this string by transforming it
2372 * in place so that existing references to this string in the JavaScript heap
2373 * will use the external string resource. The external string resource's
2374 * character contents need to be equivalent to this string.
2375 * Returns true if the string has been changed to be an external string.
2376 * The string is not modified if the operation fails. See NewExternal for
2377 * information on the lifetime of the resource.
2379 bool MakeExternal(ExternalOneByteStringResource* resource);
2382 * Returns true if this string can be made external.
2384 bool CanMakeExternal();
2387 * Converts an object to a UTF-8-encoded character array. Useful if
2388 * you want to print the object. If conversion to a string fails
2389 * (e.g. due to an exception in the toString() method of the object)
2390 * then the length() method returns 0 and the * operator returns
2393 class V8_EXPORT Utf8Value {
2395 explicit Utf8Value(Local<v8::Value> obj);
2397 char* operator*() { return str_; }
2398 const char* operator*() const { return str_; }
2399 int length() const { return length_; }
2404 // Disallow copying and assigning.
2405 Utf8Value(const Utf8Value&);
2406 void operator=(const Utf8Value&);
2410 * Converts an object to a two-byte string.
2411 * If conversion to a string fails (eg. due to an exception in the toString()
2412 * method of the object) then the length() method returns 0 and the * operator
2415 class V8_EXPORT Value {
2417 explicit Value(Local<v8::Value> obj);
2419 uint16_t* operator*() { return str_; }
2420 const uint16_t* operator*() const { return str_; }
2421 int length() const { return length_; }
2426 // Disallow copying and assigning.
2427 Value(const Value&);
2428 void operator=(const Value&);
2432 void VerifyExternalStringResourceBase(ExternalStringResourceBase* v,
2433 Encoding encoding) const;
2434 void VerifyExternalStringResource(ExternalStringResource* val) const;
2435 static void CheckCast(v8::Value* obj);
2440 * A JavaScript symbol (ECMA-262 edition 6)
2442 * This is an experimental feature. Use at your own risk.
2444 class V8_EXPORT Symbol : public Name {
2446 // Returns the print name string of the symbol, or undefined if none.
2447 Local<Value> Name() const;
2449 // Create a symbol. If name is not empty, it will be used as the description.
2450 static Local<Symbol> New(
2451 Isolate *isolate, Local<String> name = Local<String>());
2453 // Access global symbol registry.
2454 // Note that symbols created this way are never collected, so
2455 // they should only be used for statically fixed properties.
2456 // Also, there is only one global name space for the names used as keys.
2457 // To minimize the potential for clashes, use qualified names as keys.
2458 static Local<Symbol> For(Isolate *isolate, Local<String> name);
2460 // Retrieve a global symbol. Similar to |For|, but using a separate
2461 // registry that is not accessible by (and cannot clash with) JavaScript code.
2462 static Local<Symbol> ForApi(Isolate *isolate, Local<String> name);
2464 // Well-known symbols
2465 static Local<Symbol> GetIterator(Isolate* isolate);
2466 static Local<Symbol> GetUnscopables(Isolate* isolate);
2467 static Local<Symbol> GetToStringTag(Isolate* isolate);
2469 V8_INLINE static Symbol* Cast(v8::Value* obj);
2473 static void CheckCast(v8::Value* obj);
2478 * A JavaScript number value (ECMA-262, 4.3.20)
2480 class V8_EXPORT Number : public Primitive {
2482 double Value() const;
2483 static Local<Number> New(Isolate* isolate, double value);
2484 V8_INLINE static Number* Cast(v8::Value* obj);
2487 static void CheckCast(v8::Value* obj);
2492 * A JavaScript value representing a signed integer.
2494 class V8_EXPORT Integer : public Number {
2496 static Local<Integer> New(Isolate* isolate, int32_t value);
2497 static Local<Integer> NewFromUnsigned(Isolate* isolate, uint32_t value);
2498 int64_t Value() const;
2499 V8_INLINE static Integer* Cast(v8::Value* obj);
2502 static void CheckCast(v8::Value* obj);
2507 * A JavaScript value representing a 32-bit signed integer.
2509 class V8_EXPORT Int32 : public Integer {
2511 int32_t Value() const;
2512 V8_INLINE static Int32* Cast(v8::Value* obj);
2516 static void CheckCast(v8::Value* obj);
2521 * A JavaScript value representing a 32-bit unsigned integer.
2523 class V8_EXPORT Uint32 : public Integer {
2525 uint32_t Value() const;
2526 V8_INLINE static Uint32* Cast(v8::Value* obj);
2530 static void CheckCast(v8::Value* obj);
2534 enum PropertyAttribute {
2542 * Accessor[Getter|Setter] are used as callback functions when
2543 * setting|getting a particular property. See Object and ObjectTemplate's
2544 * method SetAccessor.
2546 typedef void (*AccessorGetterCallback)(
2547 Local<String> property,
2548 const PropertyCallbackInfo<Value>& info);
2549 typedef void (*AccessorNameGetterCallback)(
2550 Local<Name> property,
2551 const PropertyCallbackInfo<Value>& info);
2554 typedef void (*AccessorSetterCallback)(
2555 Local<String> property,
2557 const PropertyCallbackInfo<void>& info);
2558 typedef void (*AccessorNameSetterCallback)(
2559 Local<Name> property,
2561 const PropertyCallbackInfo<void>& info);
2565 * Access control specifications.
2567 * Some accessors should be accessible across contexts. These
2568 * accessors have an explicit access control parameter which specifies
2569 * the kind of cross-context access that should be allowed.
2571 * TODO(dcarney): Remove PROHIBITS_OVERWRITING as it is now unused.
2573 enum AccessControl {
2576 ALL_CAN_WRITE = 1 << 1,
2577 PROHIBITS_OVERWRITING = 1 << 2
2582 * A JavaScript object (ECMA-262, 4.3.3)
2584 class V8_EXPORT Object : public Value {
2586 V8_DEPRECATE_SOON("Use maybe version",
2587 bool Set(Local<Value> key, Local<Value> value));
2588 V8_WARN_UNUSED_RESULT Maybe<bool> Set(Local<Context> context,
2589 Local<Value> key, Local<Value> value);
2591 V8_DEPRECATE_SOON("Use maybe version",
2592 bool Set(uint32_t index, Local<Value> value));
2593 V8_WARN_UNUSED_RESULT Maybe<bool> Set(Local<Context> context, uint32_t index,
2594 Local<Value> value);
2596 // Implements CreateDataProperty (ECMA-262, 7.3.4).
2598 // Defines a configurable, writable, enumerable property with the given value
2599 // on the object unless the property already exists and is not configurable
2600 // or the object is not extensible.
2602 // Returns true on success.
2603 V8_WARN_UNUSED_RESULT Maybe<bool> CreateDataProperty(Local<Context> context,
2605 Local<Value> value);
2606 V8_WARN_UNUSED_RESULT Maybe<bool> CreateDataProperty(Local<Context> context,
2608 Local<Value> value);
2610 // Implements DefineOwnProperty.
2612 // In general, CreateDataProperty will be faster, however, does not allow
2613 // for specifying attributes.
2615 // Returns true on success.
2616 V8_WARN_UNUSED_RESULT Maybe<bool> DefineOwnProperty(
2617 Local<Context> context, Local<Name> key, Local<Value> value,
2618 PropertyAttribute attributes = None);
2620 // Sets an own property on this object bypassing interceptors and
2621 // overriding accessors or read-only properties.
2623 // Note that if the object has an interceptor the property will be set
2624 // locally, but since the interceptor takes precedence the local property
2625 // will only be returned if the interceptor doesn't return a value.
2627 // Note also that this only works for named properties.
2628 V8_DEPRECATE_SOON("Use CreateDataProperty",
2629 bool ForceSet(Local<Value> key, Local<Value> value,
2630 PropertyAttribute attribs = None));
2631 V8_DEPRECATE_SOON("Use CreateDataProperty",
2632 Maybe<bool> ForceSet(Local<Context> context,
2633 Local<Value> key, Local<Value> value,
2634 PropertyAttribute attribs = None));
2636 V8_DEPRECATE_SOON("Use maybe version", Local<Value> Get(Local<Value> key));
2637 V8_WARN_UNUSED_RESULT MaybeLocal<Value> Get(Local<Context> context,
2640 V8_DEPRECATE_SOON("Use maybe version", Local<Value> Get(uint32_t index));
2641 V8_WARN_UNUSED_RESULT MaybeLocal<Value> Get(Local<Context> context,
2645 * Gets the property attributes of a property which can be None or
2646 * any combination of ReadOnly, DontEnum and DontDelete. Returns
2647 * None when the property doesn't exist.
2649 V8_DEPRECATE_SOON("Use maybe version",
2650 PropertyAttribute GetPropertyAttributes(Local<Value> key));
2651 V8_WARN_UNUSED_RESULT Maybe<PropertyAttribute> GetPropertyAttributes(
2652 Local<Context> context, Local<Value> key);
2655 * Returns Object.getOwnPropertyDescriptor as per ES5 section 15.2.3.3.
2657 V8_DEPRECATE_SOON("Use maybe version",
2658 Local<Value> GetOwnPropertyDescriptor(Local<String> key));
2659 V8_WARN_UNUSED_RESULT MaybeLocal<Value> GetOwnPropertyDescriptor(
2660 Local<Context> context, Local<String> key);
2662 V8_DEPRECATE_SOON("Use maybe version", bool Has(Local<Value> key));
2663 V8_WARN_UNUSED_RESULT Maybe<bool> Has(Local<Context> context,
2666 V8_DEPRECATE_SOON("Use maybe version", bool Delete(Local<Value> key));
2667 // TODO(dcarney): mark V8_WARN_UNUSED_RESULT
2668 Maybe<bool> Delete(Local<Context> context, Local<Value> key);
2670 V8_DEPRECATE_SOON("Use maybe version", bool Has(uint32_t index));
2671 V8_WARN_UNUSED_RESULT Maybe<bool> Has(Local<Context> context, uint32_t index);
2673 V8_DEPRECATE_SOON("Use maybe version", bool Delete(uint32_t index));
2674 // TODO(dcarney): mark V8_WARN_UNUSED_RESULT
2675 Maybe<bool> Delete(Local<Context> context, uint32_t index);
2677 V8_DEPRECATE_SOON("Use maybe version",
2678 bool SetAccessor(Local<String> name,
2679 AccessorGetterCallback getter,
2680 AccessorSetterCallback setter = 0,
2681 Local<Value> data = Local<Value>(),
2682 AccessControl settings = DEFAULT,
2683 PropertyAttribute attribute = None));
2684 V8_DEPRECATE_SOON("Use maybe version",
2685 bool SetAccessor(Local<Name> name,
2686 AccessorNameGetterCallback getter,
2687 AccessorNameSetterCallback setter = 0,
2688 Local<Value> data = Local<Value>(),
2689 AccessControl settings = DEFAULT,
2690 PropertyAttribute attribute = None));
2691 // TODO(dcarney): mark V8_WARN_UNUSED_RESULT
2692 Maybe<bool> SetAccessor(Local<Context> context, Local<Name> name,
2693 AccessorNameGetterCallback getter,
2694 AccessorNameSetterCallback setter = 0,
2695 MaybeLocal<Value> data = MaybeLocal<Value>(),
2696 AccessControl settings = DEFAULT,
2697 PropertyAttribute attribute = None);
2699 void SetAccessorProperty(Local<Name> name, Local<Function> getter,
2700 Local<Function> setter = Local<Function>(),
2701 PropertyAttribute attribute = None,
2702 AccessControl settings = DEFAULT);
2705 * Returns an array containing the names of the enumerable properties
2706 * of this object, including properties from prototype objects. The
2707 * array returned by this method contains the same values as would
2708 * be enumerated by a for-in statement over this object.
2710 V8_DEPRECATE_SOON("Use maybe version", Local<Array> GetPropertyNames());
2711 V8_WARN_UNUSED_RESULT MaybeLocal<Array> GetPropertyNames(
2712 Local<Context> context);
2715 * This function has the same functionality as GetPropertyNames but
2716 * the returned array doesn't contain the names of properties from
2717 * prototype objects.
2719 V8_DEPRECATE_SOON("Use maybe version", Local<Array> GetOwnPropertyNames());
2720 V8_WARN_UNUSED_RESULT MaybeLocal<Array> GetOwnPropertyNames(
2721 Local<Context> context);
2724 * Get the prototype object. This does not skip objects marked to
2725 * be skipped by __proto__ and it does not consult the security
2728 Local<Value> GetPrototype();
2731 * Set the prototype object. This does not skip objects marked to
2732 * be skipped by __proto__ and it does not consult the security
2735 V8_DEPRECATE_SOON("Use maybe version",
2736 bool SetPrototype(Local<Value> prototype));
2737 V8_WARN_UNUSED_RESULT Maybe<bool> SetPrototype(Local<Context> context,
2738 Local<Value> prototype);
2741 * Finds an instance of the given function template in the prototype
2744 Local<Object> FindInstanceInPrototypeChain(Local<FunctionTemplate> tmpl);
2747 * Call builtin Object.prototype.toString on this object.
2748 * This is different from Value::ToString() that may call
2749 * user-defined toString function. This one does not.
2751 V8_DEPRECATE_SOON("Use maybe version", Local<String> ObjectProtoToString());
2752 V8_WARN_UNUSED_RESULT MaybeLocal<String> ObjectProtoToString(
2753 Local<Context> context);
2756 * Returns the name of the function invoked as a constructor for this object.
2758 Local<String> GetConstructorName();
2760 /** Gets the number of internal fields for this Object. */
2761 int InternalFieldCount();
2763 /** Same as above, but works for Persistents */
2764 V8_INLINE static int InternalFieldCount(
2765 const PersistentBase<Object>& object) {
2766 return object.val_->InternalFieldCount();
2769 /** Gets the value from an internal field. */
2770 V8_INLINE Local<Value> GetInternalField(int index);
2772 /** Sets the value in an internal field. */
2773 void SetInternalField(int index, Local<Value> value);
2776 * Gets a 2-byte-aligned native pointer from an internal field. This field
2777 * must have been set by SetAlignedPointerInInternalField, everything else
2778 * leads to undefined behavior.
2780 V8_INLINE void* GetAlignedPointerFromInternalField(int index);
2782 /** Same as above, but works for Persistents */
2783 V8_INLINE static void* GetAlignedPointerFromInternalField(
2784 const PersistentBase<Object>& object, int index) {
2785 return object.val_->GetAlignedPointerFromInternalField(index);
2789 * Sets a 2-byte-aligned native pointer in an internal field. To retrieve such
2790 * a field, GetAlignedPointerFromInternalField must be used, everything else
2791 * leads to undefined behavior.
2793 void SetAlignedPointerInInternalField(int index, void* value);
2795 // Testers for local properties.
2796 V8_DEPRECATE_SOON("Use maybe version",
2797 bool HasOwnProperty(Local<String> key));
2798 V8_WARN_UNUSED_RESULT Maybe<bool> HasOwnProperty(Local<Context> context,
2800 V8_DEPRECATE_SOON("Use maybe version",
2801 bool HasRealNamedProperty(Local<String> key));
2802 V8_WARN_UNUSED_RESULT Maybe<bool> HasRealNamedProperty(Local<Context> context,
2804 V8_DEPRECATE_SOON("Use maybe version",
2805 bool HasRealIndexedProperty(uint32_t index));
2806 V8_WARN_UNUSED_RESULT Maybe<bool> HasRealIndexedProperty(
2807 Local<Context> context, uint32_t index);
2808 V8_DEPRECATE_SOON("Use maybe version",
2809 bool HasRealNamedCallbackProperty(Local<String> key));
2810 V8_WARN_UNUSED_RESULT Maybe<bool> HasRealNamedCallbackProperty(
2811 Local<Context> context, Local<Name> key);
2814 * If result.IsEmpty() no real property was located in the prototype chain.
2815 * This means interceptors in the prototype chain are not called.
2818 "Use maybe version",
2819 Local<Value> GetRealNamedPropertyInPrototypeChain(Local<String> key));
2820 V8_WARN_UNUSED_RESULT MaybeLocal<Value> GetRealNamedPropertyInPrototypeChain(
2821 Local<Context> context, Local<Name> key);
2824 * Gets the property attributes of a real property in the prototype chain,
2825 * which can be None or any combination of ReadOnly, DontEnum and DontDelete.
2826 * Interceptors in the prototype chain are not called.
2829 "Use maybe version",
2830 Maybe<PropertyAttribute> GetRealNamedPropertyAttributesInPrototypeChain(
2831 Local<String> key));
2832 V8_WARN_UNUSED_RESULT Maybe<PropertyAttribute>
2833 GetRealNamedPropertyAttributesInPrototypeChain(Local<Context> context,
2837 * If result.IsEmpty() no real property was located on the object or
2838 * in the prototype chain.
2839 * This means interceptors in the prototype chain are not called.
2841 V8_DEPRECATE_SOON("Use maybe version",
2842 Local<Value> GetRealNamedProperty(Local<String> key));
2843 V8_WARN_UNUSED_RESULT MaybeLocal<Value> GetRealNamedProperty(
2844 Local<Context> context, Local<Name> key);
2847 * Gets the property attributes of a real property which can be
2848 * None or any combination of ReadOnly, DontEnum and DontDelete.
2849 * Interceptors in the prototype chain are not called.
2851 V8_DEPRECATE_SOON("Use maybe version",
2852 Maybe<PropertyAttribute> GetRealNamedPropertyAttributes(
2853 Local<String> key));
2854 V8_WARN_UNUSED_RESULT Maybe<PropertyAttribute> GetRealNamedPropertyAttributes(
2855 Local<Context> context, Local<Name> key);
2857 /** Tests for a named lookup interceptor.*/
2858 bool HasNamedLookupInterceptor();
2860 /** Tests for an index lookup interceptor.*/
2861 bool HasIndexedLookupInterceptor();
2864 * Returns the identity hash for this object. The current implementation
2865 * uses a hidden property on the object to store the identity hash.
2867 * The return value will never be 0. Also, it is not guaranteed to be
2870 int GetIdentityHash();
2873 * Access hidden properties on JavaScript objects. These properties are
2874 * hidden from the executing JavaScript and only accessible through the V8
2875 * C++ API. Hidden properties introduced by V8 internally (for example the
2876 * identity hash) are prefixed with "v8::".
2878 // TODO(dcarney): convert these to take a isolate and optionally bailout?
2879 bool SetHiddenValue(Local<String> key, Local<Value> value);
2880 Local<Value> GetHiddenValue(Local<String> key);
2881 bool DeleteHiddenValue(Local<String> key);
2884 * Clone this object with a fast but shallow copy. Values will point
2885 * to the same values as the original object.
2887 // TODO(dcarney): take an isolate and optionally bail out?
2888 Local<Object> Clone();
2891 * Returns the context in which the object was created.
2893 Local<Context> CreationContext();
2896 * Checks whether a callback is set by the
2897 * ObjectTemplate::SetCallAsFunctionHandler method.
2898 * When an Object is callable this method returns true.
2903 * Call an Object as a function if a callback is set by the
2904 * ObjectTemplate::SetCallAsFunctionHandler method.
2906 V8_DEPRECATE_SOON("Use maybe version",
2907 Local<Value> CallAsFunction(Local<Value> recv, int argc,
2908 Local<Value> argv[]));
2909 V8_WARN_UNUSED_RESULT MaybeLocal<Value> CallAsFunction(Local<Context> context,
2912 Local<Value> argv[]);
2915 * Call an Object as a constructor if a callback is set by the
2916 * ObjectTemplate::SetCallAsFunctionHandler method.
2917 * Note: This method behaves like the Function::NewInstance method.
2919 V8_DEPRECATE_SOON("Use maybe version",
2920 Local<Value> CallAsConstructor(int argc,
2921 Local<Value> argv[]));
2922 V8_WARN_UNUSED_RESULT MaybeLocal<Value> CallAsConstructor(
2923 Local<Context> context, int argc, Local<Value> argv[]);
2926 * Return the isolate to which the Object belongs to.
2928 V8_DEPRECATE_SOON("Keep track of isolate correctly", Isolate* GetIsolate());
2930 static Local<Object> New(Isolate* isolate);
2932 V8_INLINE static Object* Cast(Value* obj);
2936 static void CheckCast(Value* obj);
2937 Local<Value> SlowGetInternalField(int index);
2938 void* SlowGetAlignedPointerFromInternalField(int index);
2943 * An instance of the built-in array constructor (ECMA-262, 15.4.2).
2945 class V8_EXPORT Array : public Object {
2947 uint32_t Length() const;
2950 * Clones an element at index |index|. Returns an empty
2951 * handle if cloning fails (for any reason).
2953 V8_DEPRECATE_SOON("Use maybe version",
2954 Local<Object> CloneElementAt(uint32_t index));
2955 V8_WARN_UNUSED_RESULT MaybeLocal<Object> CloneElementAt(
2956 Local<Context> context, uint32_t index);
2959 * Creates a JavaScript array with the given length. If the length
2960 * is negative the returned array will have length 0.
2962 static Local<Array> New(Isolate* isolate, int length = 0);
2964 V8_INLINE static Array* Cast(Value* obj);
2967 static void CheckCast(Value* obj);
2972 * An instance of the built-in Map constructor (ECMA-262, 6th Edition, 23.1.1).
2974 class V8_EXPORT Map : public Object {
2976 size_t Size() const;
2978 V8_WARN_UNUSED_RESULT MaybeLocal<Value> Get(Local<Context> context,
2980 V8_WARN_UNUSED_RESULT MaybeLocal<Map> Set(Local<Context> context,
2982 Local<Value> value);
2983 V8_WARN_UNUSED_RESULT Maybe<bool> Has(Local<Context> context,
2985 V8_WARN_UNUSED_RESULT Maybe<bool> Delete(Local<Context> context,
2989 * Returns an array of length Size() * 2, where index N is the Nth key and
2990 * index N + 1 is the Nth value.
2992 Local<Array> AsArray() const;
2995 * Creates a new empty Map.
2997 static Local<Map> New(Isolate* isolate);
3000 * Creates a new Map containing the elements of array, which must be formatted
3001 * in the same manner as the array returned from AsArray().
3002 * Guaranteed to be side-effect free if the array contains no holes.
3004 static V8_WARN_UNUSED_RESULT V8_DEPRECATED(
3005 "Use mutation methods instead",
3006 MaybeLocal<Map> FromArray(Local<Context> context, Local<Array> array));
3008 V8_INLINE static Map* Cast(Value* obj);
3012 static void CheckCast(Value* obj);
3017 * An instance of the built-in Set constructor (ECMA-262, 6th Edition, 23.2.1).
3019 class V8_EXPORT Set : public Object {
3021 size_t Size() const;
3023 V8_WARN_UNUSED_RESULT MaybeLocal<Set> Add(Local<Context> context,
3025 V8_WARN_UNUSED_RESULT Maybe<bool> Has(Local<Context> context,
3027 V8_WARN_UNUSED_RESULT Maybe<bool> Delete(Local<Context> context,
3031 * Returns an array of the keys in this Set.
3033 Local<Array> AsArray() const;
3036 * Creates a new empty Set.
3038 static Local<Set> New(Isolate* isolate);
3041 * Creates a new Set containing the items in array.
3042 * Guaranteed to be side-effect free if the array contains no holes.
3044 static V8_WARN_UNUSED_RESULT V8_DEPRECATED(
3045 "Use mutation methods instead",
3046 MaybeLocal<Set> FromArray(Local<Context> context, Local<Array> array));
3048 V8_INLINE static Set* Cast(Value* obj);
3052 static void CheckCast(Value* obj);
3056 template<typename T>
3059 template <class S> V8_INLINE ReturnValue(const ReturnValue<S>& that)
3060 : value_(that.value_) {
3064 template <typename S>
3065 V8_INLINE V8_DEPRECATE_SOON("Use Global<> instead",
3066 void Set(const Persistent<S>& handle));
3067 template <typename S>
3068 V8_INLINE void Set(const Global<S>& handle);
3069 template <typename S>
3070 V8_INLINE void Set(const Local<S> handle);
3071 // Fast primitive setters
3072 V8_INLINE void Set(bool value);
3073 V8_INLINE void Set(double i);
3074 V8_INLINE void Set(int32_t i);
3075 V8_INLINE void Set(uint32_t i);
3076 // Fast JS primitive setters
3077 V8_INLINE void SetNull();
3078 V8_INLINE void SetUndefined();
3079 V8_INLINE void SetEmptyString();
3080 // Convenience getter for Isolate
3081 V8_INLINE Isolate* GetIsolate();
3083 // Pointer setter: Uncompilable to prevent inadvertent misuse.
3084 template <typename S>
3085 V8_INLINE void Set(S* whatever);
3088 template<class F> friend class ReturnValue;
3089 template<class F> friend class FunctionCallbackInfo;
3090 template<class F> friend class PropertyCallbackInfo;
3091 template <class F, class G, class H>
3092 friend class PersistentValueMapBase;
3093 V8_INLINE void SetInternal(internal::Object* value) { *value_ = value; }
3094 V8_INLINE internal::Object* GetDefaultValue();
3095 V8_INLINE explicit ReturnValue(internal::Object** slot);
3096 internal::Object** value_;
3101 * The argument information given to function call callbacks. This
3102 * class provides access to information about the context of the call,
3103 * including the receiver, the number and values of arguments, and
3104 * the holder of the function.
3106 template<typename T>
3107 class FunctionCallbackInfo {
3109 V8_INLINE int Length() const;
3110 V8_INLINE Local<Value> operator[](int i) const;
3111 V8_INLINE Local<Function> Callee() const;
3112 V8_INLINE Local<Object> This() const;
3113 V8_INLINE Local<Object> Holder() const;
3114 V8_INLINE bool IsConstructCall() const;
3115 V8_INLINE Local<Value> Data() const;
3116 V8_INLINE Isolate* GetIsolate() const;
3117 V8_INLINE ReturnValue<T> GetReturnValue() const;
3118 // This shouldn't be public, but the arm compiler needs it.
3119 static const int kArgsLength = 7;
3122 friend class internal::FunctionCallbackArguments;
3123 friend class internal::CustomArguments<FunctionCallbackInfo>;
3124 static const int kHolderIndex = 0;
3125 static const int kIsolateIndex = 1;
3126 static const int kReturnValueDefaultValueIndex = 2;
3127 static const int kReturnValueIndex = 3;
3128 static const int kDataIndex = 4;
3129 static const int kCalleeIndex = 5;
3130 static const int kContextSaveIndex = 6;
3132 V8_INLINE FunctionCallbackInfo(internal::Object** implicit_args,
3133 internal::Object** values,
3135 bool is_construct_call);
3136 internal::Object** implicit_args_;
3137 internal::Object** values_;
3139 int is_construct_call_;
3144 * The information passed to a property callback about the context
3145 * of the property access.
3147 template<typename T>
3148 class PropertyCallbackInfo {
3150 V8_INLINE Isolate* GetIsolate() const;
3151 V8_INLINE Local<Value> Data() const;
3152 V8_INLINE Local<Object> This() const;
3153 V8_INLINE Local<Object> Holder() const;
3154 V8_INLINE ReturnValue<T> GetReturnValue() const;
3155 // This shouldn't be public, but the arm compiler needs it.
3156 static const int kArgsLength = 6;
3159 friend class MacroAssembler;
3160 friend class internal::PropertyCallbackArguments;
3161 friend class internal::CustomArguments<PropertyCallbackInfo>;
3162 static const int kHolderIndex = 0;
3163 static const int kIsolateIndex = 1;
3164 static const int kReturnValueDefaultValueIndex = 2;
3165 static const int kReturnValueIndex = 3;
3166 static const int kDataIndex = 4;
3167 static const int kThisIndex = 5;
3169 V8_INLINE PropertyCallbackInfo(internal::Object** args) : args_(args) {}
3170 internal::Object** args_;
3174 typedef void (*FunctionCallback)(const FunctionCallbackInfo<Value>& info);
3178 * A JavaScript function object (ECMA-262, 15.3).
3180 class V8_EXPORT Function : public Object {
3183 * Create a function in the current execution context
3184 * for a given FunctionCallback.
3186 static MaybeLocal<Function> New(Local<Context> context,
3187 FunctionCallback callback,
3188 Local<Value> data = Local<Value>(),
3190 static V8_DEPRECATE_SOON(
3191 "Use maybe version",
3192 Local<Function> New(Isolate* isolate, FunctionCallback callback,
3193 Local<Value> data = Local<Value>(), int length = 0));
3195 V8_DEPRECATE_SOON("Use maybe version",
3196 Local<Object> NewInstance(int argc, Local<Value> argv[])
3198 V8_WARN_UNUSED_RESULT MaybeLocal<Object> NewInstance(
3199 Local<Context> context, int argc, Local<Value> argv[]) const;
3201 V8_DEPRECATE_SOON("Use maybe version", Local<Object> NewInstance() const);
3202 V8_WARN_UNUSED_RESULT MaybeLocal<Object> NewInstance(
3203 Local<Context> context) const {
3204 return NewInstance(context, 0, nullptr);
3207 V8_DEPRECATE_SOON("Use maybe version",
3208 Local<Value> Call(Local<Value> recv, int argc,
3209 Local<Value> argv[]));
3210 V8_WARN_UNUSED_RESULT MaybeLocal<Value> Call(Local<Context> context,
3211 Local<Value> recv, int argc,
3212 Local<Value> argv[]);
3214 void SetName(Local<String> name);
3215 Local<Value> GetName() const;
3218 * Name inferred from variable or property assignment of this function.
3219 * Used to facilitate debugging and profiling of JavaScript code written
3220 * in an OO style, where many functions are anonymous but are assigned
3221 * to object properties.
3223 Local<Value> GetInferredName() const;
3226 * User-defined name assigned to the "displayName" property of this function.
3227 * Used to facilitate debugging and profiling of JavaScript code.
3229 Local<Value> GetDisplayName() const;
3232 * Returns zero based line number of function body and
3233 * kLineOffsetNotFound if no information available.
3235 int GetScriptLineNumber() const;
3237 * Returns zero based column number of function body and
3238 * kLineOffsetNotFound if no information available.
3240 int GetScriptColumnNumber() const;
3243 * Tells whether this function is builtin.
3245 bool IsBuiltin() const;
3250 int ScriptId() const;
3253 * Returns the original function if this function is bound, else returns
3256 Local<Value> GetBoundFunction() const;
3258 ScriptOrigin GetScriptOrigin() const;
3259 V8_INLINE static Function* Cast(Value* obj);
3260 static const int kLineOffsetNotFound;
3264 static void CheckCast(Value* obj);
3269 * An instance of the built-in Promise constructor (ES6 draft).
3270 * This API is experimental. Only works with --harmony flag.
3272 class V8_EXPORT Promise : public Object {
3274 class V8_EXPORT Resolver : public Object {
3277 * Create a new resolver, along with an associated promise in pending state.
3279 static V8_DEPRECATE_SOON("Use maybe version",
3280 Local<Resolver> New(Isolate* isolate));
3281 static V8_WARN_UNUSED_RESULT MaybeLocal<Resolver> New(
3282 Local<Context> context);
3285 * Extract the associated promise.
3287 Local<Promise> GetPromise();
3290 * Resolve/reject the associated promise with a given value.
3291 * Ignored if the promise is no longer pending.
3293 V8_DEPRECATE_SOON("Use maybe version", void Resolve(Local<Value> value));
3294 // TODO(dcarney): mark V8_WARN_UNUSED_RESULT
3295 Maybe<bool> Resolve(Local<Context> context, Local<Value> value);
3297 V8_DEPRECATE_SOON("Use maybe version", void Reject(Local<Value> value));
3298 // TODO(dcarney): mark V8_WARN_UNUSED_RESULT
3299 Maybe<bool> Reject(Local<Context> context, Local<Value> value);
3301 V8_INLINE static Resolver* Cast(Value* obj);
3305 static void CheckCast(Value* obj);
3309 * Register a resolution/rejection handler with a promise.
3310 * The handler is given the respective resolution/rejection value as
3311 * an argument. If the promise is already resolved/rejected, the handler is
3312 * invoked at the end of turn.
3314 V8_DEPRECATE_SOON("Use maybe version",
3315 Local<Promise> Chain(Local<Function> handler));
3316 V8_WARN_UNUSED_RESULT MaybeLocal<Promise> Chain(Local<Context> context,
3317 Local<Function> handler);
3319 V8_DEPRECATE_SOON("Use maybe version",
3320 Local<Promise> Catch(Local<Function> handler));
3321 V8_WARN_UNUSED_RESULT MaybeLocal<Promise> Catch(Local<Context> context,
3322 Local<Function> handler);
3324 V8_DEPRECATE_SOON("Use maybe version",
3325 Local<Promise> Then(Local<Function> handler));
3326 V8_WARN_UNUSED_RESULT MaybeLocal<Promise> Then(Local<Context> context,
3327 Local<Function> handler);
3330 * Returns true if the promise has at least one derived promise, and
3331 * therefore resolve/reject handlers (including default handler).
3335 V8_INLINE static Promise* Cast(Value* obj);
3339 static void CheckCast(Value* obj);
3343 #ifndef V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT
3344 // The number of required internal fields can be defined by embedder.
3345 #define V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT 2
3349 enum class ArrayBufferCreationMode { kInternalized, kExternalized };
3353 * An instance of the built-in ArrayBuffer constructor (ES6 draft 15.13.5).
3354 * This API is experimental and may change significantly.
3356 class V8_EXPORT ArrayBuffer : public Object {
3359 * Allocator that V8 uses to allocate |ArrayBuffer|'s memory.
3360 * The allocator is a global V8 setting. It has to be set via
3361 * Isolate::CreateParams.
3363 * This API is experimental and may change significantly.
3365 class V8_EXPORT Allocator { // NOLINT
3367 virtual ~Allocator() {}
3370 * Allocate |length| bytes. Return NULL if allocation is not successful.
3371 * Memory should be initialized to zeroes.
3373 virtual void* Allocate(size_t length) = 0;
3376 * Allocate |length| bytes. Return NULL if allocation is not successful.
3377 * Memory does not have to be initialized.
3379 virtual void* AllocateUninitialized(size_t length) = 0;
3381 * Free the memory block of size |length|, pointed to by |data|.
3382 * That memory is guaranteed to be previously allocated by |Allocate|.
3384 virtual void Free(void* data, size_t length) = 0;
3388 * The contents of an |ArrayBuffer|. Externalization of |ArrayBuffer|
3389 * returns an instance of this class, populated, with a pointer to data
3392 * The Data pointer of ArrayBuffer::Contents is always allocated with
3393 * Allocator::Allocate that is set via Isolate::CreateParams.
3395 * This API is experimental and may change significantly.
3397 class V8_EXPORT Contents { // NOLINT
3399 Contents() : data_(NULL), byte_length_(0) {}
3401 void* Data() const { return data_; }
3402 size_t ByteLength() const { return byte_length_; }
3406 size_t byte_length_;
3408 friend class ArrayBuffer;
3413 * Data length in bytes.
3415 size_t ByteLength() const;
3418 * Create a new ArrayBuffer. Allocate |byte_length| bytes.
3419 * Allocated memory will be owned by a created ArrayBuffer and
3420 * will be deallocated when it is garbage-collected,
3421 * unless the object is externalized.
3423 static Local<ArrayBuffer> New(Isolate* isolate, size_t byte_length);
3426 * Create a new ArrayBuffer over an existing memory block.
3427 * The created array buffer is by default immediately in externalized state.
3428 * The memory block will not be reclaimed when a created ArrayBuffer
3429 * is garbage-collected.
3431 static Local<ArrayBuffer> New(
3432 Isolate* isolate, void* data, size_t byte_length,
3433 ArrayBufferCreationMode mode = ArrayBufferCreationMode::kExternalized);
3436 * Returns true if ArrayBuffer is externalized, that is, does not
3437 * own its memory block.
3439 bool IsExternal() const;
3442 * Returns true if this ArrayBuffer may be neutered.
3444 bool IsNeuterable() const;
3447 * Neuters this ArrayBuffer and all its views (typed arrays).
3448 * Neutering sets the byte length of the buffer and all typed arrays to zero,
3449 * preventing JavaScript from ever accessing underlying backing store.
3450 * ArrayBuffer should have been externalized and must be neuterable.
3455 * Make this ArrayBuffer external. The pointer to underlying memory block
3456 * and byte length are returned as |Contents| structure. After ArrayBuffer
3457 * had been etxrenalized, it does no longer owns the memory block. The caller
3458 * should take steps to free memory when it is no longer needed.
3460 * The memory block is guaranteed to be allocated with |Allocator::Allocate|
3461 * that has been set via Isolate::CreateParams.
3463 Contents Externalize();
3466 * Get a pointer to the ArrayBuffer's underlying memory block without
3467 * externalizing it. If the ArrayBuffer is not externalized, this pointer
3468 * will become invalid as soon as the ArrayBuffer became garbage collected.
3470 * The embedder should make sure to hold a strong reference to the
3471 * ArrayBuffer while accessing this pointer.
3473 * The memory block is guaranteed to be allocated with |Allocator::Allocate|.
3475 Contents GetContents();
3477 V8_INLINE static ArrayBuffer* Cast(Value* obj);
3479 static const int kInternalFieldCount = V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT;
3483 static void CheckCast(Value* obj);
3487 #ifndef V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT
3488 // The number of required internal fields can be defined by embedder.
3489 #define V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT 2
3494 * A base class for an instance of one of "views" over ArrayBuffer,
3495 * including TypedArrays and DataView (ES6 draft 15.13).
3497 * This API is experimental and may change significantly.
3499 class V8_EXPORT ArrayBufferView : public Object {
3502 * Returns underlying ArrayBuffer.
3504 Local<ArrayBuffer> Buffer();
3506 * Byte offset in |Buffer|.
3508 size_t ByteOffset();
3510 * Size of a view in bytes.
3512 size_t ByteLength();
3515 * Copy the contents of the ArrayBufferView's buffer to an embedder defined
3516 * memory without additional overhead that calling ArrayBufferView::Buffer
3519 * Will write at most min(|byte_length|, ByteLength) bytes starting at
3520 * ByteOffset of the underling buffer to the memory starting at |dest|.
3521 * Returns the number of bytes actually written.
3523 size_t CopyContents(void* dest, size_t byte_length);
3526 * Returns true if ArrayBufferView's backing ArrayBuffer has already been
3529 bool HasBuffer() const;
3531 V8_INLINE static ArrayBufferView* Cast(Value* obj);
3533 static const int kInternalFieldCount =
3534 V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT;
3538 static void CheckCast(Value* obj);
3543 * A base class for an instance of TypedArray series of constructors
3544 * (ES6 draft 15.13.6).
3545 * This API is experimental and may change significantly.
3547 class V8_EXPORT TypedArray : public ArrayBufferView {
3550 * Number of elements in this typed array
3551 * (e.g. for Int16Array, |ByteLength|/2).
3555 V8_INLINE static TypedArray* Cast(Value* obj);
3559 static void CheckCast(Value* obj);
3564 * An instance of Uint8Array constructor (ES6 draft 15.13.6).
3565 * This API is experimental and may change significantly.
3567 class V8_EXPORT Uint8Array : public TypedArray {
3569 static Local<Uint8Array> New(Local<ArrayBuffer> array_buffer,
3570 size_t byte_offset, size_t length);
3571 static Local<Uint8Array> New(Local<SharedArrayBuffer> shared_array_buffer,
3572 size_t byte_offset, size_t length);
3573 V8_INLINE static Uint8Array* Cast(Value* obj);
3577 static void CheckCast(Value* obj);
3582 * An instance of Uint8ClampedArray constructor (ES6 draft 15.13.6).
3583 * This API is experimental and may change significantly.
3585 class V8_EXPORT Uint8ClampedArray : public TypedArray {
3587 static Local<Uint8ClampedArray> New(Local<ArrayBuffer> array_buffer,
3588 size_t byte_offset, size_t length);
3589 static Local<Uint8ClampedArray> New(
3590 Local<SharedArrayBuffer> shared_array_buffer, size_t byte_offset,
3592 V8_INLINE static Uint8ClampedArray* Cast(Value* obj);
3595 Uint8ClampedArray();
3596 static void CheckCast(Value* obj);
3600 * An instance of Int8Array constructor (ES6 draft 15.13.6).
3601 * This API is experimental and may change significantly.
3603 class V8_EXPORT Int8Array : public TypedArray {
3605 static Local<Int8Array> New(Local<ArrayBuffer> array_buffer,
3606 size_t byte_offset, size_t length);
3607 static Local<Int8Array> New(Local<SharedArrayBuffer> shared_array_buffer,
3608 size_t byte_offset, size_t length);
3609 V8_INLINE static Int8Array* Cast(Value* obj);
3613 static void CheckCast(Value* obj);
3618 * An instance of Uint16Array constructor (ES6 draft 15.13.6).
3619 * This API is experimental and may change significantly.
3621 class V8_EXPORT Uint16Array : public TypedArray {
3623 static Local<Uint16Array> New(Local<ArrayBuffer> array_buffer,
3624 size_t byte_offset, size_t length);
3625 static Local<Uint16Array> New(Local<SharedArrayBuffer> shared_array_buffer,
3626 size_t byte_offset, size_t length);
3627 V8_INLINE static Uint16Array* Cast(Value* obj);
3631 static void CheckCast(Value* obj);
3636 * An instance of Int16Array constructor (ES6 draft 15.13.6).
3637 * This API is experimental and may change significantly.
3639 class V8_EXPORT Int16Array : public TypedArray {
3641 static Local<Int16Array> New(Local<ArrayBuffer> array_buffer,
3642 size_t byte_offset, size_t length);
3643 static Local<Int16Array> New(Local<SharedArrayBuffer> shared_array_buffer,
3644 size_t byte_offset, size_t length);
3645 V8_INLINE static Int16Array* Cast(Value* obj);
3649 static void CheckCast(Value* obj);
3654 * An instance of Uint32Array constructor (ES6 draft 15.13.6).
3655 * This API is experimental and may change significantly.
3657 class V8_EXPORT Uint32Array : public TypedArray {
3659 static Local<Uint32Array> New(Local<ArrayBuffer> array_buffer,
3660 size_t byte_offset, size_t length);
3661 static Local<Uint32Array> New(Local<SharedArrayBuffer> shared_array_buffer,
3662 size_t byte_offset, size_t length);
3663 V8_INLINE static Uint32Array* Cast(Value* obj);
3667 static void CheckCast(Value* obj);
3672 * An instance of Int32Array constructor (ES6 draft 15.13.6).
3673 * This API is experimental and may change significantly.
3675 class V8_EXPORT Int32Array : public TypedArray {
3677 static Local<Int32Array> New(Local<ArrayBuffer> array_buffer,
3678 size_t byte_offset, size_t length);
3679 static Local<Int32Array> New(Local<SharedArrayBuffer> shared_array_buffer,
3680 size_t byte_offset, size_t length);
3681 V8_INLINE static Int32Array* Cast(Value* obj);
3685 static void CheckCast(Value* obj);
3690 * An instance of Float32Array constructor (ES6 draft 15.13.6).
3691 * This API is experimental and may change significantly.
3693 class V8_EXPORT Float32Array : public TypedArray {
3695 static Local<Float32Array> New(Local<ArrayBuffer> array_buffer,
3696 size_t byte_offset, size_t length);
3697 static Local<Float32Array> New(Local<SharedArrayBuffer> shared_array_buffer,
3698 size_t byte_offset, size_t length);
3699 V8_INLINE static Float32Array* Cast(Value* obj);
3703 static void CheckCast(Value* obj);
3708 * An instance of Float64Array constructor (ES6 draft 15.13.6).
3709 * This API is experimental and may change significantly.
3711 class V8_EXPORT Float64Array : public TypedArray {
3713 static Local<Float64Array> New(Local<ArrayBuffer> array_buffer,
3714 size_t byte_offset, size_t length);
3715 static Local<Float64Array> New(Local<SharedArrayBuffer> shared_array_buffer,
3716 size_t byte_offset, size_t length);
3717 V8_INLINE static Float64Array* Cast(Value* obj);
3721 static void CheckCast(Value* obj);
3726 * An instance of DataView constructor (ES6 draft 15.13.7).
3727 * This API is experimental and may change significantly.
3729 class V8_EXPORT DataView : public ArrayBufferView {
3731 static Local<DataView> New(Local<ArrayBuffer> array_buffer,
3732 size_t byte_offset, size_t length);
3733 static Local<DataView> New(Local<SharedArrayBuffer> shared_array_buffer,
3734 size_t byte_offset, size_t length);
3735 V8_INLINE static DataView* Cast(Value* obj);
3739 static void CheckCast(Value* obj);
3744 * An instance of the built-in SharedArrayBuffer constructor.
3745 * This API is experimental and may change significantly.
3747 class V8_EXPORT SharedArrayBuffer : public Object {
3750 * The contents of an |SharedArrayBuffer|. Externalization of
3751 * |SharedArrayBuffer| returns an instance of this class, populated, with a
3752 * pointer to data and byte length.
3754 * The Data pointer of SharedArrayBuffer::Contents is always allocated with
3755 * |ArrayBuffer::Allocator::Allocate| by the allocator specified in
3756 * v8::Isolate::CreateParams::array_buffer_allocator.
3758 * This API is experimental and may change significantly.
3760 class V8_EXPORT Contents { // NOLINT
3762 Contents() : data_(NULL), byte_length_(0) {}
3764 void* Data() const { return data_; }
3765 size_t ByteLength() const { return byte_length_; }
3769 size_t byte_length_;
3771 friend class SharedArrayBuffer;
3776 * Data length in bytes.
3778 size_t ByteLength() const;
3781 * Create a new SharedArrayBuffer. Allocate |byte_length| bytes.
3782 * Allocated memory will be owned by a created SharedArrayBuffer and
3783 * will be deallocated when it is garbage-collected,
3784 * unless the object is externalized.
3786 static Local<SharedArrayBuffer> New(Isolate* isolate, size_t byte_length);
3789 * Create a new SharedArrayBuffer over an existing memory block. The created
3790 * array buffer is immediately in externalized state unless otherwise
3791 * specified. The memory block will not be reclaimed when a created
3792 * SharedArrayBuffer is garbage-collected.
3794 static Local<SharedArrayBuffer> New(
3795 Isolate* isolate, void* data, size_t byte_length,
3796 ArrayBufferCreationMode mode = ArrayBufferCreationMode::kExternalized);
3799 * Returns true if SharedArrayBuffer is externalized, that is, does not
3800 * own its memory block.
3802 bool IsExternal() const;
3805 * Make this SharedArrayBuffer external. The pointer to underlying memory
3806 * block and byte length are returned as |Contents| structure. After
3807 * SharedArrayBuffer had been etxrenalized, it does no longer owns the memory
3808 * block. The caller should take steps to free memory when it is no longer
3811 * The memory block is guaranteed to be allocated with |Allocator::Allocate|
3812 * by the allocator specified in
3813 * v8::Isolate::CreateParams::array_buffer_allocator.
3816 Contents Externalize();
3819 * Get a pointer to the ArrayBuffer's underlying memory block without
3820 * externalizing it. If the ArrayBuffer is not externalized, this pointer
3821 * will become invalid as soon as the ArrayBuffer became garbage collected.
3823 * The embedder should make sure to hold a strong reference to the
3824 * ArrayBuffer while accessing this pointer.
3826 * The memory block is guaranteed to be allocated with |Allocator::Allocate|
3827 * by the allocator specified in
3828 * v8::Isolate::CreateParams::array_buffer_allocator.
3830 Contents GetContents();
3832 V8_INLINE static SharedArrayBuffer* Cast(Value* obj);
3834 static const int kInternalFieldCount = V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT;
3837 SharedArrayBuffer();
3838 static void CheckCast(Value* obj);
3843 * An instance of the built-in Date constructor (ECMA-262, 15.9).
3845 class V8_EXPORT Date : public Object {
3847 static V8_DEPRECATE_SOON("Use maybe version.",
3848 Local<Value> New(Isolate* isolate, double time));
3849 static V8_WARN_UNUSED_RESULT MaybeLocal<Value> New(Local<Context> context,
3853 * A specialization of Value::NumberValue that is more efficient
3854 * because we know the structure of this object.
3856 double ValueOf() const;
3858 V8_INLINE static Date* Cast(v8::Value* obj);
3861 * Notification that the embedder has changed the time zone,
3862 * daylight savings time, or other date / time configuration
3863 * parameters. V8 keeps a cache of various values used for
3864 * date / time computation. This notification will reset
3865 * those cached values for the current context so that date /
3866 * time configuration changes would be reflected in the Date
3869 * This API should not be called more than needed as it will
3870 * negatively impact the performance of date operations.
3872 static void DateTimeConfigurationChangeNotification(Isolate* isolate);
3875 static void CheckCast(v8::Value* obj);
3880 * A Number object (ECMA-262, 4.3.21).
3882 class V8_EXPORT NumberObject : public Object {
3884 static Local<Value> New(Isolate* isolate, double value);
3886 double ValueOf() const;
3888 V8_INLINE static NumberObject* Cast(v8::Value* obj);
3891 static void CheckCast(v8::Value* obj);
3896 * A Boolean object (ECMA-262, 4.3.15).
3898 class V8_EXPORT BooleanObject : public Object {
3900 static Local<Value> New(bool value);
3902 bool ValueOf() const;
3904 V8_INLINE static BooleanObject* Cast(v8::Value* obj);
3907 static void CheckCast(v8::Value* obj);
3912 * A String object (ECMA-262, 4.3.18).
3914 class V8_EXPORT StringObject : public Object {
3916 static Local<Value> New(Local<String> value);
3918 Local<String> ValueOf() const;
3920 V8_INLINE static StringObject* Cast(v8::Value* obj);
3923 static void CheckCast(v8::Value* obj);
3928 * A Symbol object (ECMA-262 edition 6).
3930 * This is an experimental feature. Use at your own risk.
3932 class V8_EXPORT SymbolObject : public Object {
3934 static Local<Value> New(Isolate* isolate, Local<Symbol> value);
3936 Local<Symbol> ValueOf() const;
3938 V8_INLINE static SymbolObject* Cast(v8::Value* obj);
3941 static void CheckCast(v8::Value* obj);
3946 * An instance of the built-in RegExp constructor (ECMA-262, 15.10).
3948 class V8_EXPORT RegExp : public Object {
3951 * Regular expression flag bits. They can be or'ed to enable a set
3962 * Creates a regular expression from the given pattern string and
3963 * the flags bit field. May throw a JavaScript exception as
3964 * described in ECMA-262, 15.10.4.1.
3967 * RegExp::New(v8::String::New("foo"),
3968 * static_cast<RegExp::Flags>(kGlobal | kMultiline))
3969 * is equivalent to evaluating "/foo/gm".
3971 static V8_DEPRECATE_SOON("Use maybe version",
3972 Local<RegExp> New(Local<String> pattern,
3974 static V8_WARN_UNUSED_RESULT MaybeLocal<RegExp> New(Local<Context> context,
3975 Local<String> pattern,
3979 * Returns the value of the source property: a string representing
3980 * the regular expression.
3982 Local<String> GetSource() const;
3985 * Returns the flags bit field.
3987 Flags GetFlags() const;
3989 V8_INLINE static RegExp* Cast(v8::Value* obj);
3992 static void CheckCast(v8::Value* obj);
3997 * A JavaScript value that wraps a C++ void*. This type of value is mainly used
3998 * to associate C++ data structures with JavaScript objects.
4000 class V8_EXPORT External : public Value {
4002 static Local<External> New(Isolate* isolate, void* value);
4003 V8_INLINE static External* Cast(Value* obj);
4004 void* Value() const;
4006 static void CheckCast(v8::Value* obj);
4010 // --- Templates ---
4014 * The superclass of object and function templates.
4016 class V8_EXPORT Template : public Data {
4018 /** Adds a property to each instance created by this template.*/
4019 void Set(Local<Name> name, Local<Data> value,
4020 PropertyAttribute attributes = None);
4021 V8_INLINE void Set(Isolate* isolate, const char* name, Local<Data> value);
4023 void SetAccessorProperty(
4025 Local<FunctionTemplate> getter = Local<FunctionTemplate>(),
4026 Local<FunctionTemplate> setter = Local<FunctionTemplate>(),
4027 PropertyAttribute attribute = None,
4028 AccessControl settings = DEFAULT);
4030 #ifdef V8_JS_ACCESSORS
4031 void SetAccessorProperty(Local<Name> name,
4032 Local<Function> getter = Local<Function>(),
4033 Local<Function> setter = Local<Function>(),
4034 PropertyAttribute attribute = None);
4035 #endif // V8_JS_ACCESSORS
4038 * Whenever the property with the given name is accessed on objects
4039 * created from this Template the getter and setter callbacks
4040 * are called instead of getting and setting the property directly
4041 * on the JavaScript object.
4043 * \param name The name of the property for which an accessor is added.
4044 * \param getter The callback to invoke when getting the property.
4045 * \param setter The callback to invoke when setting the property.
4046 * \param data A piece of data that will be passed to the getter and setter
4047 * callbacks whenever they are invoked.
4048 * \param settings Access control settings for the accessor. This is a bit
4049 * field consisting of one of more of
4050 * DEFAULT = 0, ALL_CAN_READ = 1, or ALL_CAN_WRITE = 2.
4051 * The default is to not allow cross-context access.
4052 * ALL_CAN_READ means that all cross-context reads are allowed.
4053 * ALL_CAN_WRITE means that all cross-context writes are allowed.
4054 * The combination ALL_CAN_READ | ALL_CAN_WRITE can be used to allow all
4055 * cross-context access.
4056 * \param attribute The attributes of the property for which an accessor
4058 * \param signature The signature describes valid receivers for the accessor
4059 * and is used to perform implicit instance checks against them. If the
4060 * receiver is incompatible (i.e. is not an instance of the constructor as
4061 * defined by FunctionTemplate::HasInstance()), an implicit TypeError is
4062 * thrown and no callback is invoked.
4064 void SetNativeDataProperty(
4065 Local<String> name, AccessorGetterCallback getter,
4066 AccessorSetterCallback setter = 0,
4067 // TODO(dcarney): gcc can't handle Local below
4068 Local<Value> data = Local<Value>(), PropertyAttribute attribute = None,
4069 Local<AccessorSignature> signature = Local<AccessorSignature>(),
4070 AccessControl settings = DEFAULT);
4071 void SetNativeDataProperty(
4072 Local<Name> name, AccessorNameGetterCallback getter,
4073 AccessorNameSetterCallback setter = 0,
4074 // TODO(dcarney): gcc can't handle Local below
4075 Local<Value> data = Local<Value>(), PropertyAttribute attribute = None,
4076 Local<AccessorSignature> signature = Local<AccessorSignature>(),
4077 AccessControl settings = DEFAULT);
4082 friend class ObjectTemplate;
4083 friend class FunctionTemplate;
4088 * NamedProperty[Getter|Setter] are used as interceptors on object.
4089 * See ObjectTemplate::SetNamedPropertyHandler.
4091 typedef void (*NamedPropertyGetterCallback)(
4092 Local<String> property,
4093 const PropertyCallbackInfo<Value>& info);
4097 * Returns the value if the setter intercepts the request.
4098 * Otherwise, returns an empty handle.
4100 typedef void (*NamedPropertySetterCallback)(
4101 Local<String> property,
4103 const PropertyCallbackInfo<Value>& info);
4107 * Returns a non-empty handle if the interceptor intercepts the request.
4108 * The result is an integer encoding property attributes (like v8::None,
4109 * v8::DontEnum, etc.)
4111 typedef void (*NamedPropertyQueryCallback)(
4112 Local<String> property,
4113 const PropertyCallbackInfo<Integer>& info);
4117 * Returns a non-empty handle if the deleter intercepts the request.
4118 * The return value is true if the property could be deleted and false
4121 typedef void (*NamedPropertyDeleterCallback)(
4122 Local<String> property,
4123 const PropertyCallbackInfo<Boolean>& info);
4127 * Returns an array containing the names of the properties the named
4128 * property getter intercepts.
4130 typedef void (*NamedPropertyEnumeratorCallback)(
4131 const PropertyCallbackInfo<Array>& info);
4134 // TODO(dcarney): Deprecate and remove previous typedefs, and replace
4135 // GenericNamedPropertyFooCallback with just NamedPropertyFooCallback.
4137 * GenericNamedProperty[Getter|Setter] are used as interceptors on object.
4138 * See ObjectTemplate::SetNamedPropertyHandler.
4140 typedef void (*GenericNamedPropertyGetterCallback)(
4141 Local<Name> property, const PropertyCallbackInfo<Value>& info);
4145 * Returns the value if the setter intercepts the request.
4146 * Otherwise, returns an empty handle.
4148 typedef void (*GenericNamedPropertySetterCallback)(
4149 Local<Name> property, Local<Value> value,
4150 const PropertyCallbackInfo<Value>& info);
4154 * Returns a non-empty handle if the interceptor intercepts the request.
4155 * The result is an integer encoding property attributes (like v8::None,
4156 * v8::DontEnum, etc.)
4158 typedef void (*GenericNamedPropertyQueryCallback)(
4159 Local<Name> property, const PropertyCallbackInfo<Integer>& info);
4163 * Returns a non-empty handle if the deleter intercepts the request.
4164 * The return value is true if the property could be deleted and false
4167 typedef void (*GenericNamedPropertyDeleterCallback)(
4168 Local<Name> property, const PropertyCallbackInfo<Boolean>& info);
4172 * Returns an array containing the names of the properties the named
4173 * property getter intercepts.
4175 typedef void (*GenericNamedPropertyEnumeratorCallback)(
4176 const PropertyCallbackInfo<Array>& info);
4180 * Returns the value of the property if the getter intercepts the
4181 * request. Otherwise, returns an empty handle.
4183 typedef void (*IndexedPropertyGetterCallback)(
4185 const PropertyCallbackInfo<Value>& info);
4189 * Returns the value if the setter intercepts the request.
4190 * Otherwise, returns an empty handle.
4192 typedef void (*IndexedPropertySetterCallback)(
4195 const PropertyCallbackInfo<Value>& info);
4199 * Returns a non-empty handle if the interceptor intercepts the request.
4200 * The result is an integer encoding property attributes.
4202 typedef void (*IndexedPropertyQueryCallback)(
4204 const PropertyCallbackInfo<Integer>& info);
4208 * Returns a non-empty handle if the deleter intercepts the request.
4209 * The return value is true if the property could be deleted and false
4212 typedef void (*IndexedPropertyDeleterCallback)(
4214 const PropertyCallbackInfo<Boolean>& info);
4218 * Returns an array containing the indices of the properties the
4219 * indexed property getter intercepts.
4221 typedef void (*IndexedPropertyEnumeratorCallback)(
4222 const PropertyCallbackInfo<Array>& info);
4226 * Access type specification.
4238 * Returns true if cross-context access should be allowed to the named
4239 * property with the given key on the host object.
4241 typedef bool (*NamedSecurityCallback)(Local<Object> host,
4248 * Returns true if cross-context access should be allowed to the indexed
4249 * property with the given index on the host object.
4251 typedef bool (*IndexedSecurityCallback)(Local<Object> host,
4258 * A FunctionTemplate is used to create functions at runtime. There
4259 * can only be one function created from a FunctionTemplate in a
4260 * context. The lifetime of the created function is equal to the
4261 * lifetime of the context. So in case the embedder needs to create
4262 * temporary functions that can be collected using Scripts is
4265 * Any modification of a FunctionTemplate after first instantiation will trigger
4268 * A FunctionTemplate can have properties, these properties are added to the
4269 * function object when it is created.
4271 * A FunctionTemplate has a corresponding instance template which is
4272 * used to create object instances when the function is used as a
4273 * constructor. Properties added to the instance template are added to
4274 * each object instance.
4276 * A FunctionTemplate can have a prototype template. The prototype template
4277 * is used to create the prototype object of the function.
4279 * The following example shows how to use a FunctionTemplate:
4282 * v8::Local<v8::FunctionTemplate> t = v8::FunctionTemplate::New();
4283 * t->Set("func_property", v8::Number::New(1));
4285 * v8::Local<v8::Template> proto_t = t->PrototypeTemplate();
4286 * proto_t->Set("proto_method", v8::FunctionTemplate::New(InvokeCallback));
4287 * proto_t->Set("proto_const", v8::Number::New(2));
4289 * v8::Local<v8::ObjectTemplate> instance_t = t->InstanceTemplate();
4290 * instance_t->SetAccessor("instance_accessor", InstanceAccessorCallback);
4291 * instance_t->SetNamedPropertyHandler(PropertyHandlerCallback, ...);
4292 * instance_t->Set("instance_property", Number::New(3));
4294 * v8::Local<v8::Function> function = t->GetFunction();
4295 * v8::Local<v8::Object> instance = function->NewInstance();
4298 * Let's use "function" as the JS variable name of the function object
4299 * and "instance" for the instance object created above. The function
4300 * and the instance will have the following properties:
4303 * func_property in function == true;
4304 * function.func_property == 1;
4306 * function.prototype.proto_method() invokes 'InvokeCallback'
4307 * function.prototype.proto_const == 2;
4309 * instance instanceof function == true;
4310 * instance.instance_accessor calls 'InstanceAccessorCallback'
4311 * instance.instance_property == 3;
4314 * A FunctionTemplate can inherit from another one by calling the
4315 * FunctionTemplate::Inherit method. The following graph illustrates
4316 * the semantics of inheritance:
4319 * FunctionTemplate Parent -> Parent() . prototype -> { }
4321 * | Inherit(Parent) | .__proto__
4323 * FunctionTemplate Child -> Child() . prototype -> { }
4326 * A FunctionTemplate 'Child' inherits from 'Parent', the prototype
4327 * object of the Child() function has __proto__ pointing to the
4328 * Parent() function's prototype object. An instance of the Child
4329 * function has all properties on Parent's instance templates.
4331 * Let Parent be the FunctionTemplate initialized in the previous
4332 * section and create a Child FunctionTemplate by:
4335 * Local<FunctionTemplate> parent = t;
4336 * Local<FunctionTemplate> child = FunctionTemplate::New();
4337 * child->Inherit(parent);
4339 * Local<Function> child_function = child->GetFunction();
4340 * Local<Object> child_instance = child_function->NewInstance();
4343 * The Child function and Child instance will have the following
4347 * child_func.prototype.__proto__ == function.prototype;
4348 * child_instance.instance_accessor calls 'InstanceAccessorCallback'
4349 * child_instance.instance_property == 3;
4352 class V8_EXPORT FunctionTemplate : public Template {
4354 /** Creates a function template.*/
4355 static Local<FunctionTemplate> New(
4356 Isolate* isolate, FunctionCallback callback = 0,
4357 Local<Value> data = Local<Value>(),
4358 Local<Signature> signature = Local<Signature>(), int length = 0);
4360 /** Returns the unique function instance in the current execution context.*/
4361 V8_DEPRECATE_SOON("Use maybe version", Local<Function> GetFunction());
4362 V8_WARN_UNUSED_RESULT MaybeLocal<Function> GetFunction(
4363 Local<Context> context);
4366 * Set the call-handler callback for a FunctionTemplate. This
4367 * callback is called whenever the function created from this
4368 * FunctionTemplate is called.
4370 void SetCallHandler(FunctionCallback callback,
4371 Local<Value> data = Local<Value>());
4373 /** Set the predefined length property for the FunctionTemplate. */
4374 void SetLength(int length);
4376 /** Get the InstanceTemplate. */
4377 Local<ObjectTemplate> InstanceTemplate();
4379 /** Causes the function template to inherit from a parent function template.*/
4380 void Inherit(Local<FunctionTemplate> parent);
4383 * A PrototypeTemplate is the template used to create the prototype object
4384 * of the function created by this template.
4386 Local<ObjectTemplate> PrototypeTemplate();
4389 * Set the class name of the FunctionTemplate. This is used for
4390 * printing objects created with the function created from the
4391 * FunctionTemplate as its constructor.
4393 void SetClassName(Local<String> name);
4397 * When set to true, no access check will be performed on the receiver of a
4398 * function call. Currently defaults to true, but this is subject to change.
4400 void SetAcceptAnyReceiver(bool value);
4403 * Determines whether the __proto__ accessor ignores instances of
4404 * the function template. If instances of the function template are
4405 * ignored, __proto__ skips all instances and instead returns the
4406 * next object in the prototype chain.
4408 * Call with a value of true to make the __proto__ accessor ignore
4409 * instances of the function template. Call with a value of false
4410 * to make the __proto__ accessor not ignore instances of the
4411 * function template. By default, instances of a function template
4414 void SetHiddenPrototype(bool value);
4417 * Sets the ReadOnly flag in the attributes of the 'prototype' property
4418 * of functions created from this FunctionTemplate to true.
4420 void ReadOnlyPrototype();
4423 * Removes the prototype property from functions created from this
4426 void RemovePrototype();
4429 * Returns true if the given object is an instance of this function
4432 bool HasInstance(Local<Value> object);
4436 friend class Context;
4437 friend class ObjectTemplate;
4441 enum class PropertyHandlerFlags {
4443 // See ALL_CAN_READ above.
4445 // Will not call into interceptor for properties on the receiver or prototype
4446 // chain. Currently only valid for named interceptors.
4447 kNonMasking = 1 << 1,
4448 // Will not call into interceptor for symbol lookup. Only meaningful for
4449 // named interceptors.
4450 kOnlyInterceptStrings = 1 << 2,
4454 struct NamedPropertyHandlerConfiguration {
4455 NamedPropertyHandlerConfiguration(
4456 /** Note: getter is required **/
4457 GenericNamedPropertyGetterCallback getter = 0,
4458 GenericNamedPropertySetterCallback setter = 0,
4459 GenericNamedPropertyQueryCallback query = 0,
4460 GenericNamedPropertyDeleterCallback deleter = 0,
4461 GenericNamedPropertyEnumeratorCallback enumerator = 0,
4462 Local<Value> data = Local<Value>(),
4463 PropertyHandlerFlags flags = PropertyHandlerFlags::kNone)
4468 enumerator(enumerator),
4472 GenericNamedPropertyGetterCallback getter;
4473 GenericNamedPropertySetterCallback setter;
4474 GenericNamedPropertyQueryCallback query;
4475 GenericNamedPropertyDeleterCallback deleter;
4476 GenericNamedPropertyEnumeratorCallback enumerator;
4478 PropertyHandlerFlags flags;
4482 struct IndexedPropertyHandlerConfiguration {
4483 IndexedPropertyHandlerConfiguration(
4484 /** Note: getter is required **/
4485 IndexedPropertyGetterCallback getter = 0,
4486 IndexedPropertySetterCallback setter = 0,
4487 IndexedPropertyQueryCallback query = 0,
4488 IndexedPropertyDeleterCallback deleter = 0,
4489 IndexedPropertyEnumeratorCallback enumerator = 0,
4490 Local<Value> data = Local<Value>(),
4491 PropertyHandlerFlags flags = PropertyHandlerFlags::kNone)
4496 enumerator(enumerator),
4500 IndexedPropertyGetterCallback getter;
4501 IndexedPropertySetterCallback setter;
4502 IndexedPropertyQueryCallback query;
4503 IndexedPropertyDeleterCallback deleter;
4504 IndexedPropertyEnumeratorCallback enumerator;
4506 PropertyHandlerFlags flags;
4511 * An ObjectTemplate is used to create objects at runtime.
4513 * Properties added to an ObjectTemplate are added to each object
4514 * created from the ObjectTemplate.
4516 class V8_EXPORT ObjectTemplate : public Template {
4518 /** Creates an ObjectTemplate. */
4519 static Local<ObjectTemplate> New(
4521 Local<FunctionTemplate> constructor = Local<FunctionTemplate>());
4522 static V8_DEPRECATE_SOON("Use isolate version", Local<ObjectTemplate> New());
4524 /** Creates a new instance of this template.*/
4525 V8_DEPRECATE_SOON("Use maybe version", Local<Object> NewInstance());
4526 V8_WARN_UNUSED_RESULT MaybeLocal<Object> NewInstance(Local<Context> context);
4529 * Sets an accessor on the object template.
4531 * Whenever the property with the given name is accessed on objects
4532 * created from this ObjectTemplate the getter and setter callbacks
4533 * are called instead of getting and setting the property directly
4534 * on the JavaScript object.
4536 * \param name The name of the property for which an accessor is added.
4537 * \param getter The callback to invoke when getting the property.
4538 * \param setter The callback to invoke when setting the property.
4539 * \param data A piece of data that will be passed to the getter and setter
4540 * callbacks whenever they are invoked.
4541 * \param settings Access control settings for the accessor. This is a bit
4542 * field consisting of one of more of
4543 * DEFAULT = 0, ALL_CAN_READ = 1, or ALL_CAN_WRITE = 2.
4544 * The default is to not allow cross-context access.
4545 * ALL_CAN_READ means that all cross-context reads are allowed.
4546 * ALL_CAN_WRITE means that all cross-context writes are allowed.
4547 * The combination ALL_CAN_READ | ALL_CAN_WRITE can be used to allow all
4548 * cross-context access.
4549 * \param attribute The attributes of the property for which an accessor
4551 * \param signature The signature describes valid receivers for the accessor
4552 * and is used to perform implicit instance checks against them. If the
4553 * receiver is incompatible (i.e. is not an instance of the constructor as
4554 * defined by FunctionTemplate::HasInstance()), an implicit TypeError is
4555 * thrown and no callback is invoked.
4558 Local<String> name, AccessorGetterCallback getter,
4559 AccessorSetterCallback setter = 0, Local<Value> data = Local<Value>(),
4560 AccessControl settings = DEFAULT, PropertyAttribute attribute = None,
4561 Local<AccessorSignature> signature = Local<AccessorSignature>());
4563 Local<Name> name, AccessorNameGetterCallback getter,
4564 AccessorNameSetterCallback setter = 0, Local<Value> data = Local<Value>(),
4565 AccessControl settings = DEFAULT, PropertyAttribute attribute = None,
4566 Local<AccessorSignature> signature = Local<AccessorSignature>());
4569 * Sets a named property handler on the object template.
4571 * Whenever a property whose name is a string is accessed on objects created
4572 * from this object template, the provided callback is invoked instead of
4573 * accessing the property directly on the JavaScript object.
4575 * Note that new code should use the second version that can intercept
4576 * symbol-named properties as well as string-named properties.
4578 * \param getter The callback to invoke when getting a property.
4579 * \param setter The callback to invoke when setting a property.
4580 * \param query The callback to invoke to check if a property is present,
4581 * and if present, get its attributes.
4582 * \param deleter The callback to invoke when deleting a property.
4583 * \param enumerator The callback to invoke to enumerate all the named
4584 * properties of an object.
4585 * \param data A piece of data that will be passed to the callbacks
4586 * whenever they are invoked.
4588 // TODO(dcarney): deprecate
4589 void SetNamedPropertyHandler(NamedPropertyGetterCallback getter,
4590 NamedPropertySetterCallback setter = 0,
4591 NamedPropertyQueryCallback query = 0,
4592 NamedPropertyDeleterCallback deleter = 0,
4593 NamedPropertyEnumeratorCallback enumerator = 0,
4594 Local<Value> data = Local<Value>());
4595 void SetHandler(const NamedPropertyHandlerConfiguration& configuration);
4598 * Sets an indexed property handler on the object template.
4600 * Whenever an indexed property is accessed on objects created from
4601 * this object template, the provided callback is invoked instead of
4602 * accessing the property directly on the JavaScript object.
4604 * \param getter The callback to invoke when getting a property.
4605 * \param setter The callback to invoke when setting a property.
4606 * \param query The callback to invoke to check if an object has a property.
4607 * \param deleter The callback to invoke when deleting a property.
4608 * \param enumerator The callback to invoke to enumerate all the indexed
4609 * properties of an object.
4610 * \param data A piece of data that will be passed to the callbacks
4611 * whenever they are invoked.
4613 void SetHandler(const IndexedPropertyHandlerConfiguration& configuration);
4614 // TODO(dcarney): deprecate
4615 void SetIndexedPropertyHandler(
4616 IndexedPropertyGetterCallback getter,
4617 IndexedPropertySetterCallback setter = 0,
4618 IndexedPropertyQueryCallback query = 0,
4619 IndexedPropertyDeleterCallback deleter = 0,
4620 IndexedPropertyEnumeratorCallback enumerator = 0,
4621 Local<Value> data = Local<Value>()) {
4622 SetHandler(IndexedPropertyHandlerConfiguration(getter, setter, query,
4623 deleter, enumerator, data));
4626 * Sets the callback to be used when calling instances created from
4627 * this template as a function. If no callback is set, instances
4628 * behave like normal JavaScript objects that cannot be called as a
4631 void SetCallAsFunctionHandler(FunctionCallback callback,
4632 Local<Value> data = Local<Value>());
4635 * Mark object instances of the template as undetectable.
4637 * In many ways, undetectable objects behave as though they are not
4638 * there. They behave like 'undefined' in conditionals and when
4639 * printed. However, properties can be accessed and called as on
4642 void MarkAsUndetectable();
4645 * Sets access check callbacks on the object template and enables
4648 * When accessing properties on instances of this object template,
4649 * the access check callback will be called to determine whether or
4650 * not to allow cross-context access to the properties.
4652 void SetAccessCheckCallbacks(NamedSecurityCallback named_handler,
4653 IndexedSecurityCallback indexed_handler,
4654 Local<Value> data = Local<Value>());
4657 * Gets the number of internal fields for objects generated from
4660 int InternalFieldCount();
4663 * Sets the number of internal fields for objects generated from
4666 void SetInternalFieldCount(int value);
4670 static Local<ObjectTemplate> New(internal::Isolate* isolate,
4671 Local<FunctionTemplate> constructor);
4672 friend class FunctionTemplate;
4677 * A Signature specifies which receiver is valid for a function.
4679 class V8_EXPORT Signature : public Data {
4681 static Local<Signature> New(
4683 Local<FunctionTemplate> receiver = Local<FunctionTemplate>());
4691 * An AccessorSignature specifies which receivers are valid parameters
4692 * to an accessor callback.
4694 class V8_EXPORT AccessorSignature : public Data {
4696 static Local<AccessorSignature> New(
4698 Local<FunctionTemplate> receiver = Local<FunctionTemplate>());
4701 AccessorSignature();
4706 * A utility for determining the type of objects based on the template
4707 * they were constructed from.
4709 class V8_EXPORT TypeSwitch : public Data {
4711 static Local<TypeSwitch> New(Local<FunctionTemplate> type);
4712 static Local<TypeSwitch> New(int argc, Local<FunctionTemplate> types[]);
4713 int match(Local<Value> value);
4720 // --- Extensions ---
4722 class V8_EXPORT ExternalOneByteStringResourceImpl
4723 : public String::ExternalOneByteStringResource {
4725 ExternalOneByteStringResourceImpl() : data_(0), length_(0) {}
4726 ExternalOneByteStringResourceImpl(const char* data, size_t length)
4727 : data_(data), length_(length) {}
4728 const char* data() const { return data_; }
4729 size_t length() const { return length_; }
4739 class V8_EXPORT Extension { // NOLINT
4741 // Note that the strings passed into this constructor must live as long
4742 // as the Extension itself.
4743 Extension(const char* name,
4744 const char* source = 0,
4746 const char** deps = 0,
4747 int source_length = -1);
4748 virtual ~Extension() { }
4749 virtual v8::Local<v8::FunctionTemplate> GetNativeFunctionTemplate(
4750 v8::Isolate* isolate, v8::Local<v8::String> name) {
4751 return v8::Local<v8::FunctionTemplate>();
4754 const char* name() const { return name_; }
4755 size_t source_length() const { return source_length_; }
4756 const String::ExternalOneByteStringResource* source() const {
4758 int dependency_count() { return dep_count_; }
4759 const char** dependencies() { return deps_; }
4760 void set_auto_enable(bool value) { auto_enable_ = value; }
4761 bool auto_enable() { return auto_enable_; }
4765 size_t source_length_; // expected to initialize before source_
4766 ExternalOneByteStringResourceImpl source_;
4771 // Disallow copying and assigning.
4772 Extension(const Extension&);
4773 void operator=(const Extension&);
4777 void V8_EXPORT RegisterExtension(Extension* extension);
4782 V8_INLINE Local<Primitive> Undefined(Isolate* isolate);
4783 V8_INLINE Local<Primitive> Null(Isolate* isolate);
4784 V8_INLINE Local<Boolean> True(Isolate* isolate);
4785 V8_INLINE Local<Boolean> False(Isolate* isolate);
4789 * A set of constraints that specifies the limits of the runtime's memory use.
4790 * You must set the heap size before initializing the VM - the size cannot be
4791 * adjusted after the VM is initialized.
4793 * If you are using threads then you should hold the V8::Locker lock while
4794 * setting the stack limit and you must set a non-default stack limit separately
4797 class V8_EXPORT ResourceConstraints {
4799 ResourceConstraints();
4802 * Configures the constraints with reasonable default values based on the
4803 * capabilities of the current device the VM is running on.
4805 * \param physical_memory The total amount of physical memory on the current
4807 * \param virtual_memory_limit The amount of virtual memory on the current
4808 * device, in bytes, or zero, if there is no limit.
4810 void ConfigureDefaults(uint64_t physical_memory,
4811 uint64_t virtual_memory_limit);
4813 int max_semi_space_size() const { return max_semi_space_size_; }
4814 void set_max_semi_space_size(int value) { max_semi_space_size_ = value; }
4815 int max_old_space_size() const { return max_old_space_size_; }
4816 void set_max_old_space_size(int value) { max_old_space_size_ = value; }
4817 int max_executable_size() const { return max_executable_size_; }
4818 void set_max_executable_size(int value) { max_executable_size_ = value; }
4819 uint32_t* stack_limit() const { return stack_limit_; }
4820 // Sets an address beyond which the VM's stack may not grow.
4821 void set_stack_limit(uint32_t* value) { stack_limit_ = value; }
4822 size_t code_range_size() const { return code_range_size_; }
4823 void set_code_range_size(size_t value) {
4824 code_range_size_ = value;
4828 int max_semi_space_size_;
4829 int max_old_space_size_;
4830 int max_executable_size_;
4831 uint32_t* stack_limit_;
4832 size_t code_range_size_;
4836 // --- Exceptions ---
4839 typedef void (*FatalErrorCallback)(const char* location, const char* message);
4842 typedef void (*MessageCallback)(Local<Message> message, Local<Value> error);
4846 typedef void (*LogEventCallback)(const char* name, int event);
4849 * Create new error objects by calling the corresponding error object
4850 * constructor with the message.
4852 class V8_EXPORT Exception {
4854 static Local<Value> RangeError(Local<String> message);
4855 static Local<Value> ReferenceError(Local<String> message);
4856 static Local<Value> SyntaxError(Local<String> message);
4857 static Local<Value> TypeError(Local<String> message);
4858 static Local<Value> Error(Local<String> message);
4861 * Creates an error message for the given exception.
4862 * Will try to reconstruct the original stack trace from the exception value,
4863 * or capture the current stack trace if not available.
4865 static Local<Message> CreateMessage(Local<Value> exception);
4868 * Returns the original stack trace that was captured at the creation time
4869 * of a given exception, or an empty handle if not available.
4871 static Local<StackTrace> GetStackTrace(Local<Value> exception);
4875 // --- Counters Callbacks ---
4877 typedef int* (*CounterLookupCallback)(const char* name);
4879 typedef void* (*CreateHistogramCallback)(const char* name,
4884 typedef void (*AddHistogramSampleCallback)(void* histogram, int sample);
4886 // --- Memory Allocation Callback ---
4888 kObjectSpaceNewSpace = 1 << 0,
4889 kObjectSpaceOldSpace = 1 << 1,
4890 kObjectSpaceCodeSpace = 1 << 2,
4891 kObjectSpaceMapSpace = 1 << 3,
4892 kObjectSpaceLoSpace = 1 << 4,
4893 kObjectSpaceAll = kObjectSpaceNewSpace | kObjectSpaceOldSpace |
4894 kObjectSpaceCodeSpace | kObjectSpaceMapSpace |
4898 enum AllocationAction {
4899 kAllocationActionAllocate = 1 << 0,
4900 kAllocationActionFree = 1 << 1,
4901 kAllocationActionAll = kAllocationActionAllocate | kAllocationActionFree
4904 typedef void (*MemoryAllocationCallback)(ObjectSpace space,
4905 AllocationAction action,
4908 // --- Leave Script Callback ---
4909 typedef void (*CallCompletedCallback)();
4911 // --- Promise Reject Callback ---
4912 enum PromiseRejectEvent {
4913 kPromiseRejectWithNoHandler = 0,
4914 kPromiseHandlerAddedAfterReject = 1
4917 class PromiseRejectMessage {
4919 PromiseRejectMessage(Local<Promise> promise, PromiseRejectEvent event,
4920 Local<Value> value, Local<StackTrace> stack_trace)
4921 : promise_(promise),
4924 stack_trace_(stack_trace) {}
4926 V8_INLINE Local<Promise> GetPromise() const { return promise_; }
4927 V8_INLINE PromiseRejectEvent GetEvent() const { return event_; }
4928 V8_INLINE Local<Value> GetValue() const { return value_; }
4930 // DEPRECATED. Use v8::Exception::CreateMessage(GetValue())->GetStackTrace()
4931 V8_INLINE Local<StackTrace> GetStackTrace() const { return stack_trace_; }
4934 Local<Promise> promise_;
4935 PromiseRejectEvent event_;
4936 Local<Value> value_;
4937 Local<StackTrace> stack_trace_;
4940 typedef void (*PromiseRejectCallback)(PromiseRejectMessage message);
4942 // --- Microtask Callback ---
4943 typedef void (*MicrotaskCallback)(void* data);
4945 // --- Failed Access Check Callback ---
4946 typedef void (*FailedAccessCheckCallback)(Local<Object> target,
4950 // --- AllowCodeGenerationFromStrings callbacks ---
4953 * Callback to check if code generation from strings is allowed. See
4954 * Context::AllowCodeGenerationFromStrings.
4956 typedef bool (*AllowCodeGenerationFromStringsCallback)(Local<Context> context);
4958 // --- Garbage Collection Callbacks ---
4961 * Applications can register callback functions which will be called before and
4962 * after certain garbage collection operations. Allocations are not allowed in
4963 * the callback functions, you therefore cannot manipulate objects (set or
4964 * delete properties for example) since it is possible such operations will
4965 * result in the allocation of objects.
4968 kGCTypeScavenge = 1 << 0,
4969 kGCTypeMarkSweepCompact = 1 << 1,
4970 kGCTypeIncrementalMarking = 1 << 2,
4971 kGCTypeProcessWeakCallbacks = 1 << 3,
4972 kGCTypeAll = kGCTypeScavenge | kGCTypeMarkSweepCompact |
4973 kGCTypeIncrementalMarking | kGCTypeProcessWeakCallbacks
4976 enum GCCallbackFlags {
4977 kNoGCCallbackFlags = 0,
4978 kGCCallbackFlagConstructRetainedObjectInfos = 1 << 1,
4979 kGCCallbackFlagForced = 1 << 2,
4980 kGCCallbackFlagSynchronousPhantomCallbackProcessing = 1 << 3
4983 V8_DEPRECATE_SOON("Use GCCallBack instead",
4984 typedef void (*GCPrologueCallback)(GCType type,
4985 GCCallbackFlags flags));
4986 V8_DEPRECATE_SOON("Use GCCallBack instead",
4987 typedef void (*GCEpilogueCallback)(GCType type,
4988 GCCallbackFlags flags));
4989 typedef void (*GCCallback)(GCType type, GCCallbackFlags flags);
4991 typedef void (*InterruptCallback)(Isolate* isolate, void* data);
4995 * Collection of V8 heap information.
4997 * Instances of this class can be passed to v8::V8::HeapStatistics to
4998 * get heap statistics from V8.
5000 class V8_EXPORT HeapStatistics {
5003 size_t total_heap_size() { return total_heap_size_; }
5004 size_t total_heap_size_executable() { return total_heap_size_executable_; }
5005 size_t total_physical_size() { return total_physical_size_; }
5006 size_t total_available_size() { return total_available_size_; }
5007 size_t used_heap_size() { return used_heap_size_; }
5008 size_t heap_size_limit() { return heap_size_limit_; }
5011 size_t total_heap_size_;
5012 size_t total_heap_size_executable_;
5013 size_t total_physical_size_;
5014 size_t total_available_size_;
5015 size_t used_heap_size_;
5016 size_t heap_size_limit_;
5019 friend class Isolate;
5023 class V8_EXPORT HeapSpaceStatistics {
5025 HeapSpaceStatistics();
5026 const char* space_name() { return space_name_; }
5027 size_t space_size() { return space_size_; }
5028 size_t space_used_size() { return space_used_size_; }
5029 size_t space_available_size() { return space_available_size_; }
5030 size_t physical_space_size() { return physical_space_size_; }
5033 const char* space_name_;
5035 size_t space_used_size_;
5036 size_t space_available_size_;
5037 size_t physical_space_size_;
5039 friend class Isolate;
5043 class V8_EXPORT HeapObjectStatistics {
5045 HeapObjectStatistics();
5046 const char* object_type() { return object_type_; }
5047 const char* object_sub_type() { return object_sub_type_; }
5048 size_t object_count() { return object_count_; }
5049 size_t object_size() { return object_size_; }
5052 const char* object_type_;
5053 const char* object_sub_type_;
5054 size_t object_count_;
5055 size_t object_size_;
5057 friend class Isolate;
5061 class RetainedObjectInfo;
5065 * FunctionEntryHook is the type of the profile entry hook called at entry to
5066 * any generated function when function-level profiling is enabled.
5068 * \param function the address of the function that's being entered.
5069 * \param return_addr_location points to a location on stack where the machine
5070 * return address resides. This can be used to identify the caller of
5071 * \p function, and/or modified to divert execution when \p function exits.
5073 * \note the entry hook must not cause garbage collection.
5075 typedef void (*FunctionEntryHook)(uintptr_t function,
5076 uintptr_t return_addr_location);
5079 * A JIT code event is issued each time code is added, moved or removed.
5081 * \note removal events are not currently issued.
5083 struct JitCodeEvent {
5088 CODE_ADD_LINE_POS_INFO,
5089 CODE_START_LINE_INFO_RECORDING,
5090 CODE_END_LINE_INFO_RECORDING
5092 // Definition of the code position type. The "POSITION" type means the place
5093 // in the source code which are of interest when making stack traces to
5094 // pin-point the source location of a stack frame as close as possible.
5095 // The "STATEMENT_POSITION" means the place at the beginning of each
5096 // statement, and is used to indicate possible break locations.
5097 enum PositionType { POSITION, STATEMENT_POSITION };
5101 // Start of the instructions.
5103 // Size of the instructions.
5105 // Script info for CODE_ADDED event.
5106 Local<UnboundScript> script;
5107 // User-defined data for *_LINE_INFO_* event. It's used to hold the source
5108 // code line information which is returned from the
5109 // CODE_START_LINE_INFO_RECORDING event. And it's passed to subsequent
5110 // CODE_ADD_LINE_POS_INFO and CODE_END_LINE_INFO_RECORDING events.
5114 // Name of the object associated with the code, note that the string is not
5117 // Number of chars in str.
5121 struct line_info_t {
5126 // The position type.
5127 PositionType position_type;
5131 // Only valid for CODE_ADDED.
5134 // Only valid for CODE_ADD_LINE_POS_INFO
5135 struct line_info_t line_info;
5137 // New location of instructions. Only valid for CODE_MOVED.
5138 void* new_code_start;
5143 * Option flags passed to the SetJitCodeEventHandler function.
5145 enum JitCodeEventOptions {
5146 kJitCodeEventDefault = 0,
5147 // Generate callbacks for already existent code.
5148 kJitCodeEventEnumExisting = 1
5153 * Callback function passed to SetJitCodeEventHandler.
5155 * \param event code add, move or removal event.
5157 typedef void (*JitCodeEventHandler)(const JitCodeEvent* event);
5161 * Interface for iterating through all external resources in the heap.
5163 class V8_EXPORT ExternalResourceVisitor { // NOLINT
5165 virtual ~ExternalResourceVisitor() {}
5166 virtual void VisitExternalString(Local<String> string) {}
5171 * Interface for iterating through all the persistent handles in the heap.
5173 class V8_EXPORT PersistentHandleVisitor { // NOLINT
5175 virtual ~PersistentHandleVisitor() {}
5176 virtual void VisitPersistentHandle(Persistent<Value>* value,
5177 uint16_t class_id) {}
5182 * Isolate represents an isolated instance of the V8 engine. V8 isolates have
5183 * completely separate states. Objects from one isolate must not be used in
5184 * other isolates. The embedder can create multiple isolates and use them in
5185 * parallel in multiple threads. An isolate can be entered by at most one
5186 * thread at any given time. The Locker/Unlocker API must be used to
5189 class V8_EXPORT Isolate {
5192 * Initial configuration parameters for a new Isolate.
5194 struct CreateParams {
5197 code_event_handler(NULL),
5198 snapshot_blob(NULL),
5199 counter_lookup_callback(NULL),
5200 create_histogram_callback(NULL),
5201 add_histogram_sample_callback(NULL),
5202 array_buffer_allocator(NULL) {}
5205 * The optional entry_hook allows the host application to provide the
5206 * address of a function that's invoked on entry to every V8-generated
5207 * function. Note that entry_hook is invoked at the very start of each
5208 * generated function. Furthermore, if an entry_hook is given, V8 will
5209 * always run without a context snapshot.
5211 FunctionEntryHook entry_hook;
5214 * Allows the host application to provide the address of a function that is
5215 * notified each time code is added, moved or removed.
5217 JitCodeEventHandler code_event_handler;
5220 * ResourceConstraints to use for the new Isolate.
5222 ResourceConstraints constraints;
5225 * Explicitly specify a startup snapshot blob. The embedder owns the blob.
5227 StartupData* snapshot_blob;
5231 * Enables the host application to provide a mechanism for recording
5232 * statistics counters.
5234 CounterLookupCallback counter_lookup_callback;
5237 * Enables the host application to provide a mechanism for recording
5238 * histograms. The CreateHistogram function returns a
5239 * histogram which will later be passed to the AddHistogramSample
5242 CreateHistogramCallback create_histogram_callback;
5243 AddHistogramSampleCallback add_histogram_sample_callback;
5246 * The ArrayBuffer::Allocator to use for allocating and freeing the backing
5247 * store of ArrayBuffers.
5249 ArrayBuffer::Allocator* array_buffer_allocator;
5254 * Stack-allocated class which sets the isolate for all operations
5255 * executed within a local scope.
5257 class V8_EXPORT Scope {
5259 explicit Scope(Isolate* isolate) : isolate_(isolate) {
5263 ~Scope() { isolate_->Exit(); }
5266 Isolate* const isolate_;
5268 // Prevent copying of Scope objects.
5269 Scope(const Scope&);
5270 Scope& operator=(const Scope&);
5275 * Assert that no Javascript code is invoked.
5277 class V8_EXPORT DisallowJavascriptExecutionScope {
5279 enum OnFailure { CRASH_ON_FAILURE, THROW_ON_FAILURE };
5281 DisallowJavascriptExecutionScope(Isolate* isolate, OnFailure on_failure);
5282 ~DisallowJavascriptExecutionScope();
5288 // Prevent copying of Scope objects.
5289 DisallowJavascriptExecutionScope(const DisallowJavascriptExecutionScope&);
5290 DisallowJavascriptExecutionScope& operator=(
5291 const DisallowJavascriptExecutionScope&);
5296 * Introduce exception to DisallowJavascriptExecutionScope.
5298 class V8_EXPORT AllowJavascriptExecutionScope {
5300 explicit AllowJavascriptExecutionScope(Isolate* isolate);
5301 ~AllowJavascriptExecutionScope();
5304 void* internal_throws_;
5305 void* internal_assert_;
5307 // Prevent copying of Scope objects.
5308 AllowJavascriptExecutionScope(const AllowJavascriptExecutionScope&);
5309 AllowJavascriptExecutionScope& operator=(
5310 const AllowJavascriptExecutionScope&);
5314 * Do not run microtasks while this scope is active, even if microtasks are
5315 * automatically executed otherwise.
5317 class V8_EXPORT SuppressMicrotaskExecutionScope {
5319 explicit SuppressMicrotaskExecutionScope(Isolate* isolate);
5320 ~SuppressMicrotaskExecutionScope();
5323 internal::Isolate* isolate_;
5325 // Prevent copying of Scope objects.
5326 SuppressMicrotaskExecutionScope(const SuppressMicrotaskExecutionScope&);
5327 SuppressMicrotaskExecutionScope& operator=(
5328 const SuppressMicrotaskExecutionScope&);
5332 * Types of garbage collections that can be requested via
5333 * RequestGarbageCollectionForTesting.
5335 enum GarbageCollectionType {
5336 kFullGarbageCollection,
5337 kMinorGarbageCollection
5341 * Features reported via the SetUseCounterCallback callback. Do not change
5342 * assigned numbers of existing items; add new features to the end of this
5345 enum UseCounterFeature {
5349 kMarkDequeOverflow = 3,
5350 kStoreBufferOverflow = 4,
5351 kSlotsBufferOverflow = 5,
5354 kUseCounterFeatureCount // This enum value must be last.
5357 typedef void (*UseCounterCallback)(Isolate* isolate,
5358 UseCounterFeature feature);
5362 * Creates a new isolate. Does not change the currently entered
5365 * When an isolate is no longer used its resources should be freed
5366 * by calling Dispose(). Using the delete operator is not allowed.
5368 * V8::Initialize() must have run prior to this.
5370 static Isolate* New(const CreateParams& params);
5373 * Returns the entered isolate for the current thread or NULL in
5374 * case there is no current isolate.
5376 * This method must not be invoked before V8::Initialize() was invoked.
5378 static Isolate* GetCurrent();
5381 * Methods below this point require holding a lock (using Locker) in
5382 * a multi-threaded environment.
5386 * Sets this isolate as the entered one for the current thread.
5387 * Saves the previously entered one (if any), so that it can be
5388 * restored when exiting. Re-entering an isolate is allowed.
5393 * Exits this isolate by restoring the previously entered one in the
5394 * current thread. The isolate may still stay the same, if it was
5395 * entered more than once.
5397 * Requires: this == Isolate::GetCurrent().
5402 * Disposes the isolate. The isolate must not be entered by any
5403 * thread to be disposable.
5408 * Associate embedder-specific data with the isolate. |slot| has to be
5409 * between 0 and GetNumberOfDataSlots() - 1.
5411 V8_INLINE void SetData(uint32_t slot, void* data);
5414 * Retrieve embedder-specific data from the isolate.
5415 * Returns NULL if SetData has never been called for the given |slot|.
5417 V8_INLINE void* GetData(uint32_t slot);
5420 * Returns the maximum number of available embedder data slots. Valid slots
5421 * are in the range of 0 - GetNumberOfDataSlots() - 1.
5423 V8_INLINE static uint32_t GetNumberOfDataSlots();
5426 * Get statistics about the heap memory usage.
5428 void GetHeapStatistics(HeapStatistics* heap_statistics);
5431 * Returns the number of spaces in the heap.
5433 size_t NumberOfHeapSpaces();
5436 * Get the memory usage of a space in the heap.
5438 * \param space_statistics The HeapSpaceStatistics object to fill in
5440 * \param index The index of the space to get statistics from, which ranges
5441 * from 0 to NumberOfHeapSpaces() - 1.
5442 * \returns true on success.
5444 bool GetHeapSpaceStatistics(HeapSpaceStatistics* space_statistics,
5448 * Returns the number of types of objects tracked in the heap at GC.
5450 size_t NumberOfTrackedHeapObjectTypes();
5453 * Get statistics about objects in the heap.
5455 * \param object_statistics The HeapObjectStatistics object to fill in
5456 * statistics of objects of given type, which were live in the previous GC.
5457 * \param type_index The index of the type of object to fill details about,
5458 * which ranges from 0 to NumberOfTrackedHeapObjectTypes() - 1.
5459 * \returns true on success.
5461 bool GetHeapObjectStatisticsAtLastGC(HeapObjectStatistics* object_statistics,
5465 * Get a call stack sample from the isolate.
5466 * \param state Execution state.
5467 * \param frames Caller allocated buffer to store stack frames.
5468 * \param frames_limit Maximum number of frames to capture. The buffer must
5469 * be large enough to hold the number of frames.
5470 * \param sample_info The sample info is filled up by the function
5471 * provides number of actual captured stack frames and
5472 * the current VM state.
5473 * \note GetStackSample should only be called when the JS thread is paused or
5474 * interrupted. Otherwise the behavior is undefined.
5476 void GetStackSample(const RegisterState& state, void** frames,
5477 size_t frames_limit, SampleInfo* sample_info);
5480 * Adjusts the amount of registered external memory. Used to give V8 an
5481 * indication of the amount of externally allocated memory that is kept alive
5482 * by JavaScript objects. V8 uses this to decide when to perform global
5483 * garbage collections. Registering externally allocated memory will trigger
5484 * global garbage collections more often than it would otherwise in an attempt
5485 * to garbage collect the JavaScript objects that keep the externally
5486 * allocated memory alive.
5488 * \param change_in_bytes the change in externally allocated memory that is
5489 * kept alive by JavaScript objects.
5490 * \returns the adjusted value.
5493 AdjustAmountOfExternalAllocatedMemory(int64_t change_in_bytes);
5496 * Returns heap profiler for this isolate. Will return NULL until the isolate
5499 HeapProfiler* GetHeapProfiler();
5502 * Returns CPU profiler for this isolate. Will return NULL unless the isolate
5503 * is initialized. It is the embedder's responsibility to stop all CPU
5504 * profiling activities if it has started any.
5506 CpuProfiler* GetCpuProfiler();
5508 /** Returns true if this isolate has a current context. */
5511 /** Returns the context that is on the top of the stack. */
5512 Local<Context> GetCurrentContext();
5515 * Returns the context of the calling JavaScript code. That is the
5516 * context of the top-most JavaScript frame. If there are no
5517 * JavaScript frames an empty handle is returned.
5519 Local<Context> GetCallingContext();
5521 /** Returns the last entered context. */
5522 Local<Context> GetEnteredContext();
5525 * Schedules an exception to be thrown when returning to JavaScript. When an
5526 * exception has been scheduled it is illegal to invoke any JavaScript
5527 * operation; the caller must return immediately and only after the exception
5528 * has been handled does it become legal to invoke JavaScript operations.
5530 Local<Value> ThrowException(Local<Value> exception);
5533 * Allows the host application to group objects together. If one
5534 * object in the group is alive, all objects in the group are alive.
5535 * After each garbage collection, object groups are removed. It is
5536 * intended to be used in the before-garbage-collection callback
5537 * function, for instance to simulate DOM tree connections among JS
5538 * wrapper objects. Object groups for all dependent handles need to
5539 * be provided for kGCTypeMarkSweepCompact collections, for all other
5540 * garbage collection types it is sufficient to provide object groups
5541 * for partially dependent handles only.
5543 template<typename T> void SetObjectGroupId(const Persistent<T>& object,
5547 * Allows the host application to declare implicit references from an object
5548 * group to an object. If the objects of the object group are alive, the child
5549 * object is alive too. After each garbage collection, all implicit references
5550 * are removed. It is intended to be used in the before-garbage-collection
5551 * callback function.
5553 template<typename T> void SetReferenceFromGroup(UniqueId id,
5554 const Persistent<T>& child);
5557 * Allows the host application to declare implicit references from an object
5558 * to another object. If the parent object is alive, the child object is alive
5559 * too. After each garbage collection, all implicit references are removed. It
5560 * is intended to be used in the before-garbage-collection callback function.
5562 template<typename T, typename S>
5563 void SetReference(const Persistent<T>& parent, const Persistent<S>& child);
5565 V8_DEPRECATE_SOON("Use GCCallBack instead",
5566 typedef void (*GCPrologueCallback)(Isolate* isolate,
5568 GCCallbackFlags flags));
5569 V8_DEPRECATE_SOON("Use GCCallBack instead",
5570 typedef void (*GCEpilogueCallback)(Isolate* isolate,
5572 GCCallbackFlags flags));
5573 typedef void (*GCCallback)(Isolate* isolate, GCType type,
5574 GCCallbackFlags flags);
5577 * Enables the host application to receive a notification before a
5578 * garbage collection. Allocations are allowed in the callback function,
5579 * but the callback is not re-entrant: if the allocation inside it will
5580 * trigger the garbage collection, the callback won't be called again.
5581 * It is possible to specify the GCType filter for your callback. But it is
5582 * not possible to register the same callback function two times with
5583 * different GCType filters.
5585 void AddGCPrologueCallback(GCCallback callback,
5586 GCType gc_type_filter = kGCTypeAll);
5589 * This function removes callback which was installed by
5590 * AddGCPrologueCallback function.
5592 void RemoveGCPrologueCallback(GCCallback callback);
5595 * Enables the host application to receive a notification after a
5596 * garbage collection. Allocations are allowed in the callback function,
5597 * but the callback is not re-entrant: if the allocation inside it will
5598 * trigger the garbage collection, the callback won't be called again.
5599 * It is possible to specify the GCType filter for your callback. But it is
5600 * not possible to register the same callback function two times with
5601 * different GCType filters.
5603 void AddGCEpilogueCallback(GCCallback callback,
5604 GCType gc_type_filter = kGCTypeAll);
5607 * This function removes callback which was installed by
5608 * AddGCEpilogueCallback function.
5610 void RemoveGCEpilogueCallback(GCCallback callback);
5613 * Forcefully terminate the current thread of JavaScript execution
5614 * in the given isolate.
5616 * This method can be used by any thread even if that thread has not
5617 * acquired the V8 lock with a Locker object.
5619 void TerminateExecution();
5622 * Is V8 terminating JavaScript execution.
5624 * Returns true if JavaScript execution is currently terminating
5625 * because of a call to TerminateExecution. In that case there are
5626 * still JavaScript frames on the stack and the termination
5627 * exception is still active.
5629 bool IsExecutionTerminating();
5632 * Resume execution capability in the given isolate, whose execution
5633 * was previously forcefully terminated using TerminateExecution().
5635 * When execution is forcefully terminated using TerminateExecution(),
5636 * the isolate can not resume execution until all JavaScript frames
5637 * have propagated the uncatchable exception which is generated. This
5638 * method allows the program embedding the engine to handle the
5639 * termination event and resume execution capability, even if
5640 * JavaScript frames remain on the stack.
5642 * This method can be used by any thread even if that thread has not
5643 * acquired the V8 lock with a Locker object.
5645 void CancelTerminateExecution();
5648 * Request V8 to interrupt long running JavaScript code and invoke
5649 * the given |callback| passing the given |data| to it. After |callback|
5650 * returns control will be returned to the JavaScript code.
5651 * There may be a number of interrupt requests in flight.
5652 * Can be called from another thread without acquiring a |Locker|.
5653 * Registered |callback| must not reenter interrupted Isolate.
5655 void RequestInterrupt(InterruptCallback callback, void* data);
5658 * Request garbage collection in this Isolate. It is only valid to call this
5659 * function if --expose_gc was specified.
5661 * This should only be used for testing purposes and not to enforce a garbage
5662 * collection schedule. It has strong negative impact on the garbage
5663 * collection performance. Use IdleNotificationDeadline() or
5664 * LowMemoryNotification() instead to influence the garbage collection
5667 void RequestGarbageCollectionForTesting(GarbageCollectionType type);
5670 * Set the callback to invoke for logging event.
5672 void SetEventLogger(LogEventCallback that);
5675 * Adds a callback to notify the host application when a script finished
5676 * running. If a script re-enters the runtime during executing, the
5677 * CallCompletedCallback is only invoked when the outer-most script
5678 * execution ends. Executing scripts inside the callback do not trigger
5679 * further callbacks.
5681 void AddCallCompletedCallback(CallCompletedCallback callback);
5684 * Removes callback that was installed by AddCallCompletedCallback.
5686 void RemoveCallCompletedCallback(CallCompletedCallback callback);
5690 * Set callback to notify about promise reject with no handler, or
5691 * revocation of such a previous notification once the handler is added.
5693 void SetPromiseRejectCallback(PromiseRejectCallback callback);
5696 * Experimental: Runs the Microtask Work Queue until empty
5697 * Any exceptions thrown by microtask callbacks are swallowed.
5699 void RunMicrotasks();
5702 * Experimental: Enqueues the callback to the Microtask Work Queue
5704 void EnqueueMicrotask(Local<Function> microtask);
5707 * Experimental: Enqueues the callback to the Microtask Work Queue
5709 void EnqueueMicrotask(MicrotaskCallback microtask, void* data = NULL);
5712 * Experimental: Controls whether the Microtask Work Queue is automatically
5713 * run when the script call depth decrements to zero.
5715 void SetAutorunMicrotasks(bool autorun);
5718 * Experimental: Returns whether the Microtask Work Queue is automatically
5719 * run when the script call depth decrements to zero.
5721 bool WillAutorunMicrotasks() const;
5724 * Sets a callback for counting the number of times a feature of V8 is used.
5726 void SetUseCounterCallback(UseCounterCallback callback);
5729 * Enables the host application to provide a mechanism for recording
5730 * statistics counters.
5732 void SetCounterFunction(CounterLookupCallback);
5735 * Enables the host application to provide a mechanism for recording
5736 * histograms. The CreateHistogram function returns a
5737 * histogram which will later be passed to the AddHistogramSample
5740 void SetCreateHistogramFunction(CreateHistogramCallback);
5741 void SetAddHistogramSampleFunction(AddHistogramSampleCallback);
5744 * Optional notification that the embedder is idle.
5745 * V8 uses the notification to perform garbage collection.
5746 * This call can be used repeatedly if the embedder remains idle.
5747 * Returns true if the embedder should stop calling IdleNotificationDeadline
5748 * until real work has been done. This indicates that V8 has done
5749 * as much cleanup as it will be able to do.
5751 * The deadline_in_seconds argument specifies the deadline V8 has to finish
5752 * garbage collection work. deadline_in_seconds is compared with
5753 * MonotonicallyIncreasingTime() and should be based on the same timebase as
5754 * that function. There is no guarantee that the actual work will be done
5755 * within the time limit.
5757 bool IdleNotificationDeadline(double deadline_in_seconds);
5759 V8_DEPRECATE_SOON("use IdleNotificationDeadline()",
5760 bool IdleNotification(int idle_time_in_ms));
5763 * Optional notification that the system is running low on memory.
5764 * V8 uses these notifications to attempt to free memory.
5766 void LowMemoryNotification();
5769 * Optional notification that a context has been disposed. V8 uses
5770 * these notifications to guide the GC heuristic. Returns the number
5771 * of context disposals - including this one - since the last time
5772 * V8 had a chance to clean up.
5774 * The optional parameter |dependant_context| specifies whether the disposed
5775 * context was depending on state from other contexts or not.
5777 int ContextDisposedNotification(bool dependant_context = true);
5780 * Allows the host application to provide the address of a function that is
5781 * notified each time code is added, moved or removed.
5783 * \param options options for the JIT code event handler.
5784 * \param event_handler the JIT code event handler, which will be invoked
5785 * each time code is added, moved or removed.
5786 * \note \p event_handler won't get notified of existent code.
5787 * \note since code removal notifications are not currently issued, the
5788 * \p event_handler may get notifications of code that overlaps earlier
5789 * code notifications. This happens when code areas are reused, and the
5790 * earlier overlapping code areas should therefore be discarded.
5791 * \note the events passed to \p event_handler and the strings they point to
5792 * are not guaranteed to live past each call. The \p event_handler must
5793 * copy strings and other parameters it needs to keep around.
5794 * \note the set of events declared in JitCodeEvent::EventType is expected to
5795 * grow over time, and the JitCodeEvent structure is expected to accrue
5796 * new members. The \p event_handler function must ignore event codes
5797 * it does not recognize to maintain future compatibility.
5798 * \note Use Isolate::CreateParams to get events for code executed during
5801 void SetJitCodeEventHandler(JitCodeEventOptions options,
5802 JitCodeEventHandler event_handler);
5805 * Modifies the stack limit for this Isolate.
5807 * \param stack_limit An address beyond which the Vm's stack may not grow.
5809 * \note If you are using threads then you should hold the V8::Locker lock
5810 * while setting the stack limit and you must set a non-default stack
5811 * limit separately for each thread.
5813 void SetStackLimit(uintptr_t stack_limit);
5816 * Returns a memory range that can potentially contain jitted code.
5818 * On Win64, embedders are advised to install function table callbacks for
5819 * these ranges, as default SEH won't be able to unwind through jitted code.
5821 * The first page of the code range is reserved for the embedder and is
5822 * committed, writable, and executable.
5824 * Might be empty on other platforms.
5826 * https://code.google.com/p/v8/issues/detail?id=3598
5828 void GetCodeRange(void** start, size_t* length_in_bytes);
5830 /** Set the callback to invoke in case of fatal errors. */
5831 void SetFatalErrorHandler(FatalErrorCallback that);
5834 * Set the callback to invoke to check if code generation from
5835 * strings should be allowed.
5837 void SetAllowCodeGenerationFromStringsCallback(
5838 AllowCodeGenerationFromStringsCallback callback);
5841 * Check if V8 is dead and therefore unusable. This is the case after
5842 * fatal errors such as out-of-memory situations.
5847 * Adds a message listener.
5849 * The same message listener can be added more than once and in that
5850 * case it will be called more than once for each message.
5852 * If data is specified, it will be passed to the callback when it is called.
5853 * Otherwise, the exception object will be passed to the callback instead.
5855 bool AddMessageListener(MessageCallback that,
5856 Local<Value> data = Local<Value>());
5859 * Remove all message listeners from the specified callback function.
5861 void RemoveMessageListeners(MessageCallback that);
5863 /** Callback function for reporting failed access checks.*/
5864 void SetFailedAccessCheckCallbackFunction(FailedAccessCheckCallback);
5867 * Tells V8 to capture current stack trace when uncaught exception occurs
5868 * and report it to the message listeners. The option is off by default.
5870 void SetCaptureStackTraceForUncaughtExceptions(
5871 bool capture, int frame_limit = 10,
5872 StackTrace::StackTraceOptions options = StackTrace::kOverview);
5875 * Enables the host application to provide a mechanism to be notified
5876 * and perform custom logging when V8 Allocates Executable Memory.
5878 void AddMemoryAllocationCallback(MemoryAllocationCallback callback,
5879 ObjectSpace space, AllocationAction action);
5882 * Removes callback that was installed by AddMemoryAllocationCallback.
5884 void RemoveMemoryAllocationCallback(MemoryAllocationCallback callback);
5887 * Iterates through all external resources referenced from current isolate
5888 * heap. GC is not invoked prior to iterating, therefore there is no
5889 * guarantee that visited objects are still alive.
5891 void VisitExternalResources(ExternalResourceVisitor* visitor);
5894 * Iterates through all the persistent handles in the current isolate's heap
5895 * that have class_ids.
5897 void VisitHandlesWithClassIds(PersistentHandleVisitor* visitor);
5900 * Iterates through all the persistent handles in the current isolate's heap
5901 * that have class_ids and are candidates to be marked as partially dependent
5902 * handles. This will visit handles to young objects created since the last
5903 * garbage collection but is free to visit an arbitrary superset of these
5906 void VisitHandlesForPartialDependence(PersistentHandleVisitor* visitor);
5909 template <class K, class V, class Traits>
5910 friend class PersistentValueMapBase;
5913 Isolate(const Isolate&);
5915 Isolate& operator=(const Isolate&);
5916 void* operator new(size_t size);
5917 void operator delete(void*, size_t);
5919 void SetObjectGroupId(internal::Object** object, UniqueId id);
5920 void SetReferenceFromGroup(UniqueId id, internal::Object** object);
5921 void SetReference(internal::Object** parent, internal::Object** child);
5922 void ReportExternalAllocationLimitReached();
5925 class V8_EXPORT StartupData {
5933 * EntropySource is used as a callback function when v8 needs a source
5936 typedef bool (*EntropySource)(unsigned char* buffer, size_t length);
5940 * ReturnAddressLocationResolver is used as a callback function when v8 is
5941 * resolving the location of a return address on the stack. Profilers that
5942 * change the return address on the stack can use this to resolve the stack
5943 * location to whereever the profiler stashed the original return address.
5945 * \param return_addr_location points to a location on stack where a machine
5946 * return address resides.
5947 * \returns either return_addr_location, or else a pointer to the profiler's
5948 * copy of the original return address.
5950 * \note the resolver function must not cause garbage collection.
5952 typedef uintptr_t (*ReturnAddressLocationResolver)(
5953 uintptr_t return_addr_location);
5957 * Container class for static utility functions.
5959 class V8_EXPORT V8 {
5961 /** Set the callback to invoke in case of fatal errors. */
5962 V8_INLINE static V8_DEPRECATE_SOON(
5963 "Use isolate version",
5964 void SetFatalErrorHandler(FatalErrorCallback that));
5967 * Set the callback to invoke to check if code generation from
5968 * strings should be allowed.
5970 V8_INLINE static V8_DEPRECATE_SOON(
5971 "Use isolate version", void SetAllowCodeGenerationFromStringsCallback(
5972 AllowCodeGenerationFromStringsCallback that));
5975 * Check if V8 is dead and therefore unusable. This is the case after
5976 * fatal errors such as out-of-memory situations.
5978 V8_INLINE static V8_DEPRECATE_SOON("no alternative", bool IsDead());
5981 * Hand startup data to V8, in case the embedder has chosen to build
5982 * V8 with external startup data.
5985 * - By default the startup data is linked into the V8 library, in which
5986 * case this function is not meaningful.
5987 * - If this needs to be called, it needs to be called before V8
5988 * tries to make use of its built-ins.
5989 * - To avoid unnecessary copies of data, V8 will point directly into the
5990 * given data blob, so pretty please keep it around until V8 exit.
5991 * - Compression of the startup blob might be useful, but needs to
5992 * handled entirely on the embedders' side.
5993 * - The call will abort if the data is invalid.
5995 static void SetNativesDataBlob(StartupData* startup_blob);
5996 static void SetSnapshotDataBlob(StartupData* startup_blob);
5999 * Create a new isolate and context for the purpose of capturing a snapshot
6000 * Returns { NULL, 0 } on failure.
6001 * The caller owns the data array in the return value.
6003 static StartupData CreateSnapshotDataBlob(const char* custom_source = NULL);
6006 * Adds a message listener.
6008 * The same message listener can be added more than once and in that
6009 * case it will be called more than once for each message.
6011 * If data is specified, it will be passed to the callback when it is called.
6012 * Otherwise, the exception object will be passed to the callback instead.
6014 V8_INLINE static V8_DEPRECATE_SOON(
6015 "Use isolate version",
6016 bool AddMessageListener(MessageCallback that,
6017 Local<Value> data = Local<Value>()));
6020 * Remove all message listeners from the specified callback function.
6022 V8_INLINE static V8_DEPRECATE_SOON(
6023 "Use isolate version", void RemoveMessageListeners(MessageCallback that));
6026 * Tells V8 to capture current stack trace when uncaught exception occurs
6027 * and report it to the message listeners. The option is off by default.
6029 V8_INLINE static V8_DEPRECATE_SOON(
6030 "Use isolate version",
6031 void SetCaptureStackTraceForUncaughtExceptions(
6032 bool capture, int frame_limit = 10,
6033 StackTrace::StackTraceOptions options = StackTrace::kOverview));
6036 * Sets V8 flags from a string.
6038 static void SetFlagsFromString(const char* str, int length);
6041 * Sets V8 flags from the command line.
6043 static void SetFlagsFromCommandLine(int* argc,
6047 /** Get the version string. */
6048 static const char* GetVersion();
6050 /** Callback function for reporting failed access checks.*/
6051 V8_INLINE static V8_DEPRECATE_SOON(
6052 "Use isolate version",
6053 void SetFailedAccessCheckCallbackFunction(FailedAccessCheckCallback));
6056 * Enables the host application to receive a notification before a
6057 * garbage collection. Allocations are not allowed in the
6058 * callback function, you therefore cannot manipulate objects (set
6059 * or delete properties for example) since it is possible such
6060 * operations will result in the allocation of objects. It is possible
6061 * to specify the GCType filter for your callback. But it is not possible to
6062 * register the same callback function two times with different
6065 static V8_DEPRECATE_SOON(
6066 "Use isolate version",
6067 void AddGCPrologueCallback(GCCallback callback,
6068 GCType gc_type_filter = kGCTypeAll));
6071 * This function removes callback which was installed by
6072 * AddGCPrologueCallback function.
6074 V8_INLINE static V8_DEPRECATE_SOON(
6075 "Use isolate version",
6076 void RemoveGCPrologueCallback(GCCallback callback));
6079 * Enables the host application to receive a notification after a
6080 * garbage collection. Allocations are not allowed in the
6081 * callback function, you therefore cannot manipulate objects (set
6082 * or delete properties for example) since it is possible such
6083 * operations will result in the allocation of objects. It is possible
6084 * to specify the GCType filter for your callback. But it is not possible to
6085 * register the same callback function two times with different
6088 static V8_DEPRECATE_SOON(
6089 "Use isolate version",
6090 void AddGCEpilogueCallback(GCCallback callback,
6091 GCType gc_type_filter = kGCTypeAll));
6094 * This function removes callback which was installed by
6095 * AddGCEpilogueCallback function.
6097 V8_INLINE static V8_DEPRECATE_SOON(
6098 "Use isolate version",
6099 void RemoveGCEpilogueCallback(GCCallback callback));
6102 * Enables the host application to provide a mechanism to be notified
6103 * and perform custom logging when V8 Allocates Executable Memory.
6105 V8_INLINE static V8_DEPRECATE_SOON(
6106 "Use isolate version",
6107 void AddMemoryAllocationCallback(MemoryAllocationCallback callback,
6109 AllocationAction action));
6112 * Removes callback that was installed by AddMemoryAllocationCallback.
6114 V8_INLINE static V8_DEPRECATE_SOON(
6115 "Use isolate version",
6116 void RemoveMemoryAllocationCallback(MemoryAllocationCallback callback));
6119 * Initializes V8. This function needs to be called before the first Isolate
6120 * is created. It always returns true.
6122 static bool Initialize();
6125 * Allows the host application to provide a callback which can be used
6126 * as a source of entropy for random number generators.
6128 static void SetEntropySource(EntropySource source);
6131 * Allows the host application to provide a callback that allows v8 to
6132 * cooperate with a profiler that rewrites return addresses on stack.
6134 static void SetReturnAddressLocationResolver(
6135 ReturnAddressLocationResolver return_address_resolver);
6138 * Forcefully terminate the current thread of JavaScript execution
6139 * in the given isolate.
6141 * This method can be used by any thread even if that thread has not
6142 * acquired the V8 lock with a Locker object.
6144 * \param isolate The isolate in which to terminate the current JS execution.
6146 V8_INLINE static V8_DEPRECATE_SOON("Use isolate version",
6147 void TerminateExecution(Isolate* isolate));
6150 * Is V8 terminating JavaScript execution.
6152 * Returns true if JavaScript execution is currently terminating
6153 * because of a call to TerminateExecution. In that case there are
6154 * still JavaScript frames on the stack and the termination
6155 * exception is still active.
6157 * \param isolate The isolate in which to check.
6159 V8_INLINE static V8_DEPRECATE_SOON(
6160 "Use isolate version",
6161 bool IsExecutionTerminating(Isolate* isolate = NULL));
6164 * Resume execution capability in the given isolate, whose execution
6165 * was previously forcefully terminated using TerminateExecution().
6167 * When execution is forcefully terminated using TerminateExecution(),
6168 * the isolate can not resume execution until all JavaScript frames
6169 * have propagated the uncatchable exception which is generated. This
6170 * method allows the program embedding the engine to handle the
6171 * termination event and resume execution capability, even if
6172 * JavaScript frames remain on the stack.
6174 * This method can be used by any thread even if that thread has not
6175 * acquired the V8 lock with a Locker object.
6177 * \param isolate The isolate in which to resume execution capability.
6179 V8_INLINE static V8_DEPRECATE_SOON(
6180 "Use isolate version", void CancelTerminateExecution(Isolate* isolate));
6183 * Releases any resources used by v8 and stops any utility threads
6184 * that may be running. Note that disposing v8 is permanent, it
6185 * cannot be reinitialized.
6187 * It should generally not be necessary to dispose v8 before exiting
6188 * a process, this should happen automatically. It is only necessary
6189 * to use if the process needs the resources taken up by v8.
6191 static bool Dispose();
6194 * Iterates through all external resources referenced from current isolate
6195 * heap. GC is not invoked prior to iterating, therefore there is no
6196 * guarantee that visited objects are still alive.
6198 V8_INLINE static V8_DEPRECATE_SOON(
6199 "Use isoalte version",
6200 void VisitExternalResources(ExternalResourceVisitor* visitor));
6203 * Iterates through all the persistent handles in the current isolate's heap
6204 * that have class_ids.
6206 V8_INLINE static V8_DEPRECATE_SOON(
6207 "Use isolate version",
6208 void VisitHandlesWithClassIds(PersistentHandleVisitor* visitor));
6211 * Iterates through all the persistent handles in isolate's heap that have
6214 V8_INLINE static V8_DEPRECATE_SOON(
6215 "Use isolate version",
6216 void VisitHandlesWithClassIds(Isolate* isolate,
6217 PersistentHandleVisitor* visitor));
6220 * Iterates through all the persistent handles in the current isolate's heap
6221 * that have class_ids and are candidates to be marked as partially dependent
6222 * handles. This will visit handles to young objects created since the last
6223 * garbage collection but is free to visit an arbitrary superset of these
6226 V8_INLINE static V8_DEPRECATE_SOON(
6227 "Use isolate version",
6228 void VisitHandlesForPartialDependence(Isolate* isolate,
6229 PersistentHandleVisitor* visitor));
6232 * Initialize the ICU library bundled with V8. The embedder should only
6233 * invoke this method when using the bundled ICU. Returns true on success.
6235 * If V8 was compiled with the ICU data in an external file, the location
6236 * of the data file has to be provided.
6238 static bool InitializeICU(const char* icu_data_file = NULL);
6241 * Initialize the external startup data. The embedder only needs to
6242 * invoke this method when external startup data was enabled in a build.
6244 * If V8 was compiled with the startup data in an external file, then
6245 * V8 needs to be given those external files during startup. There are
6246 * three ways to do this:
6247 * - InitializeExternalStartupData(const char*)
6248 * This will look in the given directory for files "natives_blob.bin"
6249 * and "snapshot_blob.bin" - which is what the default build calls them.
6250 * - InitializeExternalStartupData(const char*, const char*)
6251 * As above, but will directly use the two given file names.
6252 * - Call SetNativesDataBlob, SetNativesDataBlob.
6253 * This will read the blobs from the given data structures and will
6254 * not perform any file IO.
6256 static void InitializeExternalStartupData(const char* directory_path);
6257 static void InitializeExternalStartupData(const char* natives_blob,
6258 const char* snapshot_blob);
6260 * Sets the v8::Platform to use. This should be invoked before V8 is
6263 static void InitializePlatform(Platform* platform);
6266 * Clears all references to the v8::Platform. This should be invoked after
6269 static void ShutdownPlatform();
6274 static internal::Object** GlobalizeReference(internal::Isolate* isolate,
6275 internal::Object** handle);
6276 static internal::Object** CopyPersistent(internal::Object** handle);
6277 static void DisposeGlobal(internal::Object** global_handle);
6278 typedef WeakCallbackData<Value, void>::Callback WeakCallback;
6279 static void MakeWeak(internal::Object** global_handle, void* data,
6280 WeakCallback weak_callback);
6281 static void MakeWeak(internal::Object** global_handle, void* data,
6282 WeakCallbackInfo<void>::Callback weak_callback,
6283 WeakCallbackType type);
6284 static void MakeWeak(internal::Object** global_handle, void* data,
6286 int internal_field_index1,
6288 int internal_field_index2,
6289 WeakCallbackInfo<void>::Callback weak_callback);
6290 static void* ClearWeak(internal::Object** global_handle);
6291 static void Eternalize(Isolate* isolate,
6294 static Local<Value> GetEternal(Isolate* isolate, int index);
6296 static void FromJustIsNothing();
6297 static void ToLocalEmpty();
6298 static void InternalFieldOutOfBounds(int index);
6299 template <class T> friend class Local;
6301 friend class MaybeLocal;
6305 friend class WeakCallbackInfo;
6306 template <class T> friend class Eternal;
6307 template <class T> friend class PersistentBase;
6308 template <class T, class M> friend class Persistent;
6309 friend class Context;
6314 * A simple Maybe type, representing an object which may or may not have a
6315 * value, see https://hackage.haskell.org/package/base/docs/Data-Maybe.html.
6317 * If an API method returns a Maybe<>, the API method can potentially fail
6318 * either because an exception is thrown, or because an exception is pending,
6319 * e.g. because a previous API call threw an exception that hasn't been caught
6320 * yet, or because a TerminateExecution exception was thrown. In that case, a
6321 * "Nothing" value is returned.
6326 V8_INLINE bool IsNothing() const { return !has_value; }
6327 V8_INLINE bool IsJust() const { return has_value; }
6329 // Will crash if the Maybe<> is nothing.
6330 V8_INLINE T FromJust() const {
6331 if (V8_UNLIKELY(!IsJust())) V8::FromJustIsNothing();
6335 V8_INLINE T FromMaybe(const T& default_value) const {
6336 return has_value ? value : default_value;
6339 V8_INLINE bool operator==(const Maybe& other) const {
6340 return (IsJust() == other.IsJust()) &&
6341 (!IsJust() || FromJust() == other.FromJust());
6344 V8_INLINE bool operator!=(const Maybe& other) const {
6345 return !operator==(other);
6349 Maybe() : has_value(false) {}
6350 explicit Maybe(const T& t) : has_value(true), value(t) {}
6356 friend Maybe<U> Nothing();
6358 friend Maybe<U> Just(const U& u);
6363 inline Maybe<T> Nothing() {
6369 inline Maybe<T> Just(const T& t) {
6375 * An external exception handler.
6377 class V8_EXPORT TryCatch {
6380 * Creates a new try/catch block and registers it with v8. Note that
6381 * all TryCatch blocks should be stack allocated because the memory
6382 * location itself is compared against JavaScript try/catch blocks.
6384 V8_DEPRECATE_SOON("Use isolate version", TryCatch());
6387 * Creates a new try/catch block and registers it with v8. Note that
6388 * all TryCatch blocks should be stack allocated because the memory
6389 * location itself is compared against JavaScript try/catch blocks.
6391 TryCatch(Isolate* isolate);
6394 * Unregisters and deletes this try/catch block.
6399 * Returns true if an exception has been caught by this try/catch block.
6401 bool HasCaught() const;
6404 * For certain types of exceptions, it makes no sense to continue execution.
6406 * If CanContinue returns false, the correct action is to perform any C++
6407 * cleanup needed and then return. If CanContinue returns false and
6408 * HasTerminated returns true, it is possible to call
6409 * CancelTerminateExecution in order to continue calling into the engine.
6411 bool CanContinue() const;
6414 * Returns true if an exception has been caught due to script execution
6417 * There is no JavaScript representation of an execution termination
6418 * exception. Such exceptions are thrown when the TerminateExecution
6419 * methods are called to terminate a long-running script.
6421 * If such an exception has been thrown, HasTerminated will return true,
6422 * indicating that it is possible to call CancelTerminateExecution in order
6423 * to continue calling into the engine.
6425 bool HasTerminated() const;
6428 * Throws the exception caught by this TryCatch in a way that avoids
6429 * it being caught again by this same TryCatch. As with ThrowException
6430 * it is illegal to execute any JavaScript operations after calling
6431 * ReThrow; the caller must return immediately to where the exception
6434 Local<Value> ReThrow();
6437 * Returns the exception caught by this try/catch block. If no exception has
6438 * been caught an empty handle is returned.
6440 * The returned handle is valid until this TryCatch block has been destroyed.
6442 Local<Value> Exception() const;
6445 * Returns the .stack property of the thrown object. If no .stack
6446 * property is present an empty handle is returned.
6448 V8_DEPRECATE_SOON("Use maybe version.", Local<Value> StackTrace() const);
6449 V8_WARN_UNUSED_RESULT MaybeLocal<Value> StackTrace(
6450 Local<Context> context) const;
6453 * Returns the message associated with this exception. If there is
6454 * no message associated an empty handle is returned.
6456 * The returned handle is valid until this TryCatch block has been
6459 Local<v8::Message> Message() const;
6462 * Clears any exceptions that may have been caught by this try/catch block.
6463 * After this method has been called, HasCaught() will return false. Cancels
6464 * the scheduled exception if it is caught and ReThrow() is not called before.
6466 * It is not necessary to clear a try/catch block before using it again; if
6467 * another exception is thrown the previously caught exception will just be
6468 * overwritten. However, it is often a good idea since it makes it easier
6469 * to determine which operation threw a given exception.
6474 * Set verbosity of the external exception handler.
6476 * By default, exceptions that are caught by an external exception
6477 * handler are not reported. Call SetVerbose with true on an
6478 * external exception handler to have exceptions caught by the
6479 * handler reported as if they were not caught.
6481 void SetVerbose(bool value);
6484 * Set whether or not this TryCatch should capture a Message object
6485 * which holds source information about where the exception
6486 * occurred. True by default.
6488 void SetCaptureMessage(bool value);
6491 * There are cases when the raw address of C++ TryCatch object cannot be
6492 * used for comparisons with addresses into the JS stack. The cases are:
6493 * 1) ARM, ARM64 and MIPS simulators which have separate JS stack.
6494 * 2) Address sanitizer allocates local C++ object in the heap when
6495 * UseAfterReturn mode is enabled.
6496 * This method returns address that can be used for comparisons with
6497 * addresses into the JS stack. When neither simulator nor ASAN's
6498 * UseAfterReturn is enabled, then the address returned will be the address
6499 * of the C++ try catch handler itself.
6501 static void* JSStackComparableAddress(v8::TryCatch* handler) {
6502 if (handler == NULL) return NULL;
6503 return handler->js_stack_comparable_address_;
6507 void ResetInternal();
6509 // Make it hard to create heap-allocated TryCatch blocks.
6510 TryCatch(const TryCatch&);
6511 void operator=(const TryCatch&);
6512 void* operator new(size_t size);
6513 void operator delete(void*, size_t);
6515 v8::internal::Isolate* isolate_;
6516 v8::TryCatch* next_;
6519 void* js_stack_comparable_address_;
6520 bool is_verbose_ : 1;
6521 bool can_continue_ : 1;
6522 bool capture_message_ : 1;
6524 bool has_terminated_ : 1;
6526 friend class v8::internal::Isolate;
6534 * A container for extension names.
6536 class V8_EXPORT ExtensionConfiguration {
6538 ExtensionConfiguration() : name_count_(0), names_(NULL) { }
6539 ExtensionConfiguration(int name_count, const char* names[])
6540 : name_count_(name_count), names_(names) { }
6542 const char** begin() const { return &names_[0]; }
6543 const char** end() const { return &names_[name_count_]; }
6546 const int name_count_;
6547 const char** names_;
6552 * A sandboxed execution context with its own set of built-in objects
6555 class V8_EXPORT Context {
6558 * Returns the global proxy object.
6560 * Global proxy object is a thin wrapper whose prototype points to actual
6561 * context's global object with the properties like Object, etc. This is done
6562 * that way for security reasons (for more details see
6563 * https://wiki.mozilla.org/Gecko:SplitWindow).
6565 * Please note that changes to global proxy object prototype most probably
6566 * would break VM---v8 expects only global object as a prototype of global
6569 Local<Object> Global();
6572 * Detaches the global object from its context before
6573 * the global object can be reused to create a new context.
6575 void DetachGlobal();
6578 * Creates a new context and returns a handle to the newly allocated
6581 * \param isolate The isolate in which to create the context.
6583 * \param extensions An optional extension configuration containing
6584 * the extensions to be installed in the newly created context.
6586 * \param global_template An optional object template from which the
6587 * global object for the newly created context will be created.
6589 * \param global_object An optional global object to be reused for
6590 * the newly created context. This global object must have been
6591 * created by a previous call to Context::New with the same global
6592 * template. The state of the global object will be completely reset
6593 * and only object identify will remain.
6595 static Local<Context> New(
6596 Isolate* isolate, ExtensionConfiguration* extensions = NULL,
6597 Local<ObjectTemplate> global_template = Local<ObjectTemplate>(),
6598 Local<Value> global_object = Local<Value>());
6601 * Sets the security token for the context. To access an object in
6602 * another context, the security tokens must match.
6604 void SetSecurityToken(Local<Value> token);
6606 /** Restores the security token to the default value. */
6607 void UseDefaultSecurityToken();
6609 /** Returns the security token of this context.*/
6610 Local<Value> GetSecurityToken();
6613 * Enter this context. After entering a context, all code compiled
6614 * and run is compiled and run in this context. If another context
6615 * is already entered, this old context is saved so it can be
6616 * restored when the new context is exited.
6621 * Exit this context. Exiting the current context restores the
6622 * context that was in place when entering the current context.
6626 /** Returns an isolate associated with a current context. */
6627 v8::Isolate* GetIsolate();
6630 * The field at kDebugIdIndex is reserved for V8 debugger implementation.
6631 * The value is propagated to the scripts compiled in given Context and
6632 * can be used for filtering scripts.
6634 enum EmbedderDataFields { kDebugIdIndex = 0 };
6637 * Gets the embedder data with the given index, which must have been set by a
6638 * previous call to SetEmbedderData with the same index. Note that index 0
6639 * currently has a special meaning for Chrome's debugger.
6641 V8_INLINE Local<Value> GetEmbedderData(int index);
6644 * Gets the binding object used by V8 extras. Extra natives get a reference
6645 * to this object and can use it to "export" functionality by adding
6646 * properties. Extra natives can also "import" functionality by accessing
6647 * properties added by the embedder using the V8 API.
6649 Local<Object> GetExtrasBindingObject();
6652 * Sets the embedder data with the given index, growing the data as
6653 * needed. Note that index 0 currently has a special meaning for Chrome's
6656 void SetEmbedderData(int index, Local<Value> value);
6659 * Gets a 2-byte-aligned native pointer from the embedder data with the given
6660 * index, which must have bees set by a previous call to
6661 * SetAlignedPointerInEmbedderData with the same index. Note that index 0
6662 * currently has a special meaning for Chrome's debugger.
6664 V8_INLINE void* GetAlignedPointerFromEmbedderData(int index);
6667 * Sets a 2-byte-aligned native pointer in the embedder data with the given
6668 * index, growing the data as needed. Note that index 0 currently has a
6669 * special meaning for Chrome's debugger.
6671 void SetAlignedPointerInEmbedderData(int index, void* value);
6674 * Control whether code generation from strings is allowed. Calling
6675 * this method with false will disable 'eval' and the 'Function'
6676 * constructor for code running in this context. If 'eval' or the
6677 * 'Function' constructor are used an exception will be thrown.
6679 * If code generation from strings is not allowed the
6680 * V8::AllowCodeGenerationFromStrings callback will be invoked if
6681 * set before blocking the call to 'eval' or the 'Function'
6682 * constructor. If that callback returns true, the call will be
6683 * allowed, otherwise an exception will be thrown. If no callback is
6684 * set an exception will be thrown.
6686 void AllowCodeGenerationFromStrings(bool allow);
6689 * Returns true if code generation from strings is allowed for the context.
6690 * For more details see AllowCodeGenerationFromStrings(bool) documentation.
6692 bool IsCodeGenerationFromStringsAllowed();
6695 * Sets the error description for the exception that is thrown when
6696 * code generation from strings is not allowed and 'eval' or the 'Function'
6697 * constructor are called.
6699 void SetErrorMessageForCodeGenerationFromStrings(Local<String> message);
6702 * Estimate the memory in bytes retained by this context.
6704 size_t EstimatedSize();
6707 * Stack-allocated class which sets the execution context for all
6708 * operations executed within a local scope.
6712 explicit V8_INLINE Scope(Local<Context> context) : context_(context) {
6715 V8_INLINE ~Scope() { context_->Exit(); }
6718 Local<Context> context_;
6723 friend class Script;
6724 friend class Object;
6725 friend class Function;
6727 Local<Value> SlowGetEmbedderData(int index);
6728 void* SlowGetAlignedPointerFromEmbedderData(int index);
6733 * Multiple threads in V8 are allowed, but only one thread at a time is allowed
6734 * to use any given V8 isolate, see the comments in the Isolate class. The
6735 * definition of 'using a V8 isolate' includes accessing handles or holding onto
6736 * object pointers obtained from V8 handles while in the particular V8 isolate.
6737 * It is up to the user of V8 to ensure, perhaps with locking, that this
6738 * constraint is not violated. In addition to any other synchronization
6739 * mechanism that may be used, the v8::Locker and v8::Unlocker classes must be
6740 * used to signal thead switches to V8.
6742 * v8::Locker is a scoped lock object. While it's active, i.e. between its
6743 * construction and destruction, the current thread is allowed to use the locked
6744 * isolate. V8 guarantees that an isolate can be locked by at most one thread at
6745 * any time. In other words, the scope of a v8::Locker is a critical section.
6751 * v8::Locker locker(isolate);
6752 * v8::Isolate::Scope isolate_scope(isolate);
6754 * // Code using V8 and isolate goes here.
6756 * } // Destructor called here
6759 * If you wish to stop using V8 in a thread A you can do this either by
6760 * destroying the v8::Locker object as above or by constructing a v8::Unlocker
6766 * v8::Unlocker unlocker(isolate);
6768 * // Code not using V8 goes here while V8 can run in another thread.
6770 * } // Destructor called here.
6774 * The Unlocker object is intended for use in a long-running callback from V8,
6775 * where you want to release the V8 lock for other threads to use.
6777 * The v8::Locker is a recursive lock, i.e. you can lock more than once in a
6778 * given thread. This can be useful if you have code that can be called either
6779 * from code that holds the lock or from code that does not. The Unlocker is
6780 * not recursive so you can not have several Unlockers on the stack at once, and
6781 * you can not use an Unlocker in a thread that is not inside a Locker's scope.
6783 * An unlocker will unlock several lockers if it has to and reinstate the
6784 * correct depth of locking on its destruction, e.g.:
6789 * v8::Locker locker(isolate);
6790 * Isolate::Scope isolate_scope(isolate);
6793 * v8::Locker another_locker(isolate);
6794 * // V8 still locked (2 levels).
6797 * v8::Unlocker unlocker(isolate);
6801 * // V8 locked again (2 levels).
6803 * // V8 still locked (1 level).
6805 * // V8 Now no longer locked.
6808 class V8_EXPORT Unlocker {
6811 * Initialize Unlocker for a given Isolate.
6813 V8_INLINE explicit Unlocker(Isolate* isolate) { Initialize(isolate); }
6817 void Initialize(Isolate* isolate);
6819 internal::Isolate* isolate_;
6823 class V8_EXPORT Locker {
6826 * Initialize Locker for a given Isolate.
6828 V8_INLINE explicit Locker(Isolate* isolate) { Initialize(isolate); }
6833 * Returns whether or not the locker for a given isolate, is locked by the
6836 static bool IsLocked(Isolate* isolate);
6839 * Returns whether v8::Locker is being used by this V8 instance.
6841 static bool IsActive();
6844 void Initialize(Isolate* isolate);
6848 internal::Isolate* isolate_;
6850 // Disallow copying and assigning.
6851 Locker(const Locker&);
6852 void operator=(const Locker&);
6856 // --- Implementation ---
6859 namespace internal {
6861 const int kApiPointerSize = sizeof(void*); // NOLINT
6862 const int kApiIntSize = sizeof(int); // NOLINT
6863 const int kApiInt64Size = sizeof(int64_t); // NOLINT
6865 // Tag information for HeapObject.
6866 const int kHeapObjectTag = 1;
6867 const int kHeapObjectTagSize = 2;
6868 const intptr_t kHeapObjectTagMask = (1 << kHeapObjectTagSize) - 1;
6870 // Tag information for Smi.
6871 const int kSmiTag = 0;
6872 const int kSmiTagSize = 1;
6873 const intptr_t kSmiTagMask = (1 << kSmiTagSize) - 1;
6875 template <size_t ptr_size> struct SmiTagging;
6877 template<int kSmiShiftSize>
6878 V8_INLINE internal::Object* IntToSmi(int value) {
6879 int smi_shift_bits = kSmiTagSize + kSmiShiftSize;
6880 uintptr_t tagged_value =
6881 (static_cast<uintptr_t>(value) << smi_shift_bits) | kSmiTag;
6882 return reinterpret_cast<internal::Object*>(tagged_value);
6885 // Smi constants for 32-bit systems.
6886 template <> struct SmiTagging<4> {
6887 enum { kSmiShiftSize = 0, kSmiValueSize = 31 };
6888 static int SmiShiftSize() { return kSmiShiftSize; }
6889 static int SmiValueSize() { return kSmiValueSize; }
6890 V8_INLINE static int SmiToInt(const internal::Object* value) {
6891 int shift_bits = kSmiTagSize + kSmiShiftSize;
6892 // Throw away top 32 bits and shift down (requires >> to be sign extending).
6893 return static_cast<int>(reinterpret_cast<intptr_t>(value)) >> shift_bits;
6895 V8_INLINE static internal::Object* IntToSmi(int value) {
6896 return internal::IntToSmi<kSmiShiftSize>(value);
6898 V8_INLINE static bool IsValidSmi(intptr_t value) {
6899 // To be representable as an tagged small integer, the two
6900 // most-significant bits of 'value' must be either 00 or 11 due to
6901 // sign-extension. To check this we add 01 to the two
6902 // most-significant bits, and check if the most-significant bit is 0
6904 // CAUTION: The original code below:
6905 // bool result = ((value + 0x40000000) & 0x80000000) == 0;
6906 // may lead to incorrect results according to the C language spec, and
6907 // in fact doesn't work correctly with gcc4.1.1 in some cases: The
6908 // compiler may produce undefined results in case of signed integer
6909 // overflow. The computation must be done w/ unsigned ints.
6910 return static_cast<uintptr_t>(value + 0x40000000U) < 0x80000000U;
6914 // Smi constants for 64-bit systems.
6915 template <> struct SmiTagging<8> {
6916 enum { kSmiShiftSize = 31, kSmiValueSize = 32 };
6917 static int SmiShiftSize() { return kSmiShiftSize; }
6918 static int SmiValueSize() { return kSmiValueSize; }
6919 V8_INLINE static int SmiToInt(const internal::Object* value) {
6920 int shift_bits = kSmiTagSize + kSmiShiftSize;
6921 // Shift down and throw away top 32 bits.
6922 return static_cast<int>(reinterpret_cast<intptr_t>(value) >> shift_bits);
6924 V8_INLINE static internal::Object* IntToSmi(int value) {
6925 return internal::IntToSmi<kSmiShiftSize>(value);
6927 V8_INLINE static bool IsValidSmi(intptr_t value) {
6928 // To be representable as a long smi, the value must be a 32-bit integer.
6929 return (value == static_cast<int32_t>(value));
6933 typedef SmiTagging<kApiPointerSize> PlatformSmiTagging;
6934 const int kSmiShiftSize = PlatformSmiTagging::kSmiShiftSize;
6935 const int kSmiValueSize = PlatformSmiTagging::kSmiValueSize;
6936 V8_INLINE static bool SmiValuesAre31Bits() { return kSmiValueSize == 31; }
6937 V8_INLINE static bool SmiValuesAre32Bits() { return kSmiValueSize == 32; }
6940 * This class exports constants and functionality from within v8 that
6941 * is necessary to implement inline functions in the v8 api. Don't
6942 * depend on functions and constants defined here.
6946 // These values match non-compiler-dependent values defined within
6947 // the implementation of v8.
6948 static const int kHeapObjectMapOffset = 0;
6949 static const int kMapInstanceTypeAndBitFieldOffset =
6950 1 * kApiPointerSize + kApiIntSize;
6951 static const int kStringResourceOffset = 3 * kApiPointerSize;
6953 static const int kOddballKindOffset = 4 * kApiPointerSize;
6954 static const int kForeignAddressOffset = kApiPointerSize;
6955 static const int kJSObjectHeaderSize = 3 * kApiPointerSize;
6956 static const int kFixedArrayHeaderSize = 2 * kApiPointerSize;
6957 static const int kContextHeaderSize = 2 * kApiPointerSize;
6958 static const int kContextEmbedderDataIndex = 5;
6959 static const int kFullStringRepresentationMask = 0x07;
6960 static const int kStringEncodingMask = 0x4;
6961 static const int kExternalTwoByteRepresentationTag = 0x02;
6962 static const int kExternalOneByteRepresentationTag = 0x06;
6964 static const int kIsolateEmbedderDataOffset = 0 * kApiPointerSize;
6965 static const int kAmountOfExternalAllocatedMemoryOffset =
6966 4 * kApiPointerSize;
6967 static const int kAmountOfExternalAllocatedMemoryAtLastGlobalGCOffset =
6968 kAmountOfExternalAllocatedMemoryOffset + kApiInt64Size;
6969 static const int kIsolateRootsOffset =
6970 kAmountOfExternalAllocatedMemoryAtLastGlobalGCOffset + kApiInt64Size +
6972 static const int kUndefinedValueRootIndex = 5;
6973 static const int kNullValueRootIndex = 7;
6974 static const int kTrueValueRootIndex = 8;
6975 static const int kFalseValueRootIndex = 9;
6976 static const int kEmptyStringRootIndex = 10;
6978 // The external allocation limit should be below 256 MB on all architectures
6979 // to avoid that resource-constrained embedders run low on memory.
6980 static const int kExternalAllocationLimit = 192 * 1024 * 1024;
6982 static const int kNodeClassIdOffset = 1 * kApiPointerSize;
6983 static const int kNodeFlagsOffset = 1 * kApiPointerSize + 3;
6984 static const int kNodeStateMask = 0x7;
6985 static const int kNodeStateIsWeakValue = 2;
6986 static const int kNodeStateIsPendingValue = 3;
6987 static const int kNodeStateIsNearDeathValue = 4;
6988 static const int kNodeIsIndependentShift = 3;
6989 static const int kNodeIsPartiallyDependentShift = 4;
6991 static const int kJSObjectType = 0xb7;
6992 static const int kFirstNonstringType = 0x80;
6993 static const int kOddballType = 0x83;
6994 static const int kForeignType = 0x87;
6996 static const int kUndefinedOddballKind = 5;
6997 static const int kNullOddballKind = 3;
6999 static const uint32_t kNumIsolateDataSlots = 4;
7001 V8_EXPORT static void CheckInitializedImpl(v8::Isolate* isolate);
7002 V8_INLINE static void CheckInitialized(v8::Isolate* isolate) {
7003 #ifdef V8_ENABLE_CHECKS
7004 CheckInitializedImpl(isolate);
7008 V8_INLINE static bool HasHeapObjectTag(const internal::Object* value) {
7009 return ((reinterpret_cast<intptr_t>(value) & kHeapObjectTagMask) ==
7013 V8_INLINE static int SmiValue(const internal::Object* value) {
7014 return PlatformSmiTagging::SmiToInt(value);
7017 V8_INLINE static internal::Object* IntToSmi(int value) {
7018 return PlatformSmiTagging::IntToSmi(value);
7021 V8_INLINE static bool IsValidSmi(intptr_t value) {
7022 return PlatformSmiTagging::IsValidSmi(value);
7025 V8_INLINE static int GetInstanceType(const internal::Object* obj) {
7026 typedef internal::Object O;
7027 O* map = ReadField<O*>(obj, kHeapObjectMapOffset);
7028 // Map::InstanceType is defined so that it will always be loaded into
7029 // the LS 8 bits of one 16-bit word, regardless of endianess.
7030 return ReadField<uint16_t>(map, kMapInstanceTypeAndBitFieldOffset) & 0xff;
7033 V8_INLINE static int GetOddballKind(const internal::Object* obj) {
7034 typedef internal::Object O;
7035 return SmiValue(ReadField<O*>(obj, kOddballKindOffset));
7038 V8_INLINE static bool IsExternalTwoByteString(int instance_type) {
7039 int representation = (instance_type & kFullStringRepresentationMask);
7040 return representation == kExternalTwoByteRepresentationTag;
7043 V8_INLINE static uint8_t GetNodeFlag(internal::Object** obj, int shift) {
7044 uint8_t* addr = reinterpret_cast<uint8_t*>(obj) + kNodeFlagsOffset;
7045 return *addr & static_cast<uint8_t>(1U << shift);
7048 V8_INLINE static void UpdateNodeFlag(internal::Object** obj,
7049 bool value, int shift) {
7050 uint8_t* addr = reinterpret_cast<uint8_t*>(obj) + kNodeFlagsOffset;
7051 uint8_t mask = static_cast<uint8_t>(1U << shift);
7052 *addr = static_cast<uint8_t>((*addr & ~mask) | (value << shift));
7055 V8_INLINE static uint8_t GetNodeState(internal::Object** obj) {
7056 uint8_t* addr = reinterpret_cast<uint8_t*>(obj) + kNodeFlagsOffset;
7057 return *addr & kNodeStateMask;
7060 V8_INLINE static void UpdateNodeState(internal::Object** obj,
7062 uint8_t* addr = reinterpret_cast<uint8_t*>(obj) + kNodeFlagsOffset;
7063 *addr = static_cast<uint8_t>((*addr & ~kNodeStateMask) | value);
7066 V8_INLINE static void SetEmbedderData(v8::Isolate* isolate,
7069 uint8_t *addr = reinterpret_cast<uint8_t *>(isolate) +
7070 kIsolateEmbedderDataOffset + slot * kApiPointerSize;
7071 *reinterpret_cast<void**>(addr) = data;
7074 V8_INLINE static void* GetEmbedderData(const v8::Isolate* isolate,
7076 const uint8_t* addr = reinterpret_cast<const uint8_t*>(isolate) +
7077 kIsolateEmbedderDataOffset + slot * kApiPointerSize;
7078 return *reinterpret_cast<void* const*>(addr);
7081 V8_INLINE static internal::Object** GetRoot(v8::Isolate* isolate,
7083 uint8_t* addr = reinterpret_cast<uint8_t*>(isolate) + kIsolateRootsOffset;
7084 return reinterpret_cast<internal::Object**>(addr + index * kApiPointerSize);
7087 template <typename T>
7088 V8_INLINE static T ReadField(const internal::Object* ptr, int offset) {
7089 const uint8_t* addr =
7090 reinterpret_cast<const uint8_t*>(ptr) + offset - kHeapObjectTag;
7091 return *reinterpret_cast<const T*>(addr);
7094 template <typename T>
7095 V8_INLINE static T ReadEmbedderData(const v8::Context* context, int index) {
7096 typedef internal::Object O;
7097 typedef internal::Internals I;
7098 O* ctx = *reinterpret_cast<O* const*>(context);
7099 int embedder_data_offset = I::kContextHeaderSize +
7100 (internal::kApiPointerSize * I::kContextEmbedderDataIndex);
7101 O* embedder_data = I::ReadField<O*>(ctx, embedder_data_offset);
7103 I::kFixedArrayHeaderSize + (internal::kApiPointerSize * index);
7104 return I::ReadField<T>(embedder_data, value_offset);
7108 } // namespace internal
7112 Local<T> Local<T>::New(Isolate* isolate, Local<T> that) {
7113 return New(isolate, that.val_);
7117 Local<T> Local<T>::New(Isolate* isolate, const PersistentBase<T>& that) {
7118 return New(isolate, that.val_);
7123 Local<T> Local<T>::New(Isolate* isolate, T* that) {
7124 if (that == NULL) return Local<T>();
7126 internal::Object** p = reinterpret_cast<internal::Object**>(that_ptr);
7127 return Local<T>(reinterpret_cast<T*>(HandleScope::CreateHandle(
7128 reinterpret_cast<internal::Isolate*>(isolate), *p)));
7134 void Eternal<T>::Set(Isolate* isolate, Local<S> handle) {
7136 V8::Eternalize(isolate, reinterpret_cast<Value*>(*handle), &this->index_);
7141 Local<T> Eternal<T>::Get(Isolate* isolate) {
7142 return Local<T>(reinterpret_cast<T*>(*V8::GetEternal(isolate, index_)));
7147 Local<T> MaybeLocal<T>::ToLocalChecked() {
7148 if (V8_UNLIKELY(val_ == nullptr)) V8::ToLocalEmpty();
7149 return Local<T>(val_);
7154 void* WeakCallbackInfo<T>::GetInternalField(int index) const {
7155 #ifdef V8_ENABLE_CHECKS
7156 if (index < 0 || index >= kInternalFieldsInWeakCallback) {
7157 V8::InternalFieldOutOfBounds(index);
7160 return internal_fields_[index];
7165 T* PersistentBase<T>::New(Isolate* isolate, T* that) {
7166 if (that == NULL) return NULL;
7167 internal::Object** p = reinterpret_cast<internal::Object**>(that);
7168 return reinterpret_cast<T*>(
7169 V8::GlobalizeReference(reinterpret_cast<internal::Isolate*>(isolate),
7174 template <class T, class M>
7175 template <class S, class M2>
7176 void Persistent<T, M>::Copy(const Persistent<S, M2>& that) {
7179 if (that.IsEmpty()) return;
7180 internal::Object** p = reinterpret_cast<internal::Object**>(that.val_);
7181 this->val_ = reinterpret_cast<T*>(V8::CopyPersistent(p));
7182 M::Copy(that, this);
7187 bool PersistentBase<T>::IsIndependent() const {
7188 typedef internal::Internals I;
7189 if (this->IsEmpty()) return false;
7190 return I::GetNodeFlag(reinterpret_cast<internal::Object**>(this->val_),
7191 I::kNodeIsIndependentShift);
7196 bool PersistentBase<T>::IsNearDeath() const {
7197 typedef internal::Internals I;
7198 if (this->IsEmpty()) return false;
7199 uint8_t node_state =
7200 I::GetNodeState(reinterpret_cast<internal::Object**>(this->val_));
7201 return node_state == I::kNodeStateIsNearDeathValue ||
7202 node_state == I::kNodeStateIsPendingValue;
7207 bool PersistentBase<T>::IsWeak() const {
7208 typedef internal::Internals I;
7209 if (this->IsEmpty()) return false;
7210 return I::GetNodeState(reinterpret_cast<internal::Object**>(this->val_)) ==
7211 I::kNodeStateIsWeakValue;
7216 void PersistentBase<T>::Reset() {
7217 if (this->IsEmpty()) return;
7218 V8::DisposeGlobal(reinterpret_cast<internal::Object**>(this->val_));
7225 void PersistentBase<T>::Reset(Isolate* isolate, const Local<S>& other) {
7228 if (other.IsEmpty()) return;
7229 this->val_ = New(isolate, other.val_);
7235 void PersistentBase<T>::Reset(Isolate* isolate,
7236 const PersistentBase<S>& other) {
7239 if (other.IsEmpty()) return;
7240 this->val_ = New(isolate, other.val_);
7245 template <typename S, typename P>
7246 void PersistentBase<T>::SetWeak(
7248 typename WeakCallbackData<S, P>::Callback callback) {
7250 typedef typename WeakCallbackData<Value, void>::Callback Callback;
7251 V8::MakeWeak(reinterpret_cast<internal::Object**>(this->val_), parameter,
7252 reinterpret_cast<Callback>(callback));
7257 template <typename P>
7258 void PersistentBase<T>::SetWeak(
7260 typename WeakCallbackData<T, P>::Callback callback) {
7261 SetWeak<T, P>(parameter, callback);
7266 template <typename P>
7267 void PersistentBase<T>::SetPhantom(
7268 P* parameter, typename WeakCallbackInfo<P>::Callback callback,
7269 int internal_field_index1, int internal_field_index2) {
7270 typedef typename WeakCallbackInfo<void>::Callback Callback;
7271 V8::MakeWeak(reinterpret_cast<internal::Object**>(this->val_), parameter,
7272 internal_field_index1, internal_field_index2,
7273 reinterpret_cast<Callback>(callback));
7278 template <typename P>
7279 V8_INLINE void PersistentBase<T>::SetWeak(
7280 P* parameter, typename WeakCallbackInfo<P>::Callback callback,
7281 WeakCallbackType type) {
7282 typedef typename WeakCallbackInfo<void>::Callback Callback;
7283 V8::MakeWeak(reinterpret_cast<internal::Object**>(this->val_), parameter,
7284 reinterpret_cast<Callback>(callback), type);
7289 template <typename P>
7290 P* PersistentBase<T>::ClearWeak() {
7291 return reinterpret_cast<P*>(
7292 V8::ClearWeak(reinterpret_cast<internal::Object**>(this->val_)));
7297 void PersistentBase<T>::MarkIndependent() {
7298 typedef internal::Internals I;
7299 if (this->IsEmpty()) return;
7300 I::UpdateNodeFlag(reinterpret_cast<internal::Object**>(this->val_),
7302 I::kNodeIsIndependentShift);
7307 void PersistentBase<T>::MarkPartiallyDependent() {
7308 typedef internal::Internals I;
7309 if (this->IsEmpty()) return;
7310 I::UpdateNodeFlag(reinterpret_cast<internal::Object**>(this->val_),
7312 I::kNodeIsPartiallyDependentShift);
7317 void PersistentBase<T>::SetWrapperClassId(uint16_t class_id) {
7318 typedef internal::Internals I;
7319 if (this->IsEmpty()) return;
7320 internal::Object** obj = reinterpret_cast<internal::Object**>(this->val_);
7321 uint8_t* addr = reinterpret_cast<uint8_t*>(obj) + I::kNodeClassIdOffset;
7322 *reinterpret_cast<uint16_t*>(addr) = class_id;
7327 uint16_t PersistentBase<T>::WrapperClassId() const {
7328 typedef internal::Internals I;
7329 if (this->IsEmpty()) return 0;
7330 internal::Object** obj = reinterpret_cast<internal::Object**>(this->val_);
7331 uint8_t* addr = reinterpret_cast<uint8_t*>(obj) + I::kNodeClassIdOffset;
7332 return *reinterpret_cast<uint16_t*>(addr);
7336 template<typename T>
7337 ReturnValue<T>::ReturnValue(internal::Object** slot) : value_(slot) {}
7339 template<typename T>
7340 template<typename S>
7341 void ReturnValue<T>::Set(const Persistent<S>& handle) {
7343 if (V8_UNLIKELY(handle.IsEmpty())) {
7344 *value_ = GetDefaultValue();
7346 *value_ = *reinterpret_cast<internal::Object**>(*handle);
7350 template <typename T>
7351 template <typename S>
7352 void ReturnValue<T>::Set(const Global<S>& handle) {
7354 if (V8_UNLIKELY(handle.IsEmpty())) {
7355 *value_ = GetDefaultValue();
7357 *value_ = *reinterpret_cast<internal::Object**>(*handle);
7361 template <typename T>
7362 template <typename S>
7363 void ReturnValue<T>::Set(const Local<S> handle) {
7365 if (V8_UNLIKELY(handle.IsEmpty())) {
7366 *value_ = GetDefaultValue();
7368 *value_ = *reinterpret_cast<internal::Object**>(*handle);
7372 template<typename T>
7373 void ReturnValue<T>::Set(double i) {
7374 TYPE_CHECK(T, Number);
7375 Set(Number::New(GetIsolate(), i));
7378 template<typename T>
7379 void ReturnValue<T>::Set(int32_t i) {
7380 TYPE_CHECK(T, Integer);
7381 typedef internal::Internals I;
7382 if (V8_LIKELY(I::IsValidSmi(i))) {
7383 *value_ = I::IntToSmi(i);
7386 Set(Integer::New(GetIsolate(), i));
7389 template<typename T>
7390 void ReturnValue<T>::Set(uint32_t i) {
7391 TYPE_CHECK(T, Integer);
7392 // Can't simply use INT32_MAX here for whatever reason.
7393 bool fits_into_int32_t = (i & (1U << 31)) == 0;
7394 if (V8_LIKELY(fits_into_int32_t)) {
7395 Set(static_cast<int32_t>(i));
7398 Set(Integer::NewFromUnsigned(GetIsolate(), i));
7401 template<typename T>
7402 void ReturnValue<T>::Set(bool value) {
7403 TYPE_CHECK(T, Boolean);
7404 typedef internal::Internals I;
7407 root_index = I::kTrueValueRootIndex;
7409 root_index = I::kFalseValueRootIndex;
7411 *value_ = *I::GetRoot(GetIsolate(), root_index);
7414 template<typename T>
7415 void ReturnValue<T>::SetNull() {
7416 TYPE_CHECK(T, Primitive);
7417 typedef internal::Internals I;
7418 *value_ = *I::GetRoot(GetIsolate(), I::kNullValueRootIndex);
7421 template<typename T>
7422 void ReturnValue<T>::SetUndefined() {
7423 TYPE_CHECK(T, Primitive);
7424 typedef internal::Internals I;
7425 *value_ = *I::GetRoot(GetIsolate(), I::kUndefinedValueRootIndex);
7428 template<typename T>
7429 void ReturnValue<T>::SetEmptyString() {
7430 TYPE_CHECK(T, String);
7431 typedef internal::Internals I;
7432 *value_ = *I::GetRoot(GetIsolate(), I::kEmptyStringRootIndex);
7435 template<typename T>
7436 Isolate* ReturnValue<T>::GetIsolate() {
7437 // Isolate is always the pointer below the default value on the stack.
7438 return *reinterpret_cast<Isolate**>(&value_[-2]);
7441 template<typename T>
7442 template<typename S>
7443 void ReturnValue<T>::Set(S* whatever) {
7444 // Uncompilable to prevent inadvertent misuse.
7445 TYPE_CHECK(S*, Primitive);
7448 template<typename T>
7449 internal::Object* ReturnValue<T>::GetDefaultValue() {
7450 // Default value is always the pointer below value_ on the stack.
7455 template<typename T>
7456 FunctionCallbackInfo<T>::FunctionCallbackInfo(internal::Object** implicit_args,
7457 internal::Object** values,
7459 bool is_construct_call)
7460 : implicit_args_(implicit_args),
7463 is_construct_call_(is_construct_call) { }
7466 template<typename T>
7467 Local<Value> FunctionCallbackInfo<T>::operator[](int i) const {
7468 if (i < 0 || length_ <= i) return Local<Value>(*Undefined(GetIsolate()));
7469 return Local<Value>(reinterpret_cast<Value*>(values_ - i));
7473 template<typename T>
7474 Local<Function> FunctionCallbackInfo<T>::Callee() const {
7475 return Local<Function>(reinterpret_cast<Function*>(
7476 &implicit_args_[kCalleeIndex]));
7480 template<typename T>
7481 Local<Object> FunctionCallbackInfo<T>::This() const {
7482 return Local<Object>(reinterpret_cast<Object*>(values_ + 1));
7486 template<typename T>
7487 Local<Object> FunctionCallbackInfo<T>::Holder() const {
7488 return Local<Object>(reinterpret_cast<Object*>(
7489 &implicit_args_[kHolderIndex]));
7493 template<typename T>
7494 Local<Value> FunctionCallbackInfo<T>::Data() const {
7495 return Local<Value>(reinterpret_cast<Value*>(&implicit_args_[kDataIndex]));
7499 template<typename T>
7500 Isolate* FunctionCallbackInfo<T>::GetIsolate() const {
7501 return *reinterpret_cast<Isolate**>(&implicit_args_[kIsolateIndex]);
7505 template<typename T>
7506 ReturnValue<T> FunctionCallbackInfo<T>::GetReturnValue() const {
7507 return ReturnValue<T>(&implicit_args_[kReturnValueIndex]);
7511 template<typename T>
7512 bool FunctionCallbackInfo<T>::IsConstructCall() const {
7513 return is_construct_call_ & 0x1;
7517 template<typename T>
7518 int FunctionCallbackInfo<T>::Length() const {
7522 ScriptOrigin::ScriptOrigin(Local<Value> resource_name,
7523 Local<Integer> resource_line_offset,
7524 Local<Integer> resource_column_offset,
7525 Local<Boolean> resource_is_shared_cross_origin,
7526 Local<Integer> script_id,
7527 Local<Boolean> resource_is_embedder_debug_script,
7528 Local<Value> source_map_url,
7529 Local<Boolean> resource_is_opaque)
7530 : resource_name_(resource_name),
7531 resource_line_offset_(resource_line_offset),
7532 resource_column_offset_(resource_column_offset),
7533 options_(!resource_is_embedder_debug_script.IsEmpty() &&
7534 resource_is_embedder_debug_script->IsTrue(),
7535 !resource_is_shared_cross_origin.IsEmpty() &&
7536 resource_is_shared_cross_origin->IsTrue(),
7537 !resource_is_opaque.IsEmpty() && resource_is_opaque->IsTrue()),
7538 script_id_(script_id),
7539 source_map_url_(source_map_url) {}
7541 Local<Value> ScriptOrigin::ResourceName() const { return resource_name_; }
7544 Local<Integer> ScriptOrigin::ResourceLineOffset() const {
7545 return resource_line_offset_;
7549 Local<Integer> ScriptOrigin::ResourceColumnOffset() const {
7550 return resource_column_offset_;
7554 Local<Integer> ScriptOrigin::ScriptID() const { return script_id_; }
7557 Local<Value> ScriptOrigin::SourceMapUrl() const { return source_map_url_; }
7560 ScriptCompiler::Source::Source(Local<String> string, const ScriptOrigin& origin,
7562 : source_string(string),
7563 resource_name(origin.ResourceName()),
7564 resource_line_offset(origin.ResourceLineOffset()),
7565 resource_column_offset(origin.ResourceColumnOffset()),
7566 resource_options(origin.Options()),
7567 source_map_url(origin.SourceMapUrl()),
7568 cached_data(data) {}
7571 ScriptCompiler::Source::Source(Local<String> string,
7573 : source_string(string), cached_data(data) {}
7576 ScriptCompiler::Source::~Source() {
7581 const ScriptCompiler::CachedData* ScriptCompiler::Source::GetCachedData()
7587 Local<Boolean> Boolean::New(Isolate* isolate, bool value) {
7588 return value ? True(isolate) : False(isolate);
7592 void Template::Set(Isolate* isolate, const char* name, v8::Local<Data> value) {
7593 Set(v8::String::NewFromUtf8(isolate, name, NewStringType::kNormal)
7599 Local<Value> Object::GetInternalField(int index) {
7600 #ifndef V8_ENABLE_CHECKS
7601 typedef internal::Object O;
7602 typedef internal::HeapObject HO;
7603 typedef internal::Internals I;
7604 O* obj = *reinterpret_cast<O**>(this);
7605 // Fast path: If the object is a plain JSObject, which is the common case, we
7606 // know where to find the internal fields and can return the value directly.
7607 if (I::GetInstanceType(obj) == I::kJSObjectType) {
7608 int offset = I::kJSObjectHeaderSize + (internal::kApiPointerSize * index);
7609 O* value = I::ReadField<O*>(obj, offset);
7610 O** result = HandleScope::CreateHandle(reinterpret_cast<HO*>(obj), value);
7611 return Local<Value>(reinterpret_cast<Value*>(result));
7614 return SlowGetInternalField(index);
7618 void* Object::GetAlignedPointerFromInternalField(int index) {
7619 #ifndef V8_ENABLE_CHECKS
7620 typedef internal::Object O;
7621 typedef internal::Internals I;
7622 O* obj = *reinterpret_cast<O**>(this);
7623 // Fast path: If the object is a plain JSObject, which is the common case, we
7624 // know where to find the internal fields and can return the value directly.
7625 if (V8_LIKELY(I::GetInstanceType(obj) == I::kJSObjectType)) {
7626 int offset = I::kJSObjectHeaderSize + (internal::kApiPointerSize * index);
7627 return I::ReadField<void*>(obj, offset);
7630 return SlowGetAlignedPointerFromInternalField(index);
7634 String* String::Cast(v8::Value* value) {
7635 #ifdef V8_ENABLE_CHECKS
7638 return static_cast<String*>(value);
7642 Local<String> String::Empty(Isolate* isolate) {
7643 typedef internal::Object* S;
7644 typedef internal::Internals I;
7645 I::CheckInitialized(isolate);
7646 S* slot = I::GetRoot(isolate, I::kEmptyStringRootIndex);
7647 return Local<String>(reinterpret_cast<String*>(slot));
7651 String::ExternalStringResource* String::GetExternalStringResource() const {
7652 typedef internal::Object O;
7653 typedef internal::Internals I;
7654 O* obj = *reinterpret_cast<O* const*>(this);
7655 String::ExternalStringResource* result;
7656 if (I::IsExternalTwoByteString(I::GetInstanceType(obj))) {
7657 void* value = I::ReadField<void*>(obj, I::kStringResourceOffset);
7658 result = reinterpret_cast<String::ExternalStringResource*>(value);
7662 #ifdef V8_ENABLE_CHECKS
7663 VerifyExternalStringResource(result);
7669 String::ExternalStringResourceBase* String::GetExternalStringResourceBase(
7670 String::Encoding* encoding_out) const {
7671 typedef internal::Object O;
7672 typedef internal::Internals I;
7673 O* obj = *reinterpret_cast<O* const*>(this);
7674 int type = I::GetInstanceType(obj) & I::kFullStringRepresentationMask;
7675 *encoding_out = static_cast<Encoding>(type & I::kStringEncodingMask);
7676 ExternalStringResourceBase* resource = NULL;
7677 if (type == I::kExternalOneByteRepresentationTag ||
7678 type == I::kExternalTwoByteRepresentationTag) {
7679 void* value = I::ReadField<void*>(obj, I::kStringResourceOffset);
7680 resource = static_cast<ExternalStringResourceBase*>(value);
7682 #ifdef V8_ENABLE_CHECKS
7683 VerifyExternalStringResourceBase(resource, *encoding_out);
7689 bool Value::IsUndefined() const {
7690 #ifdef V8_ENABLE_CHECKS
7691 return FullIsUndefined();
7693 return QuickIsUndefined();
7697 bool Value::QuickIsUndefined() const {
7698 typedef internal::Object O;
7699 typedef internal::Internals I;
7700 O* obj = *reinterpret_cast<O* const*>(this);
7701 if (!I::HasHeapObjectTag(obj)) return false;
7702 if (I::GetInstanceType(obj) != I::kOddballType) return false;
7703 return (I::GetOddballKind(obj) == I::kUndefinedOddballKind);
7707 bool Value::IsNull() const {
7708 #ifdef V8_ENABLE_CHECKS
7709 return FullIsNull();
7711 return QuickIsNull();
7715 bool Value::QuickIsNull() const {
7716 typedef internal::Object O;
7717 typedef internal::Internals I;
7718 O* obj = *reinterpret_cast<O* const*>(this);
7719 if (!I::HasHeapObjectTag(obj)) return false;
7720 if (I::GetInstanceType(obj) != I::kOddballType) return false;
7721 return (I::GetOddballKind(obj) == I::kNullOddballKind);
7725 bool Value::IsString() const {
7726 #ifdef V8_ENABLE_CHECKS
7727 return FullIsString();
7729 return QuickIsString();
7733 bool Value::QuickIsString() const {
7734 typedef internal::Object O;
7735 typedef internal::Internals I;
7736 O* obj = *reinterpret_cast<O* const*>(this);
7737 if (!I::HasHeapObjectTag(obj)) return false;
7738 return (I::GetInstanceType(obj) < I::kFirstNonstringType);
7742 template <class T> Value* Value::Cast(T* value) {
7743 return static_cast<Value*>(value);
7747 Local<Boolean> Value::ToBoolean() const {
7748 return ToBoolean(Isolate::GetCurrent()->GetCurrentContext())
7749 .FromMaybe(Local<Boolean>());
7753 Local<Number> Value::ToNumber() const {
7754 return ToNumber(Isolate::GetCurrent()->GetCurrentContext())
7755 .FromMaybe(Local<Number>());
7759 Local<String> Value::ToString() const {
7760 return ToString(Isolate::GetCurrent()->GetCurrentContext())
7761 .FromMaybe(Local<String>());
7765 Local<String> Value::ToDetailString() const {
7766 return ToDetailString(Isolate::GetCurrent()->GetCurrentContext())
7767 .FromMaybe(Local<String>());
7771 Local<Object> Value::ToObject() const {
7772 return ToObject(Isolate::GetCurrent()->GetCurrentContext())
7773 .FromMaybe(Local<Object>());
7777 Local<Integer> Value::ToInteger() const {
7778 return ToInteger(Isolate::GetCurrent()->GetCurrentContext())
7779 .FromMaybe(Local<Integer>());
7783 Local<Uint32> Value::ToUint32() const {
7784 return ToUint32(Isolate::GetCurrent()->GetCurrentContext())
7785 .FromMaybe(Local<Uint32>());
7789 Local<Int32> Value::ToInt32() const {
7790 return ToInt32(Isolate::GetCurrent()->GetCurrentContext())
7791 .FromMaybe(Local<Int32>());
7795 Boolean* Boolean::Cast(v8::Value* value) {
7796 #ifdef V8_ENABLE_CHECKS
7799 return static_cast<Boolean*>(value);
7803 Name* Name::Cast(v8::Value* value) {
7804 #ifdef V8_ENABLE_CHECKS
7807 return static_cast<Name*>(value);
7811 Symbol* Symbol::Cast(v8::Value* value) {
7812 #ifdef V8_ENABLE_CHECKS
7815 return static_cast<Symbol*>(value);
7819 Number* Number::Cast(v8::Value* value) {
7820 #ifdef V8_ENABLE_CHECKS
7823 return static_cast<Number*>(value);
7827 Integer* Integer::Cast(v8::Value* value) {
7828 #ifdef V8_ENABLE_CHECKS
7831 return static_cast<Integer*>(value);
7835 Int32* Int32::Cast(v8::Value* value) {
7836 #ifdef V8_ENABLE_CHECKS
7839 return static_cast<Int32*>(value);
7843 Uint32* Uint32::Cast(v8::Value* value) {
7844 #ifdef V8_ENABLE_CHECKS
7847 return static_cast<Uint32*>(value);
7851 Date* Date::Cast(v8::Value* value) {
7852 #ifdef V8_ENABLE_CHECKS
7855 return static_cast<Date*>(value);
7859 StringObject* StringObject::Cast(v8::Value* value) {
7860 #ifdef V8_ENABLE_CHECKS
7863 return static_cast<StringObject*>(value);
7867 SymbolObject* SymbolObject::Cast(v8::Value* value) {
7868 #ifdef V8_ENABLE_CHECKS
7871 return static_cast<SymbolObject*>(value);
7875 NumberObject* NumberObject::Cast(v8::Value* value) {
7876 #ifdef V8_ENABLE_CHECKS
7879 return static_cast<NumberObject*>(value);
7883 BooleanObject* BooleanObject::Cast(v8::Value* value) {
7884 #ifdef V8_ENABLE_CHECKS
7887 return static_cast<BooleanObject*>(value);
7891 RegExp* RegExp::Cast(v8::Value* value) {
7892 #ifdef V8_ENABLE_CHECKS
7895 return static_cast<RegExp*>(value);
7899 Object* Object::Cast(v8::Value* value) {
7900 #ifdef V8_ENABLE_CHECKS
7903 return static_cast<Object*>(value);
7907 Array* Array::Cast(v8::Value* value) {
7908 #ifdef V8_ENABLE_CHECKS
7911 return static_cast<Array*>(value);
7915 Map* Map::Cast(v8::Value* value) {
7916 #ifdef V8_ENABLE_CHECKS
7919 return static_cast<Map*>(value);
7923 Set* Set::Cast(v8::Value* value) {
7924 #ifdef V8_ENABLE_CHECKS
7927 return static_cast<Set*>(value);
7931 Promise* Promise::Cast(v8::Value* value) {
7932 #ifdef V8_ENABLE_CHECKS
7935 return static_cast<Promise*>(value);
7939 Promise::Resolver* Promise::Resolver::Cast(v8::Value* value) {
7940 #ifdef V8_ENABLE_CHECKS
7943 return static_cast<Promise::Resolver*>(value);
7947 ArrayBuffer* ArrayBuffer::Cast(v8::Value* value) {
7948 #ifdef V8_ENABLE_CHECKS
7951 return static_cast<ArrayBuffer*>(value);
7955 ArrayBufferView* ArrayBufferView::Cast(v8::Value* value) {
7956 #ifdef V8_ENABLE_CHECKS
7959 return static_cast<ArrayBufferView*>(value);
7963 TypedArray* TypedArray::Cast(v8::Value* value) {
7964 #ifdef V8_ENABLE_CHECKS
7967 return static_cast<TypedArray*>(value);
7971 Uint8Array* Uint8Array::Cast(v8::Value* value) {
7972 #ifdef V8_ENABLE_CHECKS
7975 return static_cast<Uint8Array*>(value);
7979 Int8Array* Int8Array::Cast(v8::Value* value) {
7980 #ifdef V8_ENABLE_CHECKS
7983 return static_cast<Int8Array*>(value);
7987 Uint16Array* Uint16Array::Cast(v8::Value* value) {
7988 #ifdef V8_ENABLE_CHECKS
7991 return static_cast<Uint16Array*>(value);
7995 Int16Array* Int16Array::Cast(v8::Value* value) {
7996 #ifdef V8_ENABLE_CHECKS
7999 return static_cast<Int16Array*>(value);
8003 Uint32Array* Uint32Array::Cast(v8::Value* value) {
8004 #ifdef V8_ENABLE_CHECKS
8007 return static_cast<Uint32Array*>(value);
8011 Int32Array* Int32Array::Cast(v8::Value* value) {
8012 #ifdef V8_ENABLE_CHECKS
8015 return static_cast<Int32Array*>(value);
8019 Float32Array* Float32Array::Cast(v8::Value* value) {
8020 #ifdef V8_ENABLE_CHECKS
8023 return static_cast<Float32Array*>(value);
8027 Float64Array* Float64Array::Cast(v8::Value* value) {
8028 #ifdef V8_ENABLE_CHECKS
8031 return static_cast<Float64Array*>(value);
8035 Uint8ClampedArray* Uint8ClampedArray::Cast(v8::Value* value) {
8036 #ifdef V8_ENABLE_CHECKS
8039 return static_cast<Uint8ClampedArray*>(value);
8043 DataView* DataView::Cast(v8::Value* value) {
8044 #ifdef V8_ENABLE_CHECKS
8047 return static_cast<DataView*>(value);
8051 SharedArrayBuffer* SharedArrayBuffer::Cast(v8::Value* value) {
8052 #ifdef V8_ENABLE_CHECKS
8055 return static_cast<SharedArrayBuffer*>(value);
8059 Function* Function::Cast(v8::Value* value) {
8060 #ifdef V8_ENABLE_CHECKS
8063 return static_cast<Function*>(value);
8067 External* External::Cast(v8::Value* value) {
8068 #ifdef V8_ENABLE_CHECKS
8071 return static_cast<External*>(value);
8075 template<typename T>
8076 Isolate* PropertyCallbackInfo<T>::GetIsolate() const {
8077 return *reinterpret_cast<Isolate**>(&args_[kIsolateIndex]);
8081 template<typename T>
8082 Local<Value> PropertyCallbackInfo<T>::Data() const {
8083 return Local<Value>(reinterpret_cast<Value*>(&args_[kDataIndex]));
8087 template<typename T>
8088 Local<Object> PropertyCallbackInfo<T>::This() const {
8089 return Local<Object>(reinterpret_cast<Object*>(&args_[kThisIndex]));
8093 template<typename T>
8094 Local<Object> PropertyCallbackInfo<T>::Holder() const {
8095 return Local<Object>(reinterpret_cast<Object*>(&args_[kHolderIndex]));
8099 template<typename T>
8100 ReturnValue<T> PropertyCallbackInfo<T>::GetReturnValue() const {
8101 return ReturnValue<T>(&args_[kReturnValueIndex]);
8105 Local<Primitive> Undefined(Isolate* isolate) {
8106 typedef internal::Object* S;
8107 typedef internal::Internals I;
8108 I::CheckInitialized(isolate);
8109 S* slot = I::GetRoot(isolate, I::kUndefinedValueRootIndex);
8110 return Local<Primitive>(reinterpret_cast<Primitive*>(slot));
8114 Local<Primitive> Null(Isolate* isolate) {
8115 typedef internal::Object* S;
8116 typedef internal::Internals I;
8117 I::CheckInitialized(isolate);
8118 S* slot = I::GetRoot(isolate, I::kNullValueRootIndex);
8119 return Local<Primitive>(reinterpret_cast<Primitive*>(slot));
8123 Local<Boolean> True(Isolate* isolate) {
8124 typedef internal::Object* S;
8125 typedef internal::Internals I;
8126 I::CheckInitialized(isolate);
8127 S* slot = I::GetRoot(isolate, I::kTrueValueRootIndex);
8128 return Local<Boolean>(reinterpret_cast<Boolean*>(slot));
8132 Local<Boolean> False(Isolate* isolate) {
8133 typedef internal::Object* S;
8134 typedef internal::Internals I;
8135 I::CheckInitialized(isolate);
8136 S* slot = I::GetRoot(isolate, I::kFalseValueRootIndex);
8137 return Local<Boolean>(reinterpret_cast<Boolean*>(slot));
8141 void Isolate::SetData(uint32_t slot, void* data) {
8142 typedef internal::Internals I;
8143 I::SetEmbedderData(this, slot, data);
8147 void* Isolate::GetData(uint32_t slot) {
8148 typedef internal::Internals I;
8149 return I::GetEmbedderData(this, slot);
8153 uint32_t Isolate::GetNumberOfDataSlots() {
8154 typedef internal::Internals I;
8155 return I::kNumIsolateDataSlots;
8159 int64_t Isolate::AdjustAmountOfExternalAllocatedMemory(
8160 int64_t change_in_bytes) {
8161 typedef internal::Internals I;
8162 int64_t* amount_of_external_allocated_memory =
8163 reinterpret_cast<int64_t*>(reinterpret_cast<uint8_t*>(this) +
8164 I::kAmountOfExternalAllocatedMemoryOffset);
8165 int64_t* amount_of_external_allocated_memory_at_last_global_gc =
8166 reinterpret_cast<int64_t*>(
8167 reinterpret_cast<uint8_t*>(this) +
8168 I::kAmountOfExternalAllocatedMemoryAtLastGlobalGCOffset);
8169 int64_t amount = *amount_of_external_allocated_memory + change_in_bytes;
8170 if (change_in_bytes > 0 &&
8171 amount - *amount_of_external_allocated_memory_at_last_global_gc >
8172 I::kExternalAllocationLimit) {
8173 ReportExternalAllocationLimitReached();
8175 *amount_of_external_allocated_memory = amount;
8176 return *amount_of_external_allocated_memory;
8180 template<typename T>
8181 void Isolate::SetObjectGroupId(const Persistent<T>& object,
8183 TYPE_CHECK(Value, T);
8184 SetObjectGroupId(reinterpret_cast<v8::internal::Object**>(object.val_), id);
8188 template<typename T>
8189 void Isolate::SetReferenceFromGroup(UniqueId id,
8190 const Persistent<T>& object) {
8191 TYPE_CHECK(Value, T);
8192 SetReferenceFromGroup(id,
8193 reinterpret_cast<v8::internal::Object**>(object.val_));
8197 template<typename T, typename S>
8198 void Isolate::SetReference(const Persistent<T>& parent,
8199 const Persistent<S>& child) {
8200 TYPE_CHECK(Object, T);
8201 TYPE_CHECK(Value, S);
8202 SetReference(reinterpret_cast<v8::internal::Object**>(parent.val_),
8203 reinterpret_cast<v8::internal::Object**>(child.val_));
8207 Local<Value> Context::GetEmbedderData(int index) {
8208 #ifndef V8_ENABLE_CHECKS
8209 typedef internal::Object O;
8210 typedef internal::HeapObject HO;
8211 typedef internal::Internals I;
8212 HO* context = *reinterpret_cast<HO**>(this);
8214 HandleScope::CreateHandle(context, I::ReadEmbedderData<O*>(this, index));
8215 return Local<Value>(reinterpret_cast<Value*>(result));
8217 return SlowGetEmbedderData(index);
8222 void* Context::GetAlignedPointerFromEmbedderData(int index) {
8223 #ifndef V8_ENABLE_CHECKS
8224 typedef internal::Internals I;
8225 return I::ReadEmbedderData<void*>(this, index);
8227 return SlowGetAlignedPointerFromEmbedderData(index);
8232 void V8::SetAllowCodeGenerationFromStringsCallback(
8233 AllowCodeGenerationFromStringsCallback callback) {
8234 Isolate* isolate = Isolate::GetCurrent();
8235 isolate->SetAllowCodeGenerationFromStringsCallback(callback);
8240 Isolate* isolate = Isolate::GetCurrent();
8241 return isolate->IsDead();
8245 bool V8::AddMessageListener(MessageCallback that, Local<Value> data) {
8246 Isolate* isolate = Isolate::GetCurrent();
8247 return isolate->AddMessageListener(that, data);
8251 void V8::RemoveMessageListeners(MessageCallback that) {
8252 Isolate* isolate = Isolate::GetCurrent();
8253 isolate->RemoveMessageListeners(that);
8257 void V8::SetFailedAccessCheckCallbackFunction(
8258 FailedAccessCheckCallback callback) {
8259 Isolate* isolate = Isolate::GetCurrent();
8260 isolate->SetFailedAccessCheckCallbackFunction(callback);
8264 void V8::SetCaptureStackTraceForUncaughtExceptions(
8265 bool capture, int frame_limit, StackTrace::StackTraceOptions options) {
8266 Isolate* isolate = Isolate::GetCurrent();
8267 isolate->SetCaptureStackTraceForUncaughtExceptions(capture, frame_limit,
8272 void V8::SetFatalErrorHandler(FatalErrorCallback callback) {
8273 Isolate* isolate = Isolate::GetCurrent();
8274 isolate->SetFatalErrorHandler(callback);
8278 void V8::RemoveGCPrologueCallback(GCCallback callback) {
8279 Isolate* isolate = Isolate::GetCurrent();
8280 isolate->RemoveGCPrologueCallback(
8281 reinterpret_cast<v8::Isolate::GCCallback>(callback));
8285 void V8::RemoveGCEpilogueCallback(GCCallback callback) {
8286 Isolate* isolate = Isolate::GetCurrent();
8287 isolate->RemoveGCEpilogueCallback(
8288 reinterpret_cast<v8::Isolate::GCCallback>(callback));
8292 void V8::AddMemoryAllocationCallback(MemoryAllocationCallback callback,
8294 AllocationAction action) {
8295 Isolate* isolate = Isolate::GetCurrent();
8296 isolate->AddMemoryAllocationCallback(callback, space, action);
8300 void V8::RemoveMemoryAllocationCallback(MemoryAllocationCallback callback) {
8301 Isolate* isolate = Isolate::GetCurrent();
8302 isolate->RemoveMemoryAllocationCallback(callback);
8306 void V8::TerminateExecution(Isolate* isolate) { isolate->TerminateExecution(); }
8309 bool V8::IsExecutionTerminating(Isolate* isolate) {
8310 if (isolate == NULL) {
8311 isolate = Isolate::GetCurrent();
8313 return isolate->IsExecutionTerminating();
8317 void V8::CancelTerminateExecution(Isolate* isolate) {
8318 isolate->CancelTerminateExecution();
8322 void V8::VisitExternalResources(ExternalResourceVisitor* visitor) {
8323 Isolate* isolate = Isolate::GetCurrent();
8324 isolate->VisitExternalResources(visitor);
8328 void V8::VisitHandlesWithClassIds(PersistentHandleVisitor* visitor) {
8329 Isolate* isolate = Isolate::GetCurrent();
8330 isolate->VisitHandlesWithClassIds(visitor);
8334 void V8::VisitHandlesWithClassIds(Isolate* isolate,
8335 PersistentHandleVisitor* visitor) {
8336 isolate->VisitHandlesWithClassIds(visitor);
8340 void V8::VisitHandlesForPartialDependence(Isolate* isolate,
8341 PersistentHandleVisitor* visitor) {
8342 isolate->VisitHandlesForPartialDependence(visitor);
8347 * A simple shell that takes a list of expressions on the
8348 * command-line and executes them.
8353 * \example process.cc