Viewing file:  v8-local-handle.h (24.35 KB) -rw-r--r--
Select action/file-type:
 (+) |  (+) |  (+) | Code (+) | Session (+) |  (+) | SDB (+) |  (+) |  (+) |  (+) |  (+) |  (+) |
// Copyright 2021 the V8 project authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef INCLUDE_V8_LOCAL_HANDLE_H_
#define INCLUDE_V8_LOCAL_HANDLE_H_
#include <stddef.h>
#include <type_traits>
#include <vector>
#include "v8-handle-base.h" // NOLINT(build/include_directory)
#include "v8-internal.h" // NOLINT(build/include_directory)
namespace v8 {
template <class T>
class LocalBase;
template <class T>
class Local;
template <class T>
class LocalVector;
template <class F>
class MaybeLocal;
template <class T>
class Eternal;
template <class T>
class Global;
template <class T>
class NonCopyablePersistentTraits;
template <class T>
class PersistentBase;
template <class T, class M = NonCopyablePersistentTraits<T>>
class Persistent;
class TracedReferenceBase;
template <class T>
class BasicTracedReference;
template <class F>
class TracedReference;
class Boolean;
class Context;
class EscapableHandleScope;
template <class F>
class FunctionCallbackInfo;
class Isolate;
class Object;
template <class F1, class F2, class F3>
class PersistentValueMapBase;
class Primitive;
class Private;
template <class F>
class PropertyCallbackInfo;
template <class F>
class ReturnValue;
class String;
template <class F>
class Traced;
class TypecheckWitness;
class Utils;
namespace debug {
class ConsoleCallArguments;
}
namespace internal {
template <typename T>
class CustomArguments;
template <typename T>
class LocalUnchecked;
class SamplingHeapProfiler;
} // namespace internal
namespace api_internal {
// Called when ToLocalChecked is called on an empty Local.
V8_EXPORT void ToLocalEmpty();
} // namespace api_internal
/**
* A stack-allocated class that governs a number of local handles.
* After a handle scope has been created, all local handles will be
* allocated within that handle scope until either the handle scope is
* deleted or another handle scope is created. If there is already a
* handle scope and a new one is created, all allocations will take
* place in the new handle scope until it is deleted. After that,
* new handles will again be allocated in the original handle scope.
*
* After the handle scope of a local handle has been deleted the
* garbage collector will no longer track the object stored in the
* handle and may deallocate it. The behavior of accessing a handle
* for which the handle scope has been deleted is undefined.
*/
class V8_EXPORT V8_NODISCARD HandleScope {
public:
explicit HandleScope(Isolate* isolate);
~HandleScope();
/**
* Counts the number of allocated handles.
*/
static int NumberOfHandles(Isolate* isolate);
V8_INLINE Isolate* GetIsolate() const {
return reinterpret_cast<Isolate*>(i_isolate_);
}
HandleScope(const HandleScope&) = delete;
void operator=(const HandleScope&) = delete;
static internal::Address* CreateHandleForCurrentIsolate(
internal::Address value);
protected:
V8_INLINE HandleScope() = default;
void Initialize(Isolate* isolate);
static internal::Address* CreateHandle(internal::Isolate* i_isolate,
internal::Address value);
private:
// Declaring operator new and delete as deleted is not spec compliant.
// Therefore declare them private instead to disable dynamic alloc
void* operator new(size_t size);
void* operator new[](size_t size);
void operator delete(void*, size_t);
void operator delete[](void*, size_t);
internal::Isolate* i_isolate_;
internal::Address* prev_next_;
internal::Address* prev_limit_;
#ifdef V8_ENABLE_CHECKS
int scope_level_ = 0;
#endif
// LocalBase<T>::New uses CreateHandle with an Isolate* parameter.
template <typename T>
friend class LocalBase;
// Object::GetInternalField and Context::GetEmbedderData use CreateHandle with
// a HeapObject in their shortcuts.
friend class Object;
friend class Context;
};
/**
* A base class for local handles.
* Its implementation depends on whether direct handle support is enabled.
* When it is, a local handle contains a direct pointer to the referenced
* object, otherwise it contains an indirect pointer.
*/
#ifdef V8_ENABLE_DIRECT_HANDLE
template <typename T>
class LocalBase : public api_internal::DirectHandleBase {
protected:
template <class F>
friend class Local;
V8_INLINE LocalBase() = default;
V8_INLINE explicit LocalBase(internal::Address ptr) : DirectHandleBase(ptr) {}
template <typename S>
V8_INLINE LocalBase(const LocalBase<S>& other) : DirectHandleBase(other) {}
V8_INLINE static LocalBase<T> New(Isolate* isolate, internal::Address value) {
return LocalBase<T>(value);
}
V8_INLINE static LocalBase<T> New(Isolate* isolate, T* that) {
return LocalBase<T>::New(isolate,
internal::ValueHelper::ValueAsAddress(that));
}
V8_INLINE static LocalBase<T> FromSlot(internal::Address* slot) {
if (slot == nullptr) return LocalBase<T>();
return LocalBase<T>(*slot);
}
V8_INLINE static LocalBase<T> FromRepr(
internal::ValueHelper::InternalRepresentationType repr) {
return LocalBase<T>(repr);
}
};
#else // !V8_ENABLE_DIRECT_HANDLE
template <typename T>
class LocalBase : public api_internal::IndirectHandleBase {
protected:
template <class F>
friend class Local;
V8_INLINE LocalBase() = default;
V8_INLINE explicit LocalBase(internal::Address* location)
: IndirectHandleBase(location) {}
template <typename S>
V8_INLINE LocalBase(const LocalBase<S>& other) : IndirectHandleBase(other) {}
V8_INLINE static LocalBase<T> New(Isolate* isolate, internal::Address value) {
return LocalBase(HandleScope::CreateHandle(
reinterpret_cast<internal::Isolate*>(isolate), value));
}
V8_INLINE static LocalBase<T> New(Isolate* isolate, T* that) {
if (internal::ValueHelper::IsEmpty(that)) return LocalBase<T>();
return LocalBase<T>::New(isolate,
internal::ValueHelper::ValueAsAddress(that));
}
V8_INLINE static LocalBase<T> FromSlot(internal::Address* slot) {
return LocalBase<T>(slot);
}
V8_INLINE static LocalBase<T> FromRepr(
internal::ValueHelper::InternalRepresentationType repr) {
return LocalBase<T>(repr);
}
};
#endif // V8_ENABLE_DIRECT_HANDLE
/**
* An object reference managed by the v8 garbage collector.
*
* All objects returned from v8 have to be tracked by the garbage collector so
* that it knows that the objects are still alive. Also, because the garbage
* collector may move objects, it is unsafe to point directly to an object.
* Instead, all objects are stored in handles which are known by the garbage
* collector and updated whenever an object moves. Handles should always be
* passed by value (except in cases like out-parameters) and they should never
* be allocated on the heap.
*
* There are two types of handles: local and persistent handles.
*
* Local handles are light-weight and transient and typically used in local
* operations. They are managed by HandleScopes. That means that a HandleScope
* must exist on the stack when they are created and that they are only valid
* inside of the HandleScope active during their creation. For passing a local
* handle to an outer HandleScope, an EscapableHandleScope and its Escape()
* method must be used.
*
* Persistent handles can be used when storing objects across several
* independent operations and have to be explicitly deallocated when they're no
* longer used.
*
* It is safe to extract the object stored in the handle by dereferencing the
* handle (for instance, to extract the Object* from a Local<Object>); the value
* will still be governed by a handle behind the scenes and the same rules apply
* to these values as to their handles.
*/
template <class T>
class V8_TRIVIAL_ABI Local : public LocalBase<T>,
#ifdef V8_ENABLE_LOCAL_OFF_STACK_CHECK
public api_internal::StackAllocated<true>
#else
public api_internal::StackAllocated<false>
#endif
{
public:
/**
* Default constructor: Returns an empty handle.
*/
V8_INLINE Local() = default;
/**
* Constructor for handling automatic up casting.
* Ex. Local<Object> can be passed when Local<Value> is expected but not
* the other way round.
*/
template <class S>
requires std::is_base_of_v<T, S>
V8_INLINE Local(Local<S> that) : LocalBase<T>(that) {}
V8_INLINE T* operator->() const { return this->template value<T>(); }
V8_INLINE T* operator*() const { return this->operator->(); }
/**
* Checks whether two handles are equal or different.
* They are equal iff they are both empty or they are both non-empty and the
* objects to which they refer are physically equal.
*
* If both handles refer to JS objects, this is the same as strict
* non-equality. For primitives, such as numbers or strings, a `true` return
* value does not indicate that the values aren't equal in the JavaScript
* sense. Use `Value::StrictEquals()` to check primitives for equality.
*/
template <class S>
V8_INLINE bool operator==(const Local<S>& that) const {
return internal::HandleHelper::EqualHandles(*this, that);
}
template <class S>
V8_INLINE bool operator==(const PersistentBase<S>& that) const {
return internal::HandleHelper::EqualHandles(*this, that);
}
template <class S>
V8_INLINE bool operator!=(const Local<S>& that) const {
return !operator==(that);
}
template <class S>
V8_INLINE bool operator!=(const Persistent<S>& that) const {
return !operator==(that);
}
/**
* Cast a handle to a subclass, e.g. Local<Value> to Local<Object>.
* This is only valid if the handle actually refers to a value of the
* target type or if the handle is empty.
*/
template <class S>
V8_INLINE static Local<T> Cast(Local<S> 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()) return Local<T>();
T::Cast(that.template value<S>());
#endif
return Local<T>(LocalBase<T>(that));
}
/**
* Calling this is equivalent to Local<S>::Cast().
* In particular, this is only valid if the handle actually refers to a value
* of the target type or if the handle is empty.
*/
template <class S>
V8_INLINE Local<S> As() const {
return Local<S>::Cast(*this);
}
/**
* Create a local handle for the content of another handle.
* The referee is kept alive by the local handle even when
* the original handle is destroyed/disposed.
*/
V8_INLINE static Local<T> New(Isolate* isolate, Local<T> that) {
return New(isolate, that.template value<T, true>());
}
V8_INLINE static Local<T> New(Isolate* isolate,
const PersistentBase<T>& that) {
return New(isolate, that.template value<T, true>());
}
V8_INLINE static Local<T> New(Isolate* isolate,
const BasicTracedReference<T>& that) {
return New(isolate, that.template value<T, true>());
}
private:
friend class TracedReferenceBase;
friend class Utils;
template <class F>
friend class Eternal;
template <class F>
friend class Global;
template <class F>
friend class Local;
template <class F>
friend class MaybeLocal;
template <class F, class M>
friend class Persistent;
template <class F>
friend class FunctionCallbackInfo;
template <class F>
friend class PropertyCallbackInfo;
friend class String;
friend class Object;
friend class Context;
friend class Isolate;
friend class Private;
template <class F>
friend class internal::CustomArguments;
friend Local<Primitive> Undefined(Isolate* isolate);
friend Local<Primitive> Null(Isolate* isolate);
friend Local<Boolean> True(Isolate* isolate);
friend Local<Boolean> False(Isolate* isolate);
friend class HandleScope;
friend class EscapableHandleScope;
friend class InternalEscapableScope;
template <class F1, class F2, class F3>
friend class PersistentValueMapBase;
template <class F>
friend class ReturnValue;
template <class F>
friend class Traced;
friend class internal::SamplingHeapProfiler;
friend class internal::HandleHelper;
friend class debug::ConsoleCallArguments;
friend class internal::LocalUnchecked<T>;
explicit Local(no_checking_tag do_not_check)
: LocalBase<T>(), StackAllocated(do_not_check) {}
explicit Local(const Local<T>& other, no_checking_tag do_not_check)
: LocalBase<T>(other), StackAllocated(do_not_check) {}
V8_INLINE explicit Local(const LocalBase<T>& other) : LocalBase<T>(other) {}
V8_INLINE static Local<T> FromRepr(
internal::ValueHelper::InternalRepresentationType repr) {
return Local<T>(LocalBase<T>::FromRepr(repr));
}
V8_INLINE static Local<T> FromSlot(internal::Address* slot) {
return Local<T>(LocalBase<T>::FromSlot(slot));
}
#ifdef V8_ENABLE_DIRECT_HANDLE
friend class TypecheckWitness;
V8_INLINE static Local<T> FromAddress(internal::Address ptr) {
return Local<T>(LocalBase<T>(ptr));
}
#endif // V8_ENABLE_DIRECT_HANDLE
V8_INLINE static Local<T> New(Isolate* isolate, internal::Address value) {
return Local<T>(LocalBase<T>::New(isolate, value));
}
V8_INLINE static Local<T> New(Isolate* isolate, T* that) {
return Local<T>(LocalBase<T>::New(isolate, that));
}
// Unsafe cast, should be avoided.
template <class S>
V8_INLINE Local<S> UnsafeAs() const {
return Local<S>(LocalBase<S>(*this));
}
};
namespace internal {
// A local variant that is suitable for off-stack allocation.
// Used internally by LocalVector<T>. Not to be used directly!
template <typename T>
class V8_TRIVIAL_ABI LocalUnchecked : public Local<T> {
public:
LocalUnchecked() : Local<T>(Local<T>::do_not_check) {}
#if defined(V8_ENABLE_LOCAL_OFF_STACK_CHECK) && V8_HAS_ATTRIBUTE_TRIVIAL_ABI
// In this case, the check is also enforced in the copy constructor and we
// need to suppress it.
LocalUnchecked(
const LocalUnchecked& other) noexcept // NOLINT(runtime/explicit)
: Local<T>(other, Local<T>::do_not_check) {}
LocalUnchecked& operator=(const LocalUnchecked&) noexcept = default;
#endif
// Implicit conversion from Local.
LocalUnchecked(const Local<T>& other) noexcept // NOLINT(runtime/explicit)
: Local<T>(other, Local<T>::do_not_check) {}
};
#ifdef V8_ENABLE_DIRECT_HANDLE
// Off-stack allocated direct locals must be registered as strong roots.
// For off-stack indirect locals, this is not necessary.
template <typename T>
class StrongRootAllocator<LocalUnchecked<T>> : public StrongRootAllocatorBase {
public:
using value_type = LocalUnchecked<T>;
static_assert(std::is_standard_layout_v<value_type>);
static_assert(sizeof(value_type) == sizeof(Address));
template <typename HeapOrIsolateT>
explicit StrongRootAllocator(HeapOrIsolateT* heap_or_isolate)
: StrongRootAllocatorBase(heap_or_isolate) {}
template <typename U>
StrongRootAllocator(const StrongRootAllocator<U>& other) noexcept
: StrongRootAllocatorBase(other) {}
value_type* allocate(size_t n) {
return reinterpret_cast<value_type*>(allocate_impl(n));
}
void deallocate(value_type* p, size_t n) noexcept {
return deallocate_impl(reinterpret_cast<Address*>(p), n);
}
};
#endif // V8_ENABLE_DIRECT_HANDLE
} // namespace internal
template <typename T>
class LocalVector {
private:
using element_type = internal::LocalUnchecked<T>;
#ifdef V8_ENABLE_DIRECT_HANDLE
using allocator_type = internal::StrongRootAllocator<element_type>;
static allocator_type make_allocator(Isolate* isolate) noexcept {
return allocator_type(isolate);
}
#else
using allocator_type = std::allocator<element_type>;
static allocator_type make_allocator(Isolate* isolate) noexcept {
return allocator_type();
}
#endif // V8_ENABLE_DIRECT_HANDLE
using vector_type = std::vector<element_type, allocator_type>;
public:
using value_type = Local<T>;
using reference = value_type&;
using const_reference = const value_type&;
using size_type = size_t;
using difference_type = ptrdiff_t;
using iterator =
internal::WrappedIterator<typename vector_type::iterator, Local<T>>;
using const_iterator =
internal::WrappedIterator<typename vector_type::const_iterator,
const Local<T>>;
explicit LocalVector(Isolate* isolate) : backing_(make_allocator(isolate)) {}
LocalVector(Isolate* isolate, size_t n)
: backing_(n, make_allocator(isolate)) {}
explicit LocalVector(Isolate* isolate, std::initializer_list<Local<T>> init)
: backing_(make_allocator(isolate)) {
if (init.size() == 0) return;
backing_.reserve(init.size());
backing_.insert(backing_.end(), init.begin(), init.end());
}
iterator begin() noexcept { return iterator(backing_.begin()); }
const_iterator begin() const noexcept {
return const_iterator(backing_.begin());
}
iterator end() noexcept { return iterator(backing_.end()); }
const_iterator end() const noexcept { return const_iterator(backing_.end()); }
size_t size() const noexcept { return backing_.size(); }
bool empty() const noexcept { return backing_.empty(); }
void reserve(size_t n) { backing_.reserve(n); }
void shrink_to_fit() { backing_.shrink_to_fit(); }
Local<T>& operator[](size_t n) { return backing_[n]; }
const Local<T>& operator[](size_t n) const { return backing_[n]; }
Local<T>& at(size_t n) { return backing_.at(n); }
const Local<T>& at(size_t n) const { return backing_.at(n); }
Local<T>& front() { return backing_.front(); }
const Local<T>& front() const { return backing_.front(); }
Local<T>& back() { return backing_.back(); }
const Local<T>& back() const { return backing_.back(); }
Local<T>* data() noexcept { return backing_.data(); }
const Local<T>* data() const noexcept { return backing_.data(); }
iterator insert(const_iterator pos, const Local<T>& value) {
return iterator(backing_.insert(pos.base(), value));
}
template <typename InputIt>
iterator insert(const_iterator pos, InputIt first, InputIt last) {
return iterator(backing_.insert(pos.base(), first, last));
}
iterator insert(const_iterator pos, std::initializer_list<Local<T>> init) {
return iterator(backing_.insert(pos.base(), init.begin(), init.end()));
}
LocalVector<T>& operator=(std::initializer_list<Local<T>> init) {
backing_.clear();
backing_.reserve(init.size());
backing_.insert(backing_.end(), init.begin(), init.end());
return *this;
}
void push_back(const Local<T>& x) { backing_.push_back(x); }
void pop_back() { backing_.pop_back(); }
template <typename... Args>
void emplace_back(Args&&... args) {
backing_.push_back(value_type{std::forward<Args>(args)...});
}
void clear() noexcept { backing_.clear(); }
void resize(size_t n) { backing_.resize(n); }
void swap(LocalVector<T>& other) { backing_.swap(other.backing_); }
friend bool operator==(const LocalVector<T>& x, const LocalVector<T>& y) {
return x.backing_ == y.backing_;
}
friend bool operator!=(const LocalVector<T>& x, const LocalVector<T>& y) {
return x.backing_ != y.backing_;
}
friend bool operator<(const LocalVector<T>& x, const LocalVector<T>& y) {
return x.backing_ < y.backing_;
}
friend bool operator>(const LocalVector<T>& x, const LocalVector<T>& y) {
return x.backing_ > y.backing_;
}
friend bool operator<=(const LocalVector<T>& x, const LocalVector<T>& y) {
return x.backing_ <= y.backing_;
}
friend bool operator>=(const LocalVector<T>& x, const LocalVector<T>& y) {
return x.backing_ >= y.backing_;
}
private:
vector_type backing_;
};
#if !defined(V8_IMMINENT_DEPRECATION_WARNINGS)
// Handle is an alias for Local for historical reasons.
template <class T>
using Handle = Local<T>;
#endif
/**
* A MaybeLocal<> is a wrapper around Local<> that enforces a check whether
* the Local<> is empty before it can be used.
*
* If an API method returns a MaybeLocal<>, the API method can potentially fail
* either because an exception is thrown, or because an exception is pending,
* e.g. because a previous API call threw an exception that hasn't been caught
* yet, or because a TerminateExecution exception was thrown. In that case, an
* empty MaybeLocal is returned.
*/
template <class T>
class MaybeLocal {
public:
/**
* Default constructor: Returns an empty handle.
*/
V8_INLINE MaybeLocal() = default;
/**
* Implicitly construct MaybeLocal from Local.
*/
template <class S>
requires std::is_base_of_v<T, S>
V8_INLINE MaybeLocal(Local<S> that) : local_(that) {}
/**
* Implicitly up-cast MaybeLocal<S> to MaybeLocal<T> if T is a base of S.
*/
template <class S>
requires std::is_base_of_v<T, S>
V8_INLINE MaybeLocal(MaybeLocal<S> that) : local_(that.local_) {}
V8_INLINE bool IsEmpty() const { return local_.IsEmpty(); }
/**
* Converts this MaybeLocal<> to a Local<>. If this MaybeLocal<> is empty,
* |false| is returned and |out| is assigned with nullptr.
*/
template <class S>
V8_WARN_UNUSED_RESULT V8_INLINE bool ToLocal(Local<S>* out) const {
*out = local_;
return !IsEmpty();
}
/**
* Converts this MaybeLocal<> to a Local<>. If this MaybeLocal<> is empty,
* V8 will crash the process.
*/
V8_INLINE Local<T> ToLocalChecked() {
if (V8_UNLIKELY(IsEmpty())) api_internal::ToLocalEmpty();
return local_;
}
/**
* Converts this MaybeLocal<> to a Local<>, using a default value if this
* MaybeLocal<> is empty.
*/
template <class S>
V8_INLINE Local<S> FromMaybe(Local<S> default_value) const {
return IsEmpty() ? default_value : Local<S>(local_);
}
/**
* Cast a handle to a subclass, e.g. MaybeLocal<Value> to MaybeLocal<Object>.
* This is only valid if the handle actually refers to a value of the target
* type or if the handle is empty.
*/
template <class S>
V8_INLINE static MaybeLocal<T> Cast(MaybeLocal<S> that) {
return MaybeLocal<T>{Local<T>::Cast(that.local_)};
}
/**
* Calling this is equivalent to MaybeLocal<S>::Cast().
* In particular, this is only valid if the handle actually refers to a value
* of the target type or if the handle is empty.
*/
template <class S>
V8_INLINE MaybeLocal<S> As() const {
return MaybeLocal<S>::Cast(*this);
}
private:
Local<T> local_;
template <typename S>
friend class MaybeLocal;
};
/**
* A HandleScope which first allocates a handle in the current scope
* which will be later filled with the escape value.
*/
class V8_EXPORT V8_NODISCARD EscapableHandleScopeBase : public HandleScope {
public:
explicit EscapableHandleScopeBase(Isolate* isolate);
V8_INLINE ~EscapableHandleScopeBase() = default;
EscapableHandleScopeBase(const EscapableHandleScopeBase&) = delete;
void operator=(const EscapableHandleScopeBase&) = delete;
void* operator new(size_t size) = delete;
void* operator new[](size_t size) = delete;
void operator delete(void*, size_t) = delete;
void operator delete[](void*, size_t) = delete;
protected:
/**
* Pushes the value into the previous scope and returns a handle to it.
* Cannot be called twice.
*/
internal::Address* EscapeSlot(internal::Address* escape_value);
private:
internal::Address* escape_slot_;
};
class V8_EXPORT V8_NODISCARD EscapableHandleScope
: public EscapableHandleScopeBase {
public:
explicit EscapableHandleScope(Isolate* isolate)
: EscapableHandleScopeBase(isolate) {}
V8_INLINE ~EscapableHandleScope() = default;
template <class T>
V8_INLINE Local<T> Escape(Local<T> value) {
#ifdef V8_ENABLE_DIRECT_HANDLE
return value;
#else
if (value.IsEmpty()) return value;
return Local<T>::FromSlot(EscapeSlot(value.slot()));
#endif
}
template <class T>
V8_INLINE MaybeLocal<T> EscapeMaybe(MaybeLocal<T> value) {
return Escape(value.FromMaybe(Local<T>()));
}
};
/**
* A SealHandleScope acts like a handle scope in which no handle allocations
* are allowed. It can be useful for debugging handle leaks.
* Handles can be allocated within inner normal HandleScopes.
*/
class V8_EXPORT V8_NODISCARD SealHandleScope {
public:
explicit SealHandleScope(Isolate* isolate);
~SealHandleScope();
SealHandleScope(const SealHandleScope&) = delete;
void operator=(const SealHandleScope&) = delete;
void* operator new(size_t size) = delete;
void* operator new[](size_t size) = delete;
void operator delete(void*, size_t) = delete;
void operator delete[](void*, size_t) = delete;
private:
internal::Isolate* const i_isolate_;
internal::Address* prev_limit_;
int prev_sealed_level_;
};
} // namespace v8
#endif // INCLUDE_V8_LOCAL_HANDLE_H_
|