src/handles/maybe-handles.h

// Copyright 2011 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 V8_HANDLES_MAYBE_HANDLES_H_
#define V8_HANDLES_MAYBE_HANDLES_H_

#include <type_traits>

#include "src/handles/handles.h"

namespace v8 {
namespace internal {

struct NullMaybeHandleType {};

constexpr NullMaybeHandleType kNullMaybeHandle;

// ----------------------------------------------------------------------------
// A Handle can be converted into a MaybeHandle. Converting a MaybeHandle
// into a Handle requires checking that it does not point to nullptr. This
// ensures nullptr checks before use.
//
// Also note that MaybeHandles do not provide default equality comparison or
// hashing operators on purpose. Such operators would be misleading, because
// intended semantics is ambiguous between handle location and object identity.
template <typename T>
class MaybeHandle final {
 public:
  V8_INLINE MaybeHandle() = default;

  V8_INLINE MaybeHandle(NullMaybeHandleType) {}

  // Constructor for handling automatic up casting from Handle.
  // Ex. Handle<JSArray> can be passed when MaybeHandle<Object> is expected.
  template <typename S>
  V8_INLINE MaybeHandle(Handle<S> handle)
    requires(is_subtype_v<S, T>)
      : location_(handle.location_) {}

  // Constructor for handling automatic up casting.
  // Ex. MaybeHandle<JSArray> can be passed when MaybeHandle<Object> is
  // expected.
  template <typename S>
  V8_INLINE MaybeHandle(MaybeHandle<S> maybe_handle)
    requires(is_subtype_v<S, T>)
      : location_(maybe_handle.location_) {}

  V8_INLINE MaybeHandle(Tagged<T> object, Isolate* isolate);
  V8_INLINE MaybeHandle(Tagged<T> object, LocalHeap* local_heap);

  V8_INLINE void Assert() const { DCHECK_NOT_NULL(location_); }
  V8_INLINE void Check() const { CHECK_NOT_NULL(location_); }

  V8_INLINE Handle<T> ToHandleChecked() const {
    Check();
    return Handle<T>(location_);
  }

  // Convert to a Handle with a type that can be upcasted to.
  template <typename S>
  V8_WARN_UNUSED_RESULT V8_INLINE bool ToHandle(Handle<S>* out) const {
    if (location_ == nullptr) {
      *out = Handle<T>::null();
      return false;
    } else {
      *out = Handle<T>(location_);
      return true;
    }
  }

  template <typename S>
  V8_WARN_UNUSED_RESULT V8_INLINE bool ToHandle(DirectHandle<S>* out) const;

  // Location equality.
  bool equals(MaybeHandle<T> other) const {
    return address() == other.address();
  }

  // Returns the raw address where this handle is stored. This should only be
  // used for hashing handles; do not ever try to dereference it.
  V8_INLINE Address address() const {
    return reinterpret_cast<Address>(location_);
  }

  bool is_null() const { return location_ == nullptr; }

 protected:
  V8_INLINE explicit MaybeHandle(Address* location) : location_(location) {}

  Address* location_ = nullptr;

  // MaybeHandles of different classes are allowed to access each
  // other's location_.
  template <typename>
  friend class MaybeHandle;
#ifdef V8_ENABLE_DIRECT_HANDLE
  template <typename>
  friend class MaybeDirectHandle;
#endif
  // Casts are allowed to access location_.
  template <typename To, typename From>
  friend inline MaybeIndirectHandle<To> UncheckedCast(MaybeHandle<From> value);
};

template <typename T>
std::ostream& operator<<(std::ostream& os, MaybeIndirectHandle<T> handle);

// A handle which contains a potentially weak pointer. Keeps it alive (strongly)
// while the MaybeObjectHandle is alive.
class MaybeObjectHandle {
 public:
  inline MaybeObjectHandle()
      : reference_type_(HeapObjectReferenceType::STRONG) {}
  inline MaybeObjectHandle(Tagged<MaybeObject> object, Isolate* isolate);
  inline MaybeObjectHandle(Tagged<Object> object, Isolate* isolate);
  inline MaybeObjectHandle(Tagged<Smi> object, Isolate* isolate);
  inline MaybeObjectHandle(Tagged<MaybeObject> object, LocalHeap* local_heap);
  inline MaybeObjectHandle(Tagged<Object> object, LocalHeap* local_heap);
  inline MaybeObjectHandle(Tagged<Smi> object, LocalHeap* local_heap);
  inline explicit MaybeObjectHandle(Handle<Object> object);

  static inline MaybeObjectHandle Weak(Tagged<Object> object, Isolate* isolate);
  static inline MaybeObjectHandle Weak(Handle<Object> object);

  inline Tagged<MaybeObject> operator*() const;
  inline Tagged<MaybeObject> operator->() const;
  inline IndirectHandle<Object> object() const;

  inline bool is_identical_to(const MaybeObjectHandle& other) const;
  bool is_null() const { return handle_.is_null(); }

 private:
  inline MaybeObjectHandle(Tagged<Object> object,
                           HeapObjectReferenceType reference_type,
                           Isolate* isolate);
  inline MaybeObjectHandle(Handle<Object> object,
                           HeapObjectReferenceType reference_type);

  friend class MaybeObjectDirectHandle;

  HeapObjectReferenceType reference_type_;
  MaybeHandle<Object> handle_;
};

#ifdef V8_ENABLE_DIRECT_HANDLE

template <typename T>
class MaybeDirectHandle final {
 public:
  V8_INLINE MaybeDirectHandle() = default;

  V8_INLINE MaybeDirectHandle(NullMaybeHandleType) {}

  // Constructor for handling automatic up casting from DirectHandle.
  // Ex. DirectHandle<JSArray> can be passed when MaybeDirectHandle<Object> is
  // expected.
  template <typename S, typename = std::enable_if_t<is_subtype_v<S, T>>>
  V8_INLINE MaybeDirectHandle(DirectHandle<S> handle)
      : location_(handle.address()) {}

  // Constructor for handling automatic up casting from Handle.
  // Ex. Handle<JSArray> can be passed when MaybeDirectHandle<Object> is
  // expected.
  template <typename S, typename = std::enable_if_t<is_subtype_v<S, T>>>
  V8_INLINE MaybeDirectHandle(Handle<S> handle)
      : MaybeDirectHandle(DirectHandle<S>(handle)) {}

  // Constructor for handling automatic up casting.
  // Ex. MaybeDirectHandle<JSArray> can be passed when MaybeDirectHandle<Object>
  // is expected.
  template <typename S, typename = std::enable_if_t<is_subtype_v<S, T>>>
  V8_INLINE MaybeDirectHandle(MaybeDirectHandle<S> maybe_handle)
      : location_(maybe_handle.location_) {}

  // Constructor for handling automatic up casting from MaybeHandle.
  // Ex. MaybeHandle<JSArray> can be passed when
  // MaybeDirectHandle<Object> is expected.
  template <typename S, typename = std::enable_if_t<is_subtype_v<S, T>>>
  V8_INLINE MaybeDirectHandle(MaybeIndirectHandle<S> maybe_handle)
      : location_(maybe_handle.location_ == nullptr ? kTaggedNullAddress
                                                    : *maybe_handle.location_) {
  }

  V8_INLINE MaybeDirectHandle(Tagged<T> object, Isolate* isolate);
  V8_INLINE MaybeDirectHandle(Tagged<T> object, LocalHeap* local_heap);

  V8_INLINE void Assert() const { DCHECK_NE(location_, kTaggedNullAddress); }
  V8_INLINE void Check() const { CHECK_NE(location_, kTaggedNullAddress); }

  V8_INLINE DirectHandle<T> ToHandleChecked() const {
    Check();
    return DirectHandle<T>(location_);
  }

  // Convert to a DirectHandle with a type that can be upcasted to.
  template <typename S>
  V8_WARN_UNUSED_RESULT V8_INLINE bool ToHandle(DirectHandle<S>* out) const {
    if (location_ == kTaggedNullAddress) {
      *out = DirectHandle<T>::null();
      return false;
    } else {
      *out = DirectHandle<T>(location_);
      return true;
    }
  }

  // Address equality.
  bool equals(MaybeHandle<T> other) const {
    return address() == other.address();
  }

  // Returns the raw address where this direct handle is stored.
  V8_INLINE Address address() const { return location_; }

  bool is_null() const { return location_ == kTaggedNullAddress; }

 protected:
  V8_INLINE explicit MaybeDirectHandle(Address location)
      : location_(location) {}

  Address location_ = kTaggedNullAddress;

  // MaybeDirectHandles of different classes are allowed to access each
  // other's location_.
  template <typename>
  friend class MaybeDirectHandle;
  template <typename>
  friend class MaybeHandle;
  // Casts are allowed to access location_.
  template <typename To, typename From>
  friend inline MaybeDirectHandle<To> UncheckedCast(
      MaybeDirectHandle<From> value);
};

#else

template <typename T>
class MaybeDirectHandle {
 public:
  V8_INLINE MaybeDirectHandle() = default;
  V8_INLINE MaybeDirectHandle(NullMaybeHandleType) {}

  V8_INLINE MaybeDirectHandle(Tagged<T> object, Isolate* isolate)
      : handle_(object, isolate) {}
  V8_INLINE MaybeDirectHandle(Tagged<T> object, LocalIsolate* isolate)
      : handle_(object, isolate) {}
  V8_INLINE MaybeDirectHandle(Tagged<T> object, LocalHeap* local_heap)
      : handle_(object, local_heap) {}

  template <typename S>
  V8_INLINE MaybeDirectHandle(DirectHandle<S> handle)
    requires(is_subtype_v<S, T>)
      : handle_(handle.handle_) {}
  template <typename S>
  V8_INLINE MaybeDirectHandle(IndirectHandle<S> handle)
    requires(is_subtype_v<S, T>)
      : handle_(handle) {}
  template <typename S>
  V8_INLINE MaybeDirectHandle(MaybeDirectHandle<S> handle)
    requires(is_subtype_v<S, T>)
      : handle_(handle.handle_) {}
  template <typename S>
  V8_INLINE MaybeDirectHandle(MaybeIndirectHandle<S> handle)
    requires(is_subtype_v<S, T>)
      : handle_(handle) {}

  V8_INLINE void Assert() const { handle_.Assert(); }
  V8_INLINE void Check() const { handle_.Check(); }

  V8_INLINE DirectHandle<T> ToHandleChecked() const {
    return handle_.ToHandleChecked();
  }
  template <typename S>
  V8_WARN_UNUSED_RESULT V8_INLINE bool ToHandle(DirectHandle<S>* out) const {
    return handle_.ToHandle(out);
  }

  V8_INLINE bool is_null() const { return handle_.is_null(); }

 private:
  // DirectHandle is allowed to access handle_.
  template <typename>
  friend class DirectHandle;
  // MaybeDirectHandle of different classes are allowed to access each other's
  // handle_.
  template <typename>
  friend class MaybeDirectHandle;
  // Casts are allowed to access handle_.
  template <typename To, typename From>
  friend inline MaybeDirectHandle<To> UncheckedCast(
      MaybeDirectHandle<From> value);
  template <typename U>
  friend inline MaybeIndirectHandle<U> indirect_handle(MaybeDirectHandle<U>,
                                                       Isolate*);
  template <typename U>
  friend inline MaybeIndirectHandle<U> indirect_handle(MaybeDirectHandle<U>,
                                                       LocalIsolate*);

  MaybeIndirectHandle<T> handle_;
};

#endif  // V8_ENABLE_DIRECT_HANDLE

template <typename T>
std::ostream& operator<<(std::ostream& os, MaybeDirectHandle<T> handle);

class MaybeObjectDirectHandle {
 public:
  inline MaybeObjectDirectHandle()
      : reference_type_(HeapObjectReferenceType::STRONG) {}
  inline MaybeObjectDirectHandle(Tagged<MaybeObject> object, Isolate* isolate);
  inline MaybeObjectDirectHandle(Tagged<Object> object, Isolate* isolate);
  inline MaybeObjectDirectHandle(Tagged<Smi> object, Isolate* isolate);
  inline MaybeObjectDirectHandle(Tagged<MaybeObject> object,
                                 LocalHeap* local_heap);
  inline MaybeObjectDirectHandle(Tagged<Object> object, LocalHeap* local_heap);
  inline MaybeObjectDirectHandle(Tagged<Smi> object, LocalHeap* local_heap);
  inline explicit MaybeObjectDirectHandle(DirectHandle<Object> object);

  inline MaybeObjectDirectHandle(MaybeObjectHandle obj);

  static inline MaybeObjectDirectHandle Weak(Tagged<Object> object,
                                             Isolate* isolate);
  static inline MaybeObjectDirectHandle Weak(DirectHandle<Object> object);

  inline Tagged<MaybeObject> operator*() const;
  inline Tagged<MaybeObject> operator->() const;
  inline DirectHandle<Object> object() const;

  inline bool is_identical_to(const MaybeObjectDirectHandle& other) const;
  inline bool is_identical_to(const MaybeObjectHandle& other) const;
  bool is_null() const { return handle_.is_null(); }

 private:
  inline MaybeObjectDirectHandle(Tagged<Object> object,
                                 HeapObjectReferenceType reference_type,
                                 Isolate* isolate);
  inline MaybeObjectDirectHandle(DirectHandle<Object> object,
                                 HeapObjectReferenceType reference_type);

  HeapObjectReferenceType reference_type_;
  MaybeDirectHandle<Object> handle_;
};

}  // namespace internal
}  // namespace v8

#endif  // V8_HANDLES_MAYBE_HANDLES_H_