src: track cppgc wrappers with a list in Realm · nodejs/node@a35cc21

#include <type_traits> // std::remove_reference

#include "cppgc/garbage-collected.h"

#include "cppgc/name-provider.h"

#include "env.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.

* with V8's GC scheduling.

*

* A cppgc-managed native wrapper should look something like this, note

* that per cppgc rules, CPPGC_MIXIN(Klass) must be at the left-most

* 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 Klass final : CPPGC_MIXIN(Klass) {

* class MyWrap final : CPPGC_MIXIN(MyWrap) {

* public:

* SET_CPPGC_NAME(Klass) // Sets the heap snapshot name to "Node / Klass"

* 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 {

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.

// invoked from the child class constructor, per cppgc::GarbageCollectedMixin

// rules.

template <typename T>

static void Wrap(T* ptr, Environment* env, v8::Local<v8::Object> obj) {

CHECK_GE(obj->InternalFieldCount(), T::kInternalFieldCount);

ptr->env_ = env;

v8::Isolate* isolate = env->isolate();

ptr->traced_reference_ = v8::TracedReference<v8::Object>(isolate, obj);

v8::Object::Wrap<v8::CppHeapPointerTag::kDefaultTag>(isolate, obj, ptr);

// Keep the layout consistent with BaseObjects.

obj->SetAlignedPointerInInternalField(

kEmbedderType, env->isolate_data()->embedder_id_for_cppgc());

obj->SetAlignedPointerInInternalField(kSlot, ptr);

}

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);

v8::Local<v8::Object> object() const {

return traced_reference_.Get(env_->isolate());

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);

}

Environment* env() const { return env_; }

template <typename T>

static T* Unwrap(v8::Local<v8::Object> obj) {

// We are not using v8::Object::Unwrap currently because that requires

// access to isolate which the ASSIGN_OR_RETURN_UNWRAP macro that we'll shim

// with ASSIGN_OR_RETURN_UNWRAP_GC doesn't take, and we also want a

// signature consistent with BaseObject::Unwrap() to avoid churn. Since

// cppgc-managed objects share the same layout as BaseObjects, just unwrap

// from the pointer in the internal field, which should be valid as long as

// the object is still alive.

if (obj->InternalFieldCount() != T::kInternalFieldCount) {

return nullptr;

}

T* ptr = static_cast<T*>(obj->GetAlignedPointerFromInternalField(T::kSlot));

return ptr;

}

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:

Environment* env_;

Realm* realm_ = nullptr;

v8::TracedReference<v8::Object> traced_reference_;

};

#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