mirror of
https://github.com/nodejs/node.git
synced 2026-11-15 10:36:53 -05:00
This allows us to perform cleanups of cppgc wrappers that rely on a
living Realm during Realm shutdown. Otherwise the cleanup may happen
during object destruction, which can be triggered by GC after Realm
shutdown, leading to invalid access to Realm.
The general pattern for this type of non-trivial destruction is
designed to be:
```
class MyWrap final : CPPGC_MIXIN(MyWrap) {
public:
~MyWrap() { this->Finalize(); }
void Clean(Realm* realm) override {
// Do cleanup that relies on a living Realm. This would be
// called by CppgcMixin::Finalize() first during Realm
// shutdown, while the Realm is still alive. If the destructor
// calls Finalize() again later during garbage collection that
// happens after Realm shutdown, Clean() would be skipped,
// preventing invalid access to the Realm.
}
}
```
In addition, this allows us to trace external memory held by the
wrappers in the heap snapshots if we add synthethic edges between the
wrappers and other nodes in the embdder graph callback, or to perform
snapshot serialization for them.
PR-URL: https://github.com/nodejs/node/pull/56534
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
237 lines
7.9 KiB
C++
237 lines
7.9 KiB
C++
#ifndef SRC_NODE_REALM_H_
|
|
#define SRC_NODE_REALM_H_
|
|
|
|
#if defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
|
|
|
|
#include <v8.h>
|
|
#include <unordered_map>
|
|
#include "cleanup_queue.h"
|
|
#include "cppgc_helpers.h"
|
|
#include "env_properties.h"
|
|
#include "memory_tracker.h"
|
|
#include "node_snapshotable.h"
|
|
|
|
namespace node {
|
|
|
|
struct RealmSerializeInfo {
|
|
std::vector<std::string> builtins;
|
|
std::vector<PropInfo> persistent_values;
|
|
std::vector<PropInfo> native_objects;
|
|
|
|
SnapshotIndex context;
|
|
friend std::ostream& operator<<(std::ostream& o, const RealmSerializeInfo& i);
|
|
};
|
|
|
|
using BindingDataStore =
|
|
std::array<BaseObjectWeakPtr<BaseObject>,
|
|
static_cast<size_t>(BindingDataType::kBindingDataTypeCount)>;
|
|
|
|
/**
|
|
* This is a wrapper around a weak persistent of CppgcMixin, used in the
|
|
* CppgcWrapperList to avoid accessing already garbage collected CppgcMixins.
|
|
*/
|
|
class CppgcWrapperListNode {
|
|
public:
|
|
explicit inline CppgcWrapperListNode(CppgcMixin* ptr);
|
|
inline explicit operator bool() const { return !persistent; }
|
|
inline CppgcMixin* operator->() const { return persistent.Get(); }
|
|
inline CppgcMixin* operator*() const { return persistent.Get(); }
|
|
|
|
cppgc::WeakPersistent<CppgcMixin> persistent;
|
|
// Used by ContainerOf in the ListNode implementation for fast manipulation of
|
|
// CppgcWrapperList.
|
|
ListNode<CppgcWrapperListNode> wrapper_list_node;
|
|
};
|
|
|
|
/**
|
|
* A per-realm list of weak persistent of cppgc wrappers, which implements
|
|
* iterations that require iterate over cppgc wrappers created by Node.js.
|
|
*/
|
|
class CppgcWrapperList
|
|
: public ListHead<CppgcWrapperListNode,
|
|
&CppgcWrapperListNode::wrapper_list_node>,
|
|
public MemoryRetainer {
|
|
public:
|
|
void Cleanup();
|
|
void PurgeEmpty();
|
|
|
|
SET_MEMORY_INFO_NAME(CppgcWrapperList)
|
|
SET_SELF_SIZE(CppgcWrapperList)
|
|
void MemoryInfo(MemoryTracker* tracker) const override;
|
|
};
|
|
|
|
/**
|
|
* node::Realm is a container for a set of JavaScript objects and functions
|
|
* that associated with a particular global environment.
|
|
*
|
|
* An ECMAScript realm (https://tc39.es/ecma262/#sec-code-realms) representing
|
|
* a global environment in which script is run. Each ECMAScript realm comes
|
|
* with a global object and a set of intrinsic objects. An ECMAScript realm has
|
|
* a [[HostDefined]] field, which contains the node::Realm object.
|
|
*
|
|
* Realm can be a principal realm or a synthetic realm. A principal realm is
|
|
* created with an Environment as its principal global environment to evaluate
|
|
* scripts. A synthetic realm is created with JS APIs like ShadowRealm.
|
|
*
|
|
* Native bindings and builtin modules can be evaluated in either a principal
|
|
* realm or a synthetic realm.
|
|
*/
|
|
class Realm : public MemoryRetainer {
|
|
public:
|
|
enum Kind {
|
|
kPrincipal,
|
|
kShadowRealm,
|
|
};
|
|
|
|
static inline Realm* GetCurrent(v8::Isolate* isolate);
|
|
static inline Realm* GetCurrent(v8::Local<v8::Context> context);
|
|
static inline Realm* GetCurrent(
|
|
const v8::FunctionCallbackInfo<v8::Value>& info);
|
|
template <typename T>
|
|
static inline Realm* GetCurrent(const v8::PropertyCallbackInfo<T>& info);
|
|
|
|
Realm(Environment* env, v8::Local<v8::Context> context, Kind kind);
|
|
|
|
Realm(const Realm&) = delete;
|
|
Realm& operator=(const Realm&) = delete;
|
|
Realm(Realm&&) = delete;
|
|
Realm& operator=(Realm&&) = delete;
|
|
|
|
void MemoryInfo(MemoryTracker* tracker) const override;
|
|
|
|
void CreateProperties();
|
|
RealmSerializeInfo Serialize(v8::SnapshotCreator* creator);
|
|
void DeserializeProperties(const RealmSerializeInfo* info);
|
|
|
|
v8::MaybeLocal<v8::Value> ExecuteBootstrapper(const char* id);
|
|
v8::MaybeLocal<v8::Value> RunBootstrapping();
|
|
|
|
inline void TrackBaseObject(BaseObject* bo);
|
|
inline void UntrackBaseObject(BaseObject* bo);
|
|
inline bool PendingCleanup() const;
|
|
void RunCleanup();
|
|
|
|
template <typename T>
|
|
void ForEachBaseObject(T&& iterator) const;
|
|
|
|
void PrintInfoForSnapshot();
|
|
void VerifyNoStrongBaseObjects();
|
|
|
|
inline IsolateData* isolate_data() const;
|
|
inline Environment* env() const;
|
|
inline v8::Isolate* isolate() const;
|
|
inline Kind kind() const;
|
|
virtual v8::Local<v8::Context> context() const;
|
|
inline bool has_run_bootstrapping_code() const;
|
|
|
|
// Methods created using SetMethod(), SetPrototypeMethod(), etc. inside
|
|
// this scope can access the created T* object using
|
|
// GetBindingData<T>(args) later.
|
|
template <typename T, typename... Args>
|
|
T* AddBindingData(v8::Local<v8::Object> target, Args&&... args);
|
|
template <typename T, typename U>
|
|
static inline T* GetBindingData(const v8::PropertyCallbackInfo<U>& info);
|
|
template <typename T>
|
|
static inline T* GetBindingData(
|
|
const v8::FunctionCallbackInfo<v8::Value>& info);
|
|
template <typename T>
|
|
static inline T* GetBindingData(v8::Local<v8::Context> context);
|
|
template <typename T>
|
|
inline T* GetBindingData();
|
|
inline BindingDataStore* binding_data_store();
|
|
|
|
// The BaseObject count is a debugging helper that makes sure that there are
|
|
// no memory leaks caused by BaseObjects staying alive longer than expected
|
|
// (in particular, no circular BaseObjectPtr references).
|
|
inline int64_t base_object_count() const;
|
|
|
|
// Base object count created after the bootstrap of the realm.
|
|
inline int64_t base_object_created_after_bootstrap() const;
|
|
|
|
inline void TrackCppgcWrapper(CppgcMixin* handle);
|
|
inline CppgcWrapperList* cppgc_wrapper_list() { return &cppgc_wrapper_list_; }
|
|
|
|
#define V(PropertyName, TypeName) \
|
|
virtual v8::Local<TypeName> PropertyName() const = 0; \
|
|
virtual void set_##PropertyName(v8::Local<TypeName> value) = 0;
|
|
PER_REALM_STRONG_PERSISTENT_VALUES(V)
|
|
#undef V
|
|
|
|
std::set<struct node_module*> internal_bindings;
|
|
std::set<std::string> builtins_with_cache;
|
|
std::set<std::string> builtins_without_cache;
|
|
// This is only filled during deserialization. We use a vector since
|
|
// it's only used for tests.
|
|
std::vector<std::string> builtins_in_snapshot;
|
|
|
|
// This used during the destruction of cppgc wrappers to inform a GC epilogue
|
|
// callback to clean up the weak persistents used to track cppgc wrappers if
|
|
// the wrappers are already garbage collected to prevent holding on to
|
|
// excessive useless persistents.
|
|
inline void set_should_purge_empty_cppgc_wrappers(bool value) {
|
|
should_purge_empty_cppgc_wrappers_ = value;
|
|
}
|
|
|
|
protected:
|
|
~Realm();
|
|
|
|
virtual v8::MaybeLocal<v8::Value> BootstrapRealm() = 0;
|
|
|
|
Environment* env_;
|
|
// Shorthand for isolate pointer.
|
|
v8::Isolate* isolate_;
|
|
v8::Global<v8::Context> context_;
|
|
bool should_purge_empty_cppgc_wrappers_ = false;
|
|
|
|
#define V(PropertyName, TypeName) v8::Global<TypeName> PropertyName##_;
|
|
PER_REALM_STRONG_PERSISTENT_VALUES(V)
|
|
#undef V
|
|
|
|
static void PurgeEmptyCppgcWrappers(v8::Isolate* isolate,
|
|
v8::GCType type,
|
|
v8::GCCallbackFlags flags,
|
|
void* data);
|
|
|
|
private:
|
|
void InitializeContext(v8::Local<v8::Context> context,
|
|
const RealmSerializeInfo* realm_info);
|
|
void DoneBootstrapping();
|
|
|
|
Kind kind_;
|
|
bool has_run_bootstrapping_code_ = false;
|
|
|
|
int64_t base_object_count_ = 0;
|
|
int64_t base_object_created_by_bootstrap_ = 0;
|
|
|
|
BindingDataStore binding_data_store_;
|
|
|
|
BaseObjectList base_object_list_;
|
|
CppgcWrapperList cppgc_wrapper_list_;
|
|
};
|
|
|
|
class PrincipalRealm : public Realm {
|
|
public:
|
|
PrincipalRealm(Environment* env,
|
|
v8::Local<v8::Context> context,
|
|
const RealmSerializeInfo* realm_info);
|
|
~PrincipalRealm();
|
|
|
|
SET_MEMORY_INFO_NAME(PrincipalRealm)
|
|
SET_SELF_SIZE(PrincipalRealm)
|
|
|
|
#define V(PropertyName, TypeName) \
|
|
v8::Local<TypeName> PropertyName() const override; \
|
|
void set_##PropertyName(v8::Local<TypeName> value) override;
|
|
PER_REALM_STRONG_PERSISTENT_VALUES(V)
|
|
#undef V
|
|
|
|
protected:
|
|
v8::MaybeLocal<v8::Value> BootstrapRealm() override;
|
|
};
|
|
|
|
} // namespace node
|
|
|
|
#endif // defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
|
|
|
|
#endif // SRC_NODE_REALM_H_
|