node/cppgc/garbage-collected.h

0001 // Copyright 2020 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_CPPGC_GARBAGE_COLLECTED_H_
0006 #define INCLUDE_CPPGC_GARBAGE_COLLECTED_H_
0007
0008 #include "cppgc/internal/api-constants.h"
0009 #include "cppgc/platform.h"
0010 #include "cppgc/trace-trait.h"
0011 #include "cppgc/type-traits.h"
0012
0013 namespace cppgc {
0014
0015 class Visitor;
0016
0017 /**
0018  * Base class for managed objects. Only descendent types of `GarbageCollected`
0019  * can be constructed using `MakeGarbageCollected()`. Must be inherited from as
0020  * left-most base class.
0021  *
0022  * Types inheriting from GarbageCollected must provide a method of
0023  * signature `void Trace(cppgc::Visitor*) const` that dispatchs all managed
0024  * pointers to the visitor and delegates to garbage-collected base classes.
0025  * The method must be virtual if the type is not directly a child of
0026  * GarbageCollected and marked as final.
0027  *
0028  * \code
0029  * // Example using final class.
0030  * class FinalType final : public GarbageCollected<FinalType> {
0031  *  public:
0032  *   void Trace(cppgc::Visitor* visitor) const {
0033  *     // Dispatch using visitor->Trace(...);
0034  *   }
0035  * };
0036  *
0037  * // Example using non-final base class.
0038  * class NonFinalBase : public GarbageCollected<NonFinalBase> {
0039  *  public:
0040  *   virtual void Trace(cppgc::Visitor*) const {}
0041  * };
0042  *
0043  * class FinalChild final : public NonFinalBase {
0044  *  public:
0045  *   void Trace(cppgc::Visitor* visitor) const final {
0046  *     // Dispatch using visitor->Trace(...);
0047  *     NonFinalBase::Trace(visitor);
0048  *   }
0049  * };
0050  * \endcode
0051  */
0052 template <typename T>
0053 class GarbageCollected {
0054  public:
0055   using IsGarbageCollectedTypeMarker = void;
0056   using ParentMostGarbageCollectedType = T;
0057
0058   // Must use MakeGarbageCollected.
0059   void* operator new(size_t) = delete;
0060   void* operator new[](size_t) = delete;
0061   // The garbage collector is taking care of reclaiming the object. Also,
0062   // virtual destructor requires an unambiguous, accessible 'operator delete'.
0063   void operator delete(void*) {
0064 #ifdef V8_ENABLE_CHECKS
0065     internal::Fatal(
0066         "Manually deleting a garbage collected object is not allowed");
0067 #endif  // V8_ENABLE_CHECKS
0068   }
0069   void operator delete[](void*) = delete;
0070
0071  protected:
0072   GarbageCollected() = default;
0073 };
0074
0075 /**
0076  * Base class for managed mixin objects. Such objects cannot be constructed
0077  * directly but must be mixed into the inheritance hierarchy of a
0078  * GarbageCollected object.
0079  *
0080  * Types inheriting from GarbageCollectedMixin must override a virtual method
0081  * of signature `void Trace(cppgc::Visitor*) const` that dispatchs all managed
0082  * pointers to the visitor and delegates to base classes.
0083  *
0084  * \code
0085  * class Mixin : public GarbageCollectedMixin {
0086  *  public:
0087  *   void Trace(cppgc::Visitor* visitor) const override {
0088  *     // Dispatch using visitor->Trace(...);
0089  *   }
0090  * };
0091  * \endcode
0092  */
0093 class GarbageCollectedMixin {
0094  public:
0095   using IsGarbageCollectedMixinTypeMarker = void;
0096
0097   /**
0098    * This Trace method must be overriden by objects inheriting from
0099    * GarbageCollectedMixin.
0100    */
0101   virtual void Trace(cppgc::Visitor*) const {}
0102 };
0103
0104 }  // namespace cppgc
0105
0106 #endif  // INCLUDE_CPPGC_GARBAGE_COLLECTED_H_