src: add utilities for cppgc classes

Author: joyeecheung

node.gyp

@@ -202,6 +202,7 @@
       'src/compile_cache.h',
       'src/connect_wrap.h',
       'src/connection_wrap.h',
+      'src/cppgc_helpers.h',
       'src/dataqueue/queue.h',
       'src/debug_utils.h',
       'src/debug_utils-inl.h',

src/README.md

@@ -975,6 +975,166 @@ overview over libuv handles managed by Node.js.
 
 <a id="callback-scopes"></a>
 
+### `CppgcMixin`
+
+V8 comes with a trace-based C++ garbage collection library called
+[Oilpan][], whose API is in headers under`deps/v8/include/cppgc`.
+In this document we refer to it as `cppgc` since that's the namespace
+of the library.
+
+C++ objects managed using `cppgc` are allocated in the V8 heap
+and traced by V8's garbage collector. The `cppgc` library provides
+APIs for embedders to create references between cppgc-managed objects
+and other objects in the V8 heap (such as JavaScript objects or other
+objects in the V8 C++ API that can be passed around with V8 handles)
+in a way that's understood by V8's garbage collector.
+This helps avoiding accidental memory leaks and use-after-frees coming
+from incorrect cross-heap reference tracking, especially when there are
+cyclic references. This is what powers the
+[unified heap design in Chromium][] to avoid cross-heap memory issues,
+and it's being rolled out in Node.js to reap similar benefits.
+
+For general guidance on how to use `cppgc`, see the
+[Oilpan documentation in Chromium][]. In Node.js there is a helper
+mixin `node::CppgcMixin` from `cppgc_helpers.h` to help implementing
+`cppgc`-managed wrapper objects with a [`BaseObject`][]-like interface.
+`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::GarbageCollected<>` must be the left-most
+base class.
+
+```cpp
+#include "cppgc_helpers.h"
+
+class MyWrap final : public cppgc::GarbageCollected<MyWrap>,
+                    public cppgc::NameProvider,
+                    public CppgcMixin {
+ public:
+  SET_CPPGC_NAME(MyWrap)  // Sets the heap snapshot name to "Node / MyWrap"
+
+  MyWrap(Environment* env, v8::Local<v8::Object> object);
+  MyWrap* New(Environment* env, v8::Local<v8::Object> object);
+
+  void Trace(cppgc::Visitor* visitor) const final;
+}
+```
+
+`cppgc::GarbageCollected` objects should not be allocated with usual C++
+primitives (e.g. using `new` or `std::make_unique` is forbidden). Instead
+they must be allocated using `cppgc::MakeGarbageCollected` - this would
+allocate them in the V8 heap and allow V8's garbage collector to trace them.
+It's recommended to use a `New` method to prepare the arguments and invoke
+`cppgc::MakeGarbageCollected` (which forwards the arguments to the child class
+constructor).
+
+```cpp
+MyWrap::MyWrap(Environment* env, v8::Local<v8::Object> object) {
+  // This cannot invoke the mixin constructor and has to invoke a static
+  // method from it, per cppgc rules. node::CppgcMixin provides
+  // InitializeCppgc() for wrapping the C++ object with the provided
+  // JavaScript object.
+  InitializeCppgc(this, env, object);
+}
+
+MyWrap* MyWrap::New(Environment* env, v8::Local<v8::Object> object) {
+  // Per cppgc rules, the constructor of MyWrap cannot be invoked directly.
+  // It's recommended to implement a New() static method that prepares
+  // and forwards the necessary arguments to cppgc::MakeGarbageCollected()
+  // and just return the raw pointer around - do not use any C++ smart
+  // pointer with this, as this is not managed by the native memory
+  // allocator but by V8.
+  return cppgc::MakeGarbageCollected<MyWrap>(
+      env->isolate()->GetCppHeap()->GetAllocationHandle(), env, object);
+}
+```
+
+`cppgc::GarbageCollected` types are expected to implement a
+`void Trace(cppgc::Visitor* visitor) const` method. When they are the
+final class in the hierarchy, this method must be marked `final`. For
+classes extending `node::CppgcMixn`, this should typically dispatch a
+call to `CppgcMixin::Trace()` first, then trace any additional owned data
+it has. See `deps/v8/include/cppgc/garbage-collected.h` see what types of
+data can be traced.
+
+```cpp
+void MyWrap::Trace(cppgc::Visitor* visitor) const {
+  CppgcMixin::Trace(visitor);
+  visitor->Trace(...);  // Trace any additional data MyWrap has
+}
+```
+
+#### Creating C++ to JavaScript references in cppgc-managed objects
+
+Unlike `BaseObject` which typically uses a `v8::Global` (either weak or strong)
+to reference an object from the V8 heap, cppgc-managed objects are expected to
+use `v8::TracedReference` (which supports any `v8::Data`). For example if the
+`MyWrap` object owns a `v8::UnboundScript`, in the class body the reference
+should be declared as
+
+```cpp
+class MyWrap : ... {
+ v8::TracedReference<v8::UnboundScript> script;
+}
+```
+
+V8's garbage collector traces the references from `MyWrap` through the
+`MyWrap::Trace()` method, which should call `cppgc::Visitor::Trace` on the
+`v8::TracedReference`.
+
+```cpp
+void MyWrap::Trace(cppgc::Visitor* visitor) const {
+  CppgcMixin::Trace(visitor);
+  visitor->Trace(script);  // v8::TracedReference is supported by cppgc::Visitor
+}
+```
+
+As long as a `MyWrap` object is alive, the `v8::UnboundScript` in its
+`v8::TracedReference` will be kept alive. When the `MyWrap` object is no longer
+reachable from the V8 heap, and there are no other references to the
+`v8::UnboundScript` it owns, the `v8::UnboundScript` will be garbage collected
+along with its owning `MyWrap`. The reference will also be automatically
+captured in the heap snapshots.
+
+#### Creating JavaScript to C++ references for cppgc-managed objects
+
+All C++ objects using `node::CppgcMixin` have a counterpart JavaScript object,
+which can be obtained in C++ using `node::CppgcMixin::object()`.
+The two references each other internally - this cycle is well-understood by V8's
+garbage collector and can be managed properly. To create a reference from another
+JavaScript object to a C++ wrapper extending `node::CppgcMixin`, just create a
+JavaScript to JavaScript reference via its counterpart JavaScript object instead.
+
+```cpp
+MyWrap* wrap = ....;  // Obtain a reference to the cppgc-managed object.
+Local<Object> referrer = ...;  // This is the referrer object.
+// To reference the C++ wrap from the JavaScript referrer, simply creates
+// a usual JavaScript property reference - the key can be a symbol or a
+// number too if necessary, or it can be a private symbol property added
+// using SetPrivate(). wrap->object() can also be passed to the JavaScript
+// land, which can be referenced by any JavaScript objects in an invisible
+// manner using a WeakMap or being inside a closure.
+referrer->Set(
+  context, FIXED_ONE_BYTE_STRING(isolate, "ref"), wrap->object()
+).ToLocalChecked();
+```
+
+Typically, a newly created cppgc-managed wrapper object should be held alive
+by the JavaScript land (for example, by being returned by a method and
+staying alive in a closure). Long-lived cppgc objects can also
+be held alive from C++ using persistent handles (see
+`deps/v8/include/cppgc/persistent.h`) or as members of other living
+cppgc-managed objects (see `deps/v8/include/cppgc/member.h`) if necessary.
+Its destructor will be called when no other objects from the V8 heap reference
+it, this can happen at any time after the garbage collector notices that
+it's no longer reachable and before the V8 isolate is torn down.
+See the [Oilpan documentation in Chromium][] for more details.
+
 ### Callback scopes
 
 The public `CallbackScope` and the internally used `InternalCallbackScope`
@@ -1082,6 +1242,8 @@ static void GetUserInfo(const FunctionCallbackInfo<Value>& args) {
 [ECMAScript realm]: https://tc39.es/ecma262/#sec-code-realms
 [JavaScript value handles]: #js-handles
 [N-API]: https://nodejs.org/api/n-api.html
+[Oilpan]: https://v8.dev/blog/oilpan-library
+[Oilpan documentation in Chromium]: https://chromium.googlesource.com/v8/v8/+/main/include/cppgc/README.md
 [`BaseObject`]: #baseobject
 [`Context`]: #context
 [`Environment`]: #environment
@@ -1117,3 +1279,4 @@ static void GetUserInfo(const FunctionCallbackInfo<Value>& args) {
 [libuv handles]: #libuv-handles-and-requests
 [libuv requests]: #libuv-handles-and-requests
 [reference documentation for the libuv API]: http://docs.libuv.org/en/v1.x/
+[unified heap design in Chromium]: https://docs.google.com/document/d/1Hs60Zx1WPJ_LUjGvgzt1OQ5Cthu-fG-zif-vquUH_8c/edit

src/cppgc_helpers.h

@@ -0,0 +1,117 @@
+#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 "env.h"
+#include "memory_tracker.h"
+#include "v8-cppgc.h"
+#include "v8.h"
+
+namespace node {
+
+// Similar to ASSIGN_OR_RETURN_UNWRAP() macro, but for cppgc objects.
+#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)
+
+/**
+ * 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::GarbageCollected<> must be the left-most
+ * base class.
+ *
+ * class Klass final : public cppgc::GarbageCollected<Klass>,
+ *                     public cppgc::NameProvider,
+ *                     public CppgcMixin {
+ *  public:
+ *   SET_CPPGC_NAME(Klass)  // Sets the heap snapshot name to "Node / Klass"
+ *   void Trace(cppgc::Visitor* visitor) const final {
+ *     CppgcMixin::Trace(visitor);
+ *     visitor->Trace(...);  // Trace any additional owned traceable data
+ *   }
+ * }
+ * TODO(joyeecheung): make it a class template?
+ */
+class CppgcMixin : public cppgc::GarbageCollectedMixin {
+ 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>
+  void InitializeCppgc(T* ptr, Environment* env, v8::Local<v8::Object> obj) {
+    env_ = env;
+    traced_reference_ = v8::TracedReference<v8::Object>(env->isolate(), obj);
+    SetCppgcReference(env->isolate(), obj, ptr);
+    CHECK_GE(obj->InternalFieldCount(), T::kInternalFieldCount);
+    obj->SetAlignedPointerInInternalField(T::kSlot, ptr);
+  }
+
+  v8::Local<v8::Object> object() const {
+    return traced_reference_.Get(env_->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 cppgc-allocated types doesn't take.
+    // 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;
+  }
+
+  // Subclasses are expected to invoke CppgcMixin::Trace() in their own Trace()
+  // methods.
+  void Trace(cppgc::Visitor* visitor) const override {
+    visitor->Trace(traced_reference_);
+  }
+
+ private:
+  Environment* env_;
+  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;                                                   \
+  }
+}  // namespace node
+
+#endif  // defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
+
+#endif  // SRC_CPPGC_HELPERS_H_

src/heap_utils.cc

@@ -21,6 +21,7 @@
 using v8::Array;
 using v8::Boolean;
 using v8::Context;
+using v8::Data;
 using v8::EmbedderGraph;
 using v8::EscapableHandleScope;
 using v8::FunctionCallbackInfo;
@@ -50,18 +51,20 @@ class JSGraphJSNode : public EmbedderGraph::Node {
   const char* Name() override { return "<JS Node>"; }
   size_t SizeInBytes() override { return 0; }
   bool IsEmbedderNode() override { return false; }
-  Local<Value> JSValue() { return PersistentToLocal::Strong(persistent_); }
+  Local<Data> V8Value() { return PersistentToLocal::Strong(persistent_); }
 
   int IdentityHash() {
-    Local<Value> v = JSValue();
+    Local<Data> d = V8Value();
+    // TODO(joyeecheung): return something better?
+    if (!d->IsValue()) return reinterpret_cast<std::uintptr_t>(this);
+    Local<Value> v = d.As<Value>();
     if (v->IsObject()) return v.As<Object>()->GetIdentityHash();
     if (v->IsName()) return v.As<v8::Name>()->GetIdentityHash();
     if (v->IsInt32()) return v.As<v8::Int32>()->Value();
     return 0;
   }
 
-  JSGraphJSNode(Isolate* isolate, Local<Value> val)
-      : persistent_(isolate, val) {
+  JSGraphJSNode(Isolate* isolate, Local<Data> val) : persistent_(isolate, val) {
     CHECK(!val.IsEmpty());
   }
 
@@ -73,19 +76,27 @@ class JSGraphJSNode : public EmbedderGraph::Node {
 
   struct Equal {
     inline bool operator()(JSGraphJSNode* a, JSGraphJSNode* b) const {
-      return a->JSValue()->SameValue(b->JSValue());
+      Local<Data> data_a = a->V8Value();
+      Local<Data> data_b = a->V8Value();
+      if (data_a->IsValue()) {
+        if (!data_b->IsValue()) {
+          return false;
+        }
+        return data_a.As<Value>()->SameValue(data_b.As<Value>());
+      }
+      return data_a == data_b;
     }
   };
 
  private:
-  Global<Value> persistent_;
+  Global<Data> persistent_;
 };
 
 class JSGraph : public EmbedderGraph {
  public:
   explicit JSGraph(Isolate* isolate) : isolate_(isolate) {}
 
-  Node* V8Node(const Local<Value>& value) override {
+  Node* V8Node(const Local<v8::Data>& value) override {
     std::unique_ptr<JSGraphJSNode> n { new JSGraphJSNode(isolate_, value) };
     auto it = engine_nodes_.find(n.get());
     if (it != engine_nodes_.end())
@@ -94,6 +105,10 @@ class JSGraph : public EmbedderGraph {
     return AddNode(std::unique_ptr<Node>(n.release()));
   }
 
+  Node* V8Node(const Local<v8::Value>& value) override {
+    return V8Node(value.As<v8::Data>());
+  }
+
   Node* AddNode(std::unique_ptr<Node> node) override {
     Node* n = node.get();
     nodes_.emplace(std::move(node));
@@ -154,8 +169,9 @@ class JSGraph : public EmbedderGraph {
         if (nodes->Set(context, i++, obj).IsNothing())
           return MaybeLocal<Array>();
         if (!n->IsEmbedderNode()) {
-          value = static_cast<JSGraphJSNode*>(n.get())->JSValue();
-          if (obj->Set(context, value_string, value).IsNothing())
+          Local<Data> data = static_cast<JSGraphJSNode*>(n.get())->V8Value();
+          if (data->IsValue() &&
+              obj->Set(context, value_string, data.As<Value>()).IsNothing())
             return MaybeLocal<Array>();
         }
       }