include/node/v8-handle-base.h

0001 // Copyright 2023 the V8 project authors. All rights reserved.
0002 // Use of this source code is governed by a BSD-style license that can be
0003 // found in the LICENSE file.
0004
0005 #ifndef INCLUDE_V8_HANDLE_BASE_H_
0006 #define INCLUDE_V8_HANDLE_BASE_H_
0007
0008 #include "v8-internal.h"  // NOLINT(build/include_directory)
0009
0010 namespace v8::api_internal {
0011
0012 template <bool check_statically_enabled>
0013 class StackAllocated {
0014  public:
0015   V8_INLINE StackAllocated() = default;
0016
0017  protected:
0018   struct no_checking_tag {};
0019   static constexpr no_checking_tag do_not_check{};
0020
0021   V8_INLINE explicit StackAllocated(no_checking_tag) {}
0022   V8_INLINE explicit StackAllocated(const StackAllocated& other,
0023                                     no_checking_tag) {}
0024
0025   V8_INLINE void VerifyOnStack() const {}
0026 };
0027
0028 template <>
0029 class V8_TRIVIAL_ABI StackAllocated<true> : public StackAllocated<false> {
0030  public:
0031   V8_INLINE StackAllocated() { VerifyOnStack(); }
0032
0033 #if V8_HAS_ATTRIBUTE_TRIVIAL_ABI
0034   // In this case, StackAllocated becomes not trivially copyable.
0035   V8_INLINE StackAllocated(const StackAllocated& other) { VerifyOnStack(); }
0036   StackAllocated& operator=(const StackAllocated&) = default;
0037 #endif
0038
0039  protected:
0040   V8_INLINE explicit StackAllocated(no_checking_tag tag)
0041       : StackAllocated<false>(tag) {}
0042   V8_INLINE explicit StackAllocated(const StackAllocated& other,
0043                                     no_checking_tag tag)
0044       : StackAllocated<false>(other, tag) {}
0045
0046   V8_EXPORT void VerifyOnStack() const;
0047 };
0048
0049 /**
0050  * A base class for abstract handles containing indirect pointers.
0051  * These are useful regardless of whether direct local support is enabled.
0052  */
0053 class IndirectHandleBase {
0054  public:
0055   // Returns true if the handle is empty.
0056   V8_INLINE bool IsEmpty() const { return location_ == nullptr; }
0057
0058   // Sets the handle to be empty. IsEmpty() will then return true.
0059   V8_INLINE void Clear() { location_ = nullptr; }
0060
0061  protected:
0062   friend class internal::ValueHelper;
0063   friend class internal::HandleHelper;
0064
0065   V8_INLINE IndirectHandleBase() = default;
0066   V8_INLINE IndirectHandleBase(const IndirectHandleBase& other) = default;
0067   V8_INLINE IndirectHandleBase& operator=(const IndirectHandleBase& that) =
0068       default;
0069
0070   V8_INLINE explicit IndirectHandleBase(internal::Address* location)
0071       : location_(location) {}
0072
0073   // Returns the address of the actual heap object (tagged).
0074   // This method must be called only if the handle is not empty, otherwise it
0075   // will crash.
0076   V8_INLINE internal::Address ptr() const { return *location_; }
0077
0078   // Returns a reference to the slot (indirect pointer).
0079   V8_INLINE internal::Address* const& slot() const { return location_; }
0080   V8_INLINE internal::Address*& slot() { return location_; }
0081
0082   // Returns the handler's "value" (direct or indirect pointer, depending on
0083   // whether direct local support is enabled).
0084   template <typename T, bool check_null = false>
0085   V8_INLINE T* value() const {
0086     return internal::ValueHelper::SlotAsValue<T, check_null>(slot());
0087   }
0088
0089  private:
0090   internal::Address* location_ = nullptr;
0091 };
0092
0093 #ifdef V8_ENABLE_DIRECT_LOCAL
0094
0095 /**
0096  * A base class for abstract handles containing direct pointers.
0097  * These are only possible when conservative stack scanning is enabled.
0098  */
0099 class DirectHandleBase {
0100  public:
0101   // Returns true if the handle is empty.
0102   V8_INLINE bool IsEmpty() const {
0103     return ptr_ == internal::ValueHelper::kEmpty;
0104   }
0105
0106   // Sets the handle to be empty. IsEmpty() will then return true.
0107   V8_INLINE void Clear() { ptr_ = internal::ValueHelper::kEmpty; }
0108
0109  protected:
0110   friend class internal::ValueHelper;
0111   friend class internal::HandleHelper;
0112
0113   V8_INLINE DirectHandleBase() = default;
0114   V8_INLINE DirectHandleBase(const DirectHandleBase& other) = default;
0115   V8_INLINE DirectHandleBase& operator=(const DirectHandleBase& that) = default;
0116
0117   V8_INLINE explicit DirectHandleBase(internal::Address ptr) : ptr_(ptr) {}
0118
0119   // Returns the address of the referenced object.
0120   V8_INLINE internal::Address ptr() const { return ptr_; }
0121
0122   // Returns the handler's "value" (direct pointer, as direct local support
0123   // is guaranteed to be enabled here).
0124   template <typename T, bool check_null = false>
0125   V8_INLINE T* value() const {
0126     return reinterpret_cast<T*>(ptr_);
0127   }
0128
0129  private:
0130   internal::Address ptr_ = internal::ValueHelper::kEmpty;
0131 };
0132
0133 #endif  // V8_ENABLE_DIRECT_LOCAL
0134
0135 }  // namespace v8::api_internal
0136
0137 #endif  // INCLUDE_V8_HANDLE_BASE_H_