File Explorer

1// Copyright 2020 the V8 project authors. All rights reserved.2// Use of this source code is governed by a BSD-style license that can be3// found in the LICENSE file.4 5#ifndef INCLUDE_CPPGC_VISITOR_H_6#define INCLUDE_CPPGC_VISITOR_H_7 8#include <type_traits>9 10#include "cppgc/custom-space.h"11#include "cppgc/garbage-collected.h"12#include "cppgc/internal/logging.h"13#include "cppgc/internal/member-storage.h"14#include "cppgc/internal/pointer-policies.h"15#include "cppgc/liveness-broker.h"16#include "cppgc/macros.h"17#include "cppgc/member.h"18#include "cppgc/sentinel-pointer.h"19#include "cppgc/source-location.h"20#include "cppgc/trace-trait.h"21#include "cppgc/type-traits.h"22 23namespace cppgc {24 25namespace internal {26template <typename T, typename WeaknessPolicy, typename LocationPolicy,27          typename CheckingPolicy>28class BasicCrossThreadPersistent;29template <typename T, typename WeaknessPolicy, typename LocationPolicy,30          typename CheckingPolicy>31class BasicPersistent;32class ConservativeTracingVisitor;33class VisitorBase;34class VisitorFactory;35}  // namespace internal36 37using WeakCallback = void (*)(const LivenessBroker&, const void*);38 39/**40 * An ephemeron pair is used to conditionally retain an object.41 * The `value` will be kept alive only if the `key` is alive.42 */43template <typename K, typename V>44struct EphemeronPair {45  CPPGC_DISALLOW_NEW();46 47  EphemeronPair(K* k, V* v) : key(k), value(v) {}48  WeakMember<K> key;49  Member<V> value;50 51  void ClearValueIfKeyIsDead(const LivenessBroker& broker) {52    if (!broker.IsHeapObjectAlive(key)) value = nullptr;53  }54 55  void Trace(Visitor* visitor) const;56};57 58/**59 * Visitor passed to trace methods. All managed pointers must have called the60 * Visitor's trace method on them.61 *62 * \code63 * class Foo final : public GarbageCollected<Foo> {64 *  public:65 *   void Trace(Visitor* visitor) const {66 *     visitor->Trace(foo_);67 *     visitor->Trace(weak_foo_);68 *   }69 *  private:70 *   Member<Foo> foo_;71 *   WeakMember<Foo> weak_foo_;72 * };73 * \endcode74 */75class V8_EXPORT Visitor {76 public:77  class Key {78   private:79    Key() = default;80    friend class internal::VisitorFactory;81  };82 83  explicit Visitor(Key) {}84 85  virtual ~Visitor() = default;86 87  /**88   * Trace method for Member.89   *90   * \param member Member reference retaining an object.91   */92  template <typename T>93  void Trace(const Member<T>& member) {94    const T* value = member.GetRawAtomic();95    CPPGC_DCHECK(value != kSentinelPointer);96    TraceImpl(value);97  }98 99  /**100   * Trace method for WeakMember.101   *102   * \param weak_member WeakMember reference weakly retaining an object.103   */104  template <typename T>105  void Trace(const WeakMember<T>& weak_member) {106    static_assert(sizeof(T), "Pointee type must be fully defined.");107    static_assert(internal::IsGarbageCollectedOrMixinType<T>::value,108                  "T must be GarbageCollected or GarbageCollectedMixin type");109    static_assert(!internal::IsAllocatedOnCompactableSpace<T>::value,110                  "Weak references to compactable objects are not allowed");111 112    const T* value = weak_member.GetRawAtomic();113 114    // Bailout assumes that WeakMember emits write barrier.115    if (!value) {116      return;117    }118 119    CPPGC_DCHECK(value != kSentinelPointer);120    VisitWeak(value, TraceTrait<T>::GetTraceDescriptor(value),121              &HandleWeak<WeakMember<T>>, &weak_member);122  }123 124#if defined(CPPGC_POINTER_COMPRESSION)125  /**126   * Trace method for UncompressedMember.127   *128   * \param member UncompressedMember reference retaining an object.129   */130  template <typename T>131  void Trace(const subtle::UncompressedMember<T>& member) {132    const T* value = member.GetRawAtomic();133    CPPGC_DCHECK(value != kSentinelPointer);134    TraceImpl(value);135  }136#endif  // defined(CPPGC_POINTER_COMPRESSION)137 138  template <typename T>139  void TraceMultiple(const subtle::UncompressedMember<T>* start, size_t len) {140    static_assert(sizeof(T), "Pointee type must be fully defined.");141    static_assert(internal::IsGarbageCollectedOrMixinType<T>::value,142                  "T must be GarbageCollected or GarbageCollectedMixin type");143    VisitMultipleUncompressedMember(start, len,144                                    &TraceTrait<T>::GetTraceDescriptor);145  }146 147  template <typename T,148            std::enable_if_t<!std::is_same_v<149                Member<T>, subtle::UncompressedMember<T>>>* = nullptr>150  void TraceMultiple(const Member<T>* start, size_t len) {151    static_assert(sizeof(T), "Pointee type must be fully defined.");152    static_assert(internal::IsGarbageCollectedOrMixinType<T>::value,153                  "T must be GarbageCollected or GarbageCollectedMixin type");154#if defined(CPPGC_POINTER_COMPRESSION)155    static_assert(std::is_same_v<Member<T>, subtle::CompressedMember<T>>,156                  "Member and CompressedMember must be the same.");157    VisitMultipleCompressedMember(start, len,158                                  &TraceTrait<T>::GetTraceDescriptor);159#endif  // defined(CPPGC_POINTER_COMPRESSION)160  }161 162  /**163   * Trace method for inlined objects that are not allocated themselves but164   * otherwise follow managed heap layout and have a Trace() method.165   *166   * \param object reference of the inlined object.167   */168  template <typename T>169  void Trace(const T& object) {170#if V8_ENABLE_CHECKS171    // This object is embedded in potentially multiple nested objects. The172    // outermost object must not be in construction as such objects are (a) not173    // processed immediately, and (b) only processed conservatively if not174    // otherwise possible.175    CheckObjectNotInConstruction(&object);176#endif  // V8_ENABLE_CHECKS177    TraceTrait<T>::Trace(this, &object);178  }179 180  template <typename T>181  void TraceMultiple(const T* start, size_t len) {182#if V8_ENABLE_CHECKS183    // This object is embedded in potentially multiple nested objects. The184    // outermost object must not be in construction as such objects are (a) not185    // processed immediately, and (b) only processed conservatively if not186    // otherwise possible.187    CheckObjectNotInConstruction(start);188#endif  // V8_ENABLE_CHECKS189    for (size_t i = 0; i < len; ++i) {190      const T* object = &start[i];191      if constexpr (std::is_polymorphic_v<T>) {192        // The object's vtable may be uninitialized in which case the object is193        // not traced.194        if (*reinterpret_cast<const uintptr_t*>(object) == 0) continue;195      }196      TraceTrait<T>::Trace(this, object);197    }198  }199 200  /**201   * Registers a weak callback method on the object of type T. See202   * LivenessBroker for an usage example.203   *204   * \param object of type T specifying a weak callback method.205   */206  template <typename T, void (T::*method)(const LivenessBroker&)>207  void RegisterWeakCallbackMethod(const T* object) {208    RegisterWeakCallback(&WeakCallbackMethodDelegate<T, method>, object);209  }210 211  /**212   * Trace method for EphemeronPair.213   *214   * \param ephemeron_pair EphemeronPair reference weakly retaining a key object215   * and strongly retaining a value object in case the key object is alive.216   */217  template <typename K, typename V>218  void Trace(const EphemeronPair<K, V>& ephemeron_pair) {219    TraceEphemeron(ephemeron_pair.key, &ephemeron_pair.value);220    RegisterWeakCallbackMethod<EphemeronPair<K, V>,221                               &EphemeronPair<K, V>::ClearValueIfKeyIsDead>(222        &ephemeron_pair);223  }224 225  /**226   * Trace method for a single ephemeron. Used for tracing a raw ephemeron in227   * which the `key` and `value` are kept separately.228   *229   * \param weak_member_key WeakMember reference weakly retaining a key object.230   * \param member_value Member reference with ephemeron semantics.231   */232  template <typename KeyType, typename ValueType>233  void TraceEphemeron(const WeakMember<KeyType>& weak_member_key,234                      const Member<ValueType>* member_value) {235    const KeyType* key = weak_member_key.GetRawAtomic();236    if (!key) return;237 238    // `value` must always be non-null.239    CPPGC_DCHECK(member_value);240    const ValueType* value = member_value->GetRawAtomic();241    if (!value) return;242 243    // KeyType and ValueType may refer to GarbageCollectedMixin.244    TraceDescriptor value_desc =245        TraceTrait<ValueType>::GetTraceDescriptor(value);246    CPPGC_DCHECK(value_desc.base_object_payload);247    const void* key_base_object_payload =248        TraceTrait<KeyType>::GetTraceDescriptor(key).base_object_payload;249    CPPGC_DCHECK(key_base_object_payload);250 251    VisitEphemeron(key_base_object_payload, value, value_desc);252  }253 254  /**255   * Trace method for a single ephemeron. Used for tracing a raw ephemeron in256   * which the `key` and `value` are kept separately. Note that this overload257   * is for non-GarbageCollected `value`s that can be traced though.258   *259   * \param key `WeakMember` reference weakly retaining a key object.260   * \param value Reference weakly retaining a value object. Note that261   *   `ValueType` here should not be `Member`. It is expected that262   *   `TraceTrait<ValueType>::GetTraceDescriptor(value)` returns a263   *   `TraceDescriptor` with a null base pointer but a valid trace method.264   */265  template <typename KeyType, typename ValueType>266  void TraceEphemeron(const WeakMember<KeyType>& weak_member_key,267                      const ValueType* value) {268    static_assert(!IsGarbageCollectedOrMixinTypeV<ValueType>,269                  "garbage-collected types must use WeakMember and Member");270    const KeyType* key = weak_member_key.GetRawAtomic();271    if (!key) return;272 273    // `value` must always be non-null.274    CPPGC_DCHECK(value);275    TraceDescriptor value_desc =276        TraceTrait<ValueType>::GetTraceDescriptor(value);277    // `value_desc.base_object_payload` must be null as this override is only278    // taken for non-garbage-collected values.279    CPPGC_DCHECK(!value_desc.base_object_payload);280 281    // KeyType might be a GarbageCollectedMixin.282    const void* key_base_object_payload =283        TraceTrait<KeyType>::GetTraceDescriptor(key).base_object_payload;284    CPPGC_DCHECK(key_base_object_payload);285 286    VisitEphemeron(key_base_object_payload, value, value_desc);287  }288 289  /**290   * Trace method that strongifies a WeakMember.291   *292   * \param weak_member WeakMember reference retaining an object.293   */294  template <typename T>295  void TraceStrongly(const WeakMember<T>& weak_member) {296    const T* value = weak_member.GetRawAtomic();297    CPPGC_DCHECK(value != kSentinelPointer);298    TraceImpl(value);299  }300 301  /**302   * Trace method for retaining containers strongly.303   *304   * \param object reference to the container.305   */306  template <typename T>307  void TraceStrongContainer(const T* object) {308    TraceImpl(object);309  }310 311  /**312   * Trace method for retaining containers weakly. Note that weak containers313   * should emit write barriers.314   *315   * \param object reference to the container.316   * \param callback to be invoked.317   * \param callback_data custom data that is passed to the callback.318   */319  template <typename T>320  void TraceWeakContainer(const T* object, WeakCallback callback,321                          const void* callback_data) {322    if (!object) return;323    VisitWeakContainer(object, TraceTrait<T>::GetTraceDescriptor(object),324                       TraceTrait<T>::GetWeakTraceDescriptor(object), callback,325                       callback_data);326  }327 328  /**329   * Registers a slot containing a reference to an object allocated on a330   * compactable space. Such references maybe be arbitrarily moved by the GC.331   *332   * \param slot location of reference to object that might be moved by the GC.333   * The slot must contain an uncompressed pointer.334   */335  template <typename T>336  void RegisterMovableReference(const T** slot) {337    static_assert(internal::IsAllocatedOnCompactableSpace<T>::value,338                  "Only references to objects allocated on compactable spaces "339                  "should be registered as movable slots.");340    static_assert(!IsGarbageCollectedMixinTypeV<T>,341                  "Mixin types do not support compaction.");342    HandleMovableReference(reinterpret_cast<const void**>(slot));343  }344 345  /**346   * Registers a weak callback that is invoked during garbage collection.347   *348   * \param callback to be invoked.349   * \param data custom data that is passed to the callback.350   */351  virtual void RegisterWeakCallback(WeakCallback callback, const void* data) {}352 353  /**354   * Defers tracing an object from a concurrent thread to the mutator thread.355   * Should be called by Trace methods of types that are not safe to trace356   * concurrently.357   *358   * \param parameter tells the trace callback which object was deferred.359   * \param callback to be invoked for tracing on the mutator thread.360   * \param deferred_size size of deferred object.361   *362   * \returns false if the object does not need to be deferred (i.e. currently363   * traced on the mutator thread) and true otherwise (i.e. currently traced on364   * a concurrent thread).365   */366  virtual V8_WARN_UNUSED_RESULT bool DeferTraceToMutatorThreadIfConcurrent(367      const void* parameter, TraceCallback callback, size_t deferred_size) {368    // By default tracing is not deferred.369    return false;370  }371 372 protected:373  virtual void Visit(const void* self, TraceDescriptor) {}374  virtual void VisitWeak(const void* self, TraceDescriptor, WeakCallback,375                         const void* weak_member) {}376  virtual void VisitEphemeron(const void* key, const void* value,377                              TraceDescriptor value_desc) {}378  virtual void VisitWeakContainer(const void* self, TraceDescriptor strong_desc,379                                  TraceDescriptor weak_desc,380                                  WeakCallback callback, const void* data) {}381  virtual void HandleMovableReference(const void**) {}382 383  virtual void VisitMultipleUncompressedMember(384      const void* start, size_t len,385      TraceDescriptorCallback get_trace_descriptor) {386    // Default implementation merely delegates to Visit().387    const char* it = static_cast<const char*>(start);388    const char* end = it + len * internal::kSizeOfUncompressedMember;389    for (; it < end; it += internal::kSizeOfUncompressedMember) {390      const auto* current = reinterpret_cast<const internal::RawPointer*>(it);391      const void* object = current->LoadAtomic();392      if (!object) continue;393 394      Visit(object, get_trace_descriptor(object));395    }396  }397 398#if defined(CPPGC_POINTER_COMPRESSION)399  virtual void VisitMultipleCompressedMember(400      const void* start, size_t len,401      TraceDescriptorCallback get_trace_descriptor) {402    // Default implementation merely delegates to Visit().403    const char* it = static_cast<const char*>(start);404    const char* end = it + len * internal::kSizeofCompressedMember;405    for (; it < end; it += internal::kSizeofCompressedMember) {406      const auto* current =407          reinterpret_cast<const internal::CompressedPointer*>(it);408      const void* object = current->LoadAtomic();409      if (!object) continue;410 411      Visit(object, get_trace_descriptor(object));412    }413  }414#endif  // defined(CPPGC_POINTER_COMPRESSION)415 416 private:417  template <typename T, void (T::*method)(const LivenessBroker&)>418  static void WeakCallbackMethodDelegate(const LivenessBroker& info,419                                         const void* self) {420    // Callback is registered through a potential const Trace method but needs421    // to be able to modify fields. See HandleWeak.422    (const_cast<T*>(static_cast<const T*>(self))->*method)(info);423  }424 425  template <typename PointerType>426  static void HandleWeak(const LivenessBroker& info, const void* object) {427    const PointerType* weak = static_cast<const PointerType*>(object);428    if (!info.IsHeapObjectAlive(weak->GetFromGC())) {429      weak->ClearFromGC();430    }431  }432 433  template <typename T>434  void TraceImpl(const T* t) {435    static_assert(sizeof(T), "Pointee type must be fully defined.");436    static_assert(internal::IsGarbageCollectedOrMixinType<T>::value,437                  "T must be GarbageCollected or GarbageCollectedMixin type");438    if (!t) {439      return;440    }441    Visit(t, TraceTrait<T>::GetTraceDescriptor(t));442  }443 444#if V8_ENABLE_CHECKS445  void CheckObjectNotInConstruction(const void* address);446#endif  // V8_ENABLE_CHECKS447 448  template <typename T, typename WeaknessPolicy, typename LocationPolicy,449            typename CheckingPolicy>450  friend class internal::BasicCrossThreadPersistent;451  template <typename T, typename WeaknessPolicy, typename LocationPolicy,452            typename CheckingPolicy>453  friend class internal::BasicPersistent;454  friend class internal::ConservativeTracingVisitor;455  friend class internal::VisitorBase;456};457 458template <typename K, typename V>459void EphemeronPair<K, V>::Trace(Visitor* visitor) const {460  visitor->TraceEphemeron(key, value);461}462 463namespace internal {464 465class V8_EXPORT RootVisitor {466 public:467  explicit RootVisitor(Visitor::Key) {}468 469  virtual ~RootVisitor() = default;470 471  template <typename AnyStrongPersistentType,472            std::enable_if_t<473                AnyStrongPersistentType::IsStrongPersistent::value>* = nullptr>474  void Trace(const AnyStrongPersistentType& p) {475    using PointeeType = typename AnyStrongPersistentType::PointeeType;476    const void* object = Extract(p);477    if (!object) {478      return;479    }480    VisitRoot(object, TraceTrait<PointeeType>::GetTraceDescriptor(object),481              p.Location());482  }483 484  template <typename AnyWeakPersistentType,485            std::enable_if_t<486                !AnyWeakPersistentType::IsStrongPersistent::value>* = nullptr>487  void Trace(const AnyWeakPersistentType& p) {488    using PointeeType = typename AnyWeakPersistentType::PointeeType;489    static_assert(!internal::IsAllocatedOnCompactableSpace<PointeeType>::value,490                  "Weak references to compactable objects are not allowed");491    const void* object = Extract(p);492    if (!object) {493      return;494    }495    VisitWeakRoot(object, TraceTrait<PointeeType>::GetTraceDescriptor(object),496                  &HandleWeak<AnyWeakPersistentType>, &p, p.Location());497  }498 499 protected:500  virtual void VisitRoot(const void*, TraceDescriptor, const SourceLocation&) {}501  virtual void VisitWeakRoot(const void* self, TraceDescriptor, WeakCallback,502                             const void* weak_root, const SourceLocation&) {}503 504 private:505  template <typename AnyPersistentType>506  static const void* Extract(AnyPersistentType& p) {507    using PointeeType = typename AnyPersistentType::PointeeType;508    static_assert(sizeof(PointeeType),509                  "Persistent's pointee type must be fully defined");510    static_assert(internal::IsGarbageCollectedOrMixinType<PointeeType>::value,511                  "Persistent's pointee type must be GarbageCollected or "512                  "GarbageCollectedMixin");513    return p.GetFromGC();514  }515 516  template <typename PointerType>517  static void HandleWeak(const LivenessBroker& info, const void* object) {518    const PointerType* weak = static_cast<const PointerType*>(object);519    if (!info.IsHeapObjectAlive(weak->GetFromGC())) {520      weak->ClearFromGC();521    }522  }523};524 525}  // namespace internal526}  // namespace cppgc527 528#endif  // INCLUDE_CPPGC_VISITOR_H_529