src/cppgc_helpers.h

#ifndef SRC_CPPGC_HELPERS_H_
#define SRC_CPPGC_HELPERS_H_

#if defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS

#include <type_traits>  // std::remove_reference
#include "cppgc/garbage-collected.h"
#include "cppgc/name-provider.h"
#include "cppgc/persistent.h"
#include "memory_tracker.h"
#include "util.h"
#include "v8-cppgc.h"
#include "v8-sandbox.h"
#include "v8.h"

namespace node {

class Environment;
class Realm;
class CppgcWrapperListNode;

/**
 * This is a helper mixin with a BaseObject-like interface to help
 * implementing wrapper objects managed by V8's cppgc (Oilpan) library.
 * cppgc-manged objects in Node.js internals should extend this mixin,
 * while non-cppgc-managed objects typically extend BaseObject - the
 * latter are being migrated to be cppgc-managed wherever it's beneficial
 * and practical. Typically cppgc-managed objects are more efficient to
 * keep track of (which lowers initialization cost) and work better
 * with V8's GC scheduling.
 *
 * A cppgc-managed native wrapper should look something like this, note
 * that per cppgc rules, CPPGC_MIXIN(MyWrap) must be at the left-most
 * position in the hierarchy (which ensures cppgc::GarbageCollected
 * is at the left-most position).
 *
 * class MyWrap final : CPPGC_MIXIN(MyWrap) {
 *  public:
 *   SET_CPPGC_NAME(MyWrap)  // Sets the heap snapshot name to "Node / MyWrap"
 *   void Trace(cppgc::Visitor* visitor) const final {
 *     CppgcMixin::Trace(visitor);
 *     visitor->Trace(...);  // Trace any additional owned traceable data
 *   }
 * }
 *
 * If the wrapper needs to perform cleanups when it's destroyed and that
 * cleanup relies on a living Node.js `Realm`, it should implement a
 * pattern like this:
 *
 *   ~MyWrap() { this->Destroy(); }
 *   void Clean(Realm* env) override {
 *     // Do cleanup that relies on a living Environemnt.
 *   }
 */
class CppgcMixin : public cppgc::GarbageCollectedMixin, public MemoryRetainer {
 public:
  // To help various callbacks access wrapper objects with different memory
  // management, cppgc-managed objects share the same layout as BaseObjects.
  enum InternalFields { kEmbedderType = 0, kSlot, kInternalFieldCount };

  // The initialization cannot be done in the mixin constructor but has to be
  // invoked from the child class constructor, per cppgc::GarbageCollectedMixin
  // rules.
  template <typename T>
  static inline void Wrap(T* ptr, Realm* realm, v8::Local<v8::Object> obj);
  template <typename T>
  static inline void Wrap(T* ptr, Environment* env, v8::Local<v8::Object> obj);

  inline v8::Local<v8::Object> object() const;
  inline Environment* env() const;
  inline Realm* realm() const { return realm_; }
  inline v8::Local<v8::Object> object(v8::Isolate* isolate) const {
    return traced_reference_.Get(isolate);
  }

  template <typename T>
  static inline T* Unwrap(v8::Local<v8::Object> obj);

  // Subclasses are expected to invoke CppgcMixin::Trace() in their own Trace()
  // methods.
  void Trace(cppgc::Visitor* visitor) const override {
    visitor->Trace(traced_reference_);
  }

  // TODO(joyeecheung): use ObjectSizeTrait;
  inline size_t SelfSize() const override { return sizeof(*this); }
  inline bool IsCppgcWrapper() const override { return true; }

  // This is run for all the remaining Cppgc wrappers tracked in the Realm
  // during Realm shutdown. The destruction of the wrappers would happen later,
  // when the final garbage collection is triggered when CppHeap is torn down as
  // part of the Isolate teardown. If subclasses of CppgcMixin wish to perform
  // cleanups that depend on the Realm during destruction, they should implment
  // it in a Clean() override, and then call this->Finalize() from their
  // destructor. Outside of Finalize(), subclasses should avoid calling
  // into JavaScript or perform any operation that can trigger garbage
  // collection during the destruction.
  void Finalize() {
    if (realm_ == nullptr) return;
    this->Clean(realm_);
    realm_ = nullptr;
  }

  // The default implementation of Clean() is a no-op. If subclasses wish
  // to perform cleanup that require a living Realm, they should
  // should put the cleanups in a Clean() override, and call this->Finalize()
  // in the destructor, instead of doing those cleanups directly in the
  // destructor.
  virtual void Clean(Realm* realm) {}

  inline ~CppgcMixin();

  friend class CppgcWrapperListNode;

 private:
  Realm* realm_ = nullptr;
  v8::TracedReference<v8::Object> traced_reference_;
};

// If the class doesn't have additional owned traceable data, use this macro to
// save the implementation of a custom Trace() method.
#define DEFAULT_CPPGC_TRACE()                                                  \
  void Trace(cppgc::Visitor* visitor) const final {                            \
    CppgcMixin::Trace(visitor);                                                \
  }

// This macro sets the node name in the heap snapshot with a "Node /" prefix.
// Classes that use this macro must extend cppgc::NameProvider.
#define SET_CPPGC_NAME(Klass)                                                  \
  inline const char* GetHumanReadableName() const final {                      \
    return "Node / " #Klass;                                                   \
  }                                                                            \
  inline const char* MemoryInfoName() const override { return #Klass; }

/**
 * Similar to ASSIGN_OR_RETURN_UNWRAP() but works on cppgc-managed types
 * inheriting CppgcMixin.
 */
#define ASSIGN_OR_RETURN_UNWRAP_CPPGC(ptr, obj, ...)                           \
  do {                                                                         \
    *ptr = CppgcMixin::Unwrap<                                                 \
        typename std::remove_reference<decltype(**ptr)>::type>(obj);           \
    if (*ptr == nullptr) return __VA_ARGS__;                                   \
  } while (0)
}  // namespace node

/**
 * Helper macro the manage the cppgc-based wrapper hierarchy. This must
 * be used at the left-most position - right after `:` in the class inheritance,
 * like this:
 * class Klass : CPPGC_MIXIN(Klass) ... {}
 *
 * This needs to disable linters because it will be at odds with
 * clang-format.
 */
#define CPPGC_MIXIN(Klass)                                                     \
  public /* NOLINT(whitespace/indent) */                                       \
  v8::Object::Wrappable, public CppgcMixin

#endif  // defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS

#endif  // SRC_CPPGC_HELPERS_H_