garbage-collected.h 3.11 KB
Newer Older
1 2 3 4 5 6 7
// Copyright 2020 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_CPPGC_GARBAGE_COLLECTED_H_
#define INCLUDE_CPPGC_GARBAGE_COLLECTED_H_

8 9 10 11
#include "cppgc/internal/api-constants.h"
#include "cppgc/platform.h"
#include "cppgc/trace-trait.h"
#include "cppgc/type-traits.h"
12 13

namespace cppgc {
14

15
class Visitor;
16

17
/**
18 19
 * Base class for managed objects. Only descendent types of `GarbageCollected`
 * can be constructed using `MakeGarbageCollected()`. Must be inherited from as
20 21 22
 * left-most base class.
 *
 * Types inheriting from GarbageCollected must provide a method of
23 24 25 26
 * signature `void Trace(cppgc::Visitor*) const` that dispatchs all managed
 * pointers to the visitor and delegates to garbage-collected base classes.
 * The method must be virtual if the type is not directly a child of
 * GarbageCollected and marked as final.
27 28 29 30 31
 *
 * \code
 * // Example using final class.
 * class FinalType final : public GarbageCollected<FinalType> {
 *  public:
32
 *   void Trace(cppgc::Visitor* visitor) const {
33 34 35 36 37 38 39
 *     // Dispatch using visitor->Trace(...);
 *   }
 * };
 *
 * // Example using non-final base class.
 * class NonFinalBase : public GarbageCollected<NonFinalBase> {
 *  public:
40
 *   virtual void Trace(cppgc::Visitor*) const {}
41 42 43 44
 * };
 *
 * class FinalChild final : public NonFinalBase {
 *  public:
45
 *   void Trace(cppgc::Visitor* visitor) const final {
46 47 48 49 50 51
 *     // Dispatch using visitor->Trace(...);
 *     NonFinalBase::Trace(visitor);
 *   }
 * };
 * \endcode
 */
52
template <typename T>
53
class GarbageCollected {
54 55
 public:
  using IsGarbageCollectedTypeMarker = void;
56
  using ParentMostGarbageCollectedType = T;
57

58 59 60 61 62 63 64
  // Must use MakeGarbageCollected.
  void* operator new(size_t) = delete;
  void* operator new[](size_t) = delete;
  // The garbage collector is taking care of reclaiming the object. Also,
  // virtual destructor requires an unambiguous, accessible 'operator delete'.
  void operator delete(void*) {
#ifdef V8_ENABLE_CHECKS
65 66
    internal::Fatal(
        "Manually deleting a garbage collected object is not allowed");
67 68 69 70
#endif  // V8_ENABLE_CHECKS
  }
  void operator delete[](void*) = delete;

71 72 73 74
 protected:
  GarbageCollected() = default;
};

75 76 77 78 79
/**
 * Base class for managed mixin objects. Such objects cannot be constructed
 * directly but must be mixed into the inheritance hierarchy of a
 * GarbageCollected object.
 *
80 81 82
 * Types inheriting from GarbageCollectedMixin must override a virtual method
 * of signature `void Trace(cppgc::Visitor*) const` that dispatchs all managed
 * pointers to the visitor and delegates to base classes.
83 84 85 86
 *
 * \code
 * class Mixin : public GarbageCollectedMixin {
 *  public:
87
 *   void Trace(cppgc::Visitor* visitor) const override {
88 89 90 91 92
 *     // Dispatch using visitor->Trace(...);
 *   }
 * };
 * \endcode
 */
93
class GarbageCollectedMixin {
94 95 96
 public:
  using IsGarbageCollectedMixinTypeMarker = void;

97 98 99 100
  /**
   * This Trace method must be overriden by objects inheriting from
   * GarbageCollectedMixin.
   */
101
  virtual void Trace(cppgc::Visitor*) const {}
102 103
};

104 105 106
}  // namespace cppgc

#endif  // INCLUDE_CPPGC_GARBAGE_COLLECTED_H_