Repository navigation
Expand file tree
/
Copy pathcppgc_helpers.h
More file actions
156 lines (136 loc) · 6.3 KB
/
Copy pathcppgc_helpers.h
File metadata and controls
156 lines (136 loc) · 6.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
#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->Finalize(); }
* void Clean(Realm* env) override {
* // Do cleanup that relies on a living Realm.
* }
*/
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;
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 implement
// 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.
inline void Finalize();
// 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();
private:
CppgcWrapperListNode* list_node_ = 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_