V8_INLINE void SetWeak(P* parameter,
typename WeakCallbackInfo::Callback callback,
WeakCallbackType type);
/**
* Turns this handle into a weak phantom handle without finalization callback.
* The handle will be reset automatically when the garbage collector detects
* that the object is no longer reachable.
* A related function Isolate::NumberOfPhantomHandleResetsSinceLastCall
* returns how many phantom handles were reset by the garbage collector.
*/
V8_INLINE void SetWeak();
template
V8_INLINE P* ClearWeak();
// TODO(dcarney): remove this.
V8_INLINE void ClearWeak() { ClearWeak(); }
/**
* Annotates the strong handle with the given label, which is then used by the
* heap snapshot generator as a name of the edge from the root to the handle.
* The function does not take ownership of the label and assumes that the
* label is valid as long as the handle is valid.
*/
V8_INLINE void AnnotateStrongRetainer(const char* label);
/** Returns true if the handle's reference is weak. */
V8_INLINE bool IsWeak() const;
/**
* Assigns a wrapper class ID to the handle.
*/
V8_INLINE void SetWrapperClassId(uint16_t class_id);
/**
* Returns the class ID previously assigned to this handle or 0 if no class ID
* was previously assigned.
*/
V8_INLINE uint16_t WrapperClassId() const;
PersistentBase(const PersistentBase& other) = delete;
void operator=(const PersistentBase&) = delete;
private:
friend class Isolate;
friend class Utils;
template friend class Local;
template friend class Persistent;
template
friend class Global;
template friend class PersistentBase;
template friend class ReturnValue;
template
friend class PersistentValueMapBase;
template friend class PersistentValueVector;
friend class Object;
explicit V8_INLINE PersistentBase(T* val) : val_(val) {}
V8_INLINE static T* New(Isolate* isolate, T* that);
T* val_;
};
/**
* Default traits for Persistent. This class does not allow
* use of the copy constructor or assignment operator.
* At present kResetInDestructor is not set, but that will change in a future
* version.
*/
template
class NonCopyablePersistentTraits {
public:
using NonCopyablePersistent = Persistent>;
static const bool kResetInDestructor = false;
template
V8_INLINE static void Copy(const Persistent& source,
NonCopyablePersistent* dest) {
static_assert(sizeof(S) < 0,
"NonCopyablePersistentTraits::Copy is not instantiable");
}
};
/**
* Helper class traits to allow copying and assignment of Persistent.
* This will clone the contents of storage cell, but not any of the flags, etc.
*/
template
struct CopyablePersistentTraits {
using CopyablePersistent = Persistent>;
static const bool kResetInDestructor = true;
template
static V8_INLINE void Copy(const Persistent& source,
CopyablePersistent* dest) {
// do nothing, just allow copy
}
};
/**
* A PersistentBase which allows copy and assignment.
*
* Copy, assignment and destructor behavior is controlled by the traits
* class M.
*
* Note: Persistent class hierarchy is subject to future changes.
*/
template class Persistent : public PersistentBase {
public:
/**
* A Persistent with no storage cell.
*/
V8_INLINE Persistent() : PersistentBase(nullptr) {}
/**
* Construct a Persistent from a Local.
* When the Local is non-empty, a new storage cell is created
* pointing to the same object, and no flags are set.
*/
template
V8_INLINE Persistent(Isolate* isolate, Local that)
: PersistentBase(PersistentBase::New(isolate, *that)) {
static_assert(std::is_base_of::value, "type check");
}
/**
* Construct a Persistent from a Persistent.
* When the Persistent is non-empty, a new storage cell is created
* pointing to the same object, and no flags are set.
*/
template
V8_INLINE Persistent(Isolate* isolate, const Persistent& that)
: PersistentBase(PersistentBase::New(isolate, *that)) {
static_assert(std::is_base_of::value, "type check");
}
/**
* The copy constructors and assignment operator create a Persistent
* exactly as the Persistent constructor, but the Copy function from the
* traits class is called, allowing the setting of flags based on the
* copied Persistent.
*/
V8_INLINE Persistent(const Persistent& that) : PersistentBase(nullptr) {
Copy(that);
}
template
V8_INLINE Persistent(const Persistent& that) : PersistentBase(0) {
Copy(that);
}
V8_INLINE Persistent& operator=(const Persistent& that) {
Copy(that);
return *this;
}
template
V8_INLINE Persistent& operator=(const Persistent& that) {
Copy(that);
return *this;
}
/**
* The destructor will dispose the Persistent based on the
* kResetInDestructor flags in the traits class. Since not calling dispose
* can result in a memory leak, it is recommended to always set this flag.
*/
V8_INLINE ~Persistent() {
if (M::kResetInDestructor) this->Reset();
}
// TODO(dcarney): this is pretty useless, fix or remove
template
V8_INLINE static Persistent& Cast(const Persistent& that) {
#ifdef V8_ENABLE_CHECKS
// If we're going to perform the type check then we have to check
// that the handle isn't empty before doing the checked cast.
if (!that.IsEmpty()) T::Cast(*that);
#endif
return reinterpret_cast&>(const_cast&>(that));
}
// TODO(dcarney): this is pretty useless, fix or remove
template
V8_INLINE Persistent& As() const {
return Persistent::Cast(*this);
}
private:
friend class Isolate;
friend class Utils;
template friend class Local;
template friend class Persistent;
template friend class ReturnValue;
explicit V8_INLINE Persistent(T* that) : PersistentBase(that) {}
V8_INLINE T* operator*() const { return this->val_; }
template
V8_INLINE void Copy(const Persistent& that);
};
/**
* A PersistentBase which has move semantics.
*
* Note: Persistent class hierarchy is subject to future changes.
*/
template
class Global : public PersistentBase {
public:
/**
* A Global with no storage cell.
*/
V8_INLINE Global() : PersistentBase(nullptr) {}
/**
* Construct a Global from a Local.
* When the Local is non-empty, a new storage cell is created
* pointing to the same object, and no flags are set.
*/
template
V8_INLINE Global(Isolate* isolate, Local that)
: PersistentBase(PersistentBase::New(isolate, *that)) {
static_assert(std::is_base_of::value, "type check");
}
/**
* Construct a Global from a PersistentBase.
* When the Persistent is non-empty, a new storage cell is created
* pointing to the same object, and no flags are set.
*/
template
V8_INLINE Global(Isolate* isolate, const PersistentBase& that)
: PersistentBase(PersistentBase::New(isolate, that.val_)) {
static_assert(std::is_base_of::value, "type check");
}
/**
* Move constructor.
*/
V8_INLINE Global(Global&& other);
V8_INLINE ~Global() { this->Reset(); }
/**
* Move via assignment.
*/
template
V8_INLINE Global& operator=(Global&& rhs);
/**
* Pass allows returning uniques from functions, etc.
*/
Global Pass() { return static_cast(*this); }
/*
* For compatibility with Chromium's base::Bind (base::Passed).
*/
using MoveOnlyTypeForCPP03 = void;
Global(const Global&) = delete;
void operator=(const Global&) = delete;
private:
template
friend class ReturnValue;
V8_INLINE T* operator*() const { return this->val_; }
};
// UniquePersistent is an alias for Global for historical reason.
template
using UniquePersistent = Global;
/**
* Deprecated. Use |TracedReference| instead.
*/
template
struct TracedGlobalTrait {};
class TracedReferenceBase {
public:
/**
* Returns true if the reference is empty, i.e., has not been assigned
* object.
*/
bool IsEmpty() const { return val_ == nullptr; }
/**
* If non-empty, destroy the underlying storage cell. |IsEmpty| will return
* true after this call.
*/
V8_INLINE void Reset();
/**
* Construct a Local from this handle.
*/
V8_INLINE v8::Local Get(v8::Isolate* isolate) const;
/**
* Returns true if this TracedReference is empty, i.e., has not been
* assigned an object. This version of IsEmpty is thread-safe.
*/
bool IsEmptyThreadSafe() const {
return this->GetSlotThreadSafe() == nullptr;
}
/**
* Assigns a wrapper class ID to the handle.
*/
V8_INLINE void SetWrapperClassId(uint16_t class_id);
/**
* Returns the class ID previously assigned to this handle or 0 if no class ID
* was previously assigned.
*/
V8_INLINE uint16_t WrapperClassId() const;
protected:
/**
* Update this reference in a thread-safe way.
*/
void SetSlotThreadSafe(void* new_val) {
reinterpret_cast*>(&val_)->store(
new_val, std::memory_order_relaxed);
}
/**
* Get this reference in a thread-safe way
*/
const void* GetSlotThreadSafe() const {
return reinterpret_cast const*>(&val_)->load(
std::memory_order_relaxed);
}
V8_EXPORT void CheckValue() const;
// val_ points to a GlobalHandles node.
internal::Address* val_ = nullptr;
friend class internal::BasicTracedReferenceExtractor;
template
friend class Local;
template
friend bool operator==(const TracedReferenceBase&, const Local&);
friend bool operator==(const TracedReferenceBase&,
const TracedReferenceBase&);
};
/**
* A traced handle with copy and move semantics. The handle is to be used
* together with |v8::EmbedderHeapTracer| or as part of GarbageCollected objects
* (see v8-cppgc.h) and specifies edges from C++ objects to JavaScript.
*
* The exact semantics are:
* - Tracing garbage collections use |v8::EmbedderHeapTracer| or cppgc.
* - Non-tracing garbage collections refer to
* |v8::EmbedderRootsHandler::IsRoot()| whether the handle should
* be treated as root or not.
*
* Note that the base class cannot be instantiated itself. Choose from
* - TracedGlobal
* - TracedReference
*/
template
class BasicTracedReference : public TracedReferenceBase {
public:
/**
* Construct a Local from this handle.
*/
Local Get(Isolate* isolate) const { return Local::New(isolate, *this); }
template
V8_INLINE BasicTracedReference& As() const {
return reinterpret_cast&>(
const_cast&>(*this));
}
T* operator->() const {
#ifdef V8_ENABLE_CHECKS
CheckValue();
#endif // V8_ENABLE_CHECKS
return reinterpret_cast(val_);
}
T* operator*() const {
#ifdef V8_ENABLE_CHECKS
CheckValue();
#endif // V8_ENABLE_CHECKS
return reinterpret_cast(val_);
}
private:
enum DestructionMode { kWithDestructor, kWithoutDestructor };
/**
* An empty BasicTracedReference without storage cell.
*/
BasicTracedReference() = default;
V8_INLINE static internal::Address* New(Isolate* isolate, T* that, void* slot,
DestructionMode destruction_mode);
friend class EmbedderHeapTracer;
template
friend class Local;
friend class Object;
template
friend class TracedGlobal;
template
friend class TracedReference;
template
friend class BasicTracedReference;
template
friend class ReturnValue;
};
/**
* A traced handle with destructor that clears the handle. For more details see
* BasicTracedReference.
*/
template
class TracedGlobal : public BasicTracedReference {
public:
using BasicTracedReference::Reset;
/**
* Destructor resetting the handle.Is
*/
~TracedGlobal() { this->Reset(); }
/**
* An empty TracedGlobal without storage cell.
*/
TracedGlobal() : BasicTracedReference() {}
/**
* Construct a TracedGlobal from a Local.
*
* When the Local is non-empty, a new storage cell is created
* pointing to the same object.
*/
template
TracedGlobal(Isolate* isolate, Local that) : BasicTracedReference() {
this->val_ = this->New(isolate, that.val_, &this->val_,
BasicTracedReference::kWithDestructor);
static_assert(std::is_base_of::value, "type check");
}
/**
* Move constructor initializing TracedGlobal from an existing one.
*/
V8_INLINE TracedGlobal(TracedGlobal&& other) {
// Forward to operator=.
*this = std::move(other);
}
/**
* Move constructor initializing TracedGlobal from an existing one.
*/
template
V8_INLINE TracedGlobal(TracedGlobal&& other) {
// Forward to operator=.
*this = std::move(other);
}
/**
* Copy constructor initializing TracedGlobal from an existing one.
*/
V8_INLINE TracedGlobal(const TracedGlobal& other) {
// Forward to operator=;
*this = other;
}
/**
* Copy constructor initializing TracedGlobal from an existing one.
*/
template
V8_INLINE TracedGlobal(const TracedGlobal& other) {
// Forward to operator=;
*this = other;
}
/**
* Move assignment operator initializing TracedGlobal from an existing one.
*/
V8_INLINE TracedGlobal& operator=(TracedGlobal&& rhs);
/**
* Move assignment operator initializing TracedGlobal from an existing one.
*/
template
V8_INLINE TracedGlobal& operator=(TracedGlobal&& rhs);
/**
* Copy assignment operator initializing TracedGlobal from an existing one.
*
* Note: Prohibited when |other| has a finalization callback set through
* |SetFinalizationCallback|.
*/
V8_INLINE TracedGlobal& operator=(const TracedGlobal& rhs);
/**
* Copy assignment operator initializing TracedGlobal from an existing one.
*
* Note: Prohibited when |other| has a finalization callback set through
* |SetFinalizationCallback|.
*/
template
V8_INLINE TracedGlobal& operator=(const TracedGlobal& rhs);
/**
* If non-empty, destroy the underlying storage cell and create a new one with
* the contents of other if other is non empty
*/
template
V8_INLINE void Reset(Isolate* isolate, const Local& other);
template
V8_INLINE TracedGlobal& As() const {
return reinterpret_cast&>(
const_cast&>(*this));
}
/**
* Adds a finalization callback to the handle. The type of this callback is
* similar to WeakCallbackType::kInternalFields, i.e., it will pass the
* parameter and the first two internal fields of the object.
*
* The callback is then supposed to reset the handle in the callback. No
* further V8 API may be called in this callback. In case additional work
* involving V8 needs to be done, a second callback can be scheduled using
* WeakCallbackInfo::SetSecondPassCallback.
*/
V8_INLINE void SetFinalizationCallback(
void* parameter, WeakCallbackInfo::Callback callback);
};
/**
* A traced handle without destructor that clears the handle. The embedder needs
* to ensure that the handle is not accessed once the V8 object has been
* reclaimed. This can happen when the handle is not passed through the
* EmbedderHeapTracer. For more details see BasicTracedReference.
*
* The reference assumes the embedder has precise knowledge about references at
* all times. In case V8 needs to separately handle on-stack references, the
* embedder is required to set the stack start through
* |EmbedderHeapTracer::SetStackStart|.
*/
template
class TracedReference : public BasicTracedReference {
public:
using BasicTracedReference::Reset;
/**
* An empty TracedReference without storage cell.
*/
TracedReference() : BasicTracedReference() {}
/**
* Construct a TracedReference from a Local.
*
* When the Local is non-empty, a new storage cell is created
* pointing to the same object.
*/
template
TracedReference(Isolate* isolate, Local