@encharm/cws 4.5.2 → 4.6.0

package/src/headers/26/memory_tracker.h

@@ -0,0 +1,341 @@
+#pragma once
+
+#if defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
+
+#include "node_concepts.h"
+#include "v8-profiler.h"
+
+#include <uv.h>
+
+#include <limits>
+#include <queue>
+#include <stack>
+#include <string>
+#include <unordered_map>
+
+namespace v8 {
+class BackingStore;
+}
+
+namespace node {
+
+class CppgcMixin;
+
+template <typename T>
+struct MallocedBuffer;
+
+// Set the node name of a MemoryRetainer to klass
+#define SET_MEMORY_INFO_NAME(Klass)                                            \
+  inline const char* MemoryInfoName() const override { return #Klass; }
+
+// Set the self size of a MemoryRetainer to the stack-allocated size of a
+// certain class
+#define SET_SELF_SIZE(Klass)                                                   \
+  inline size_t SelfSize() const override { return sizeof(Klass); }
+
+// Used when there is no additional fields to track
+#define SET_NO_MEMORY_INFO()                                                   \
+  inline void MemoryInfo(node::MemoryTracker* tracker) const override {}
+
+class MemoryTracker;
+class MemoryRetainerNode;
+template <typename T, bool kIsWeak>
+class BaseObjectPtrImpl;
+
+namespace crypto {
+class NodeBIO;
+}
+
+class CleanupHookCallback;
+
+/* Example:
+ *
+ * class ExampleRetainer : public MemoryRetainer {
+ *   public:
+ *     // Or use SET_NO_MEMORY_INFO() when there is no additional fields
+ *     // to track.
+ *     void MemoryInfo(MemoryTracker* tracker) const override {
+ *       // Node name and size comes from the MemoryInfoName and SelfSize of
+ *       // AnotherRetainerClass
+ *       tracker->TrackField("another_retainer", another_retainer_);
+ *
+ *       // Add non_pointer_retainer as a separate node into the graph
+ *       // and track its memory information recursively.
+ *       // Note that we need to make sure its size is not accounted in
+ *       // ExampleRetainer::SelfSize().
+ *       tracker->TrackField("non_pointer_retainer", &non_pointer_retainer_);
+ *
+ *       // Specify node name and size explicitly
+ *       tracker->TrackFieldWithSize("internal_member",
+ *                                   internal_member_.size(),
+ *                                   "InternalClass");
+ *       // Node name falls back to the edge name,
+ *       // elements in the container appear as grandchildren nodes
+ *       tracker->TrackField("vector", vector_);
+ *       // Node name and size come from the JS object
+ *       tracker->TrackField("target", target_);
+ *     }
+ *
+ *     // Or use SET_MEMORY_INFO_NAME(ExampleRetainer)
+ *     const char* MemoryInfoName() const override {
+ *       return "ExampleRetainer";
+ *     }
+ *
+ *     // Classes that only want to return its sizeof() value can use the
+ *     // SET_SELF_SIZE(Class) macro instead.
+ *     size_t SelfSize() const override {
+ *       // We need to exclude the size of non_pointer_retainer so that
+ *       // we can track it separately in ExampleRetainer::MemoryInfo().
+ *       return sizeof(ExampleRetainer) - sizeof(NonPointerRetainerClass);
+ *     }
+ *
+ *     // Note: no need to implement these two methods when implementing
+ *     // a BaseObject or an AsyncWrap class
+ *     bool IsRootNode() const override { return !wrapped_.IsWeak(); }
+ *     v8::Local<v8::Object> WrappedObject() const override {
+ *       return node::PersistentToLocal::Default(wrapped_);
+ *     }
+ *
+ *   private:
+ *     AnotherRetainerClass* another_retainer_;
+ *     NonPointerRetainerClass non_pointer_retainer;
+ *     InternalClass internal_member_;
+ *     std::vector<uv_async_t> vector_;
+ *     v8::Global<Object> target_;
+ *
+ *     v8::Global<Object> wrapped_;
+ * }
+ *
+ * This creates the following graph:
+ *   Node / ExampleRetainer
+ *    |> another_retainer :: Node / AnotherRetainerClass
+ *    |> internal_member :: Node / InternalClass
+ *    |> vector :: Node / vector (elements will be grandchildren)
+ *        |> [1] :: Node / uv_async_t (uv_async_t has predefined names)
+ *        |> [2] :: Node / uv_async_t
+ *        |> ...
+ *    |> target :: TargetClass (JS class name of the target object)
+ *    |> wrapped :: WrappedClass (JS class name of the wrapped object)
+ *        |> wrapper :: Node / ExampleRetainer (back reference)
+ */
+class MemoryRetainer {
+ public:
+  virtual ~MemoryRetainer() = default;
+
+  // Subclasses should implement these methods to provide information
+  // for the V8 heap snapshot generator.
+  // The MemoryInfo() method is assumed to be called within a context
+  // where all the edges start from the node of the current retainer,
+  // and point to the nodes as specified by tracker->Track* calls.
+  virtual void MemoryInfo(MemoryTracker* tracker) const = 0;
+  virtual const char* MemoryInfoName() const = 0;
+  virtual size_t SelfSize() const = 0;
+
+  virtual v8::Local<v8::Object> WrappedObject() const {
+    return v8::Local<v8::Object>();
+  }
+
+  virtual bool IsRootNode() const { return false; }
+  virtual bool IsCppgcWrapper() const { return false; }
+  virtual v8::EmbedderGraph::Node::Detachedness GetDetachedness() const {
+    return v8::EmbedderGraph::Node::Detachedness::kUnknown;
+  }
+};
+
+/**
+ * MemoryRetainerTraits allows defining a custom memory info for a
+ * class that can not be modified to implement the MemoryRetainer interface.
+ *
+ * Example:
+ *
+ * template <>
+ * struct MemoryRetainerTraits<ExampleRetainer> {
+ *   static void MemoryInfo(MemoryTracker* tracker,
+ *                         const ExampleRetainer& value) {
+ *     tracker->TrackField("another_retainer", value.another_retainer_);
+ *   }
+ *   static const char* MemoryInfoName(const ExampleRetainer& value) {
+ *     return "ExampleRetainer";
+ *   }
+ *   static size_t SelfSize(const ExampleRetainer& value) {
+ *     return sizeof(value);
+ *   }
+ * };
+ *
+ * This creates the following graph:
+ *   Node / ExampleRetainer
+ *    |> another_retainer :: Node / AnotherRetainerClass
+ */
+template <typename T, typename = void>
+struct MemoryRetainerTraits {};
+
+class MemoryTracker {
+ public:
+  // Used to specify node name and size explicitly
+  inline void TrackFieldWithSize(const char* edge_name,
+                                 size_t size,
+                                 const char* node_name = nullptr);
+  inline void TrackInlineFieldWithSize(const char* edge_name,
+                                       size_t size,
+                                       const char* node_name = nullptr);
+
+  // Shortcut to extract the underlying object out of the smart pointer
+  template <typename T, typename D>
+  inline void TrackField(const char* edge_name,
+                         const std::unique_ptr<T, D>& value,
+                         const char* node_name = nullptr);
+
+  template <typename T>
+  inline void TrackField(const char* edge_name,
+                         const std::shared_ptr<T>& value,
+                         const char* node_name = nullptr);
+
+  template <typename T, bool kIsWeak>
+  void TrackField(const char* edge_name,
+                  const BaseObjectPtrImpl<T, kIsWeak>& value,
+                  const char* node_name = nullptr);
+
+  // For containers, the elements will be graphed as grandchildren nodes
+  // if the container is not empty.
+  // By default, we assume the parent count the stack size of the container
+  // into its SelfSize so that will be subtracted from the parent size when we
+  // spin off a new node for the container.
+  // TODO(joyeecheung): use RTTI to retrieve the class name at runtime?
+  template <typename T, typename Iterator = typename T::const_iterator>
+  inline void TrackField(const char* edge_name,
+                         const T& value,
+                         const char* node_name = nullptr,
+                         const char* element_name = nullptr,
+                         bool subtract_from_self = true);
+  template <typename T>
+  inline void TrackField(const char* edge_name,
+                         const std::queue<T>& value,
+                         const char* node_name = nullptr,
+                         const char* element_name = nullptr);
+  template <typename T, typename U>
+  inline void TrackField(const char* edge_name,
+                         const std::pair<T, U>& value,
+                         const char* node_name = nullptr);
+
+  // For the following types, node_name will be ignored and predefined names
+  // will be used instead. They are only in the signature for template
+  // expansion.
+  inline void TrackField(const char* edge_name,
+                         const MemoryRetainer& value,
+                         const char* node_name = nullptr);
+  inline void TrackField(const char* edge_name,
+                         const MemoryRetainer* value,
+                         const char* node_name = nullptr);
+  template <typename T>
+  inline void TrackField(const char* edge_name,
+                         const std::basic_string<T>& value,
+                         const char* node_name = nullptr);
+  template <NumericValue T>
+  inline void TrackField(const char* edge_name,
+                         const T& value,
+                         const char* node_name = nullptr);
+  template <typename T>
+  void TrackField(const char* edge_name,
+                  const v8::Eternal<T>& value,
+                  const char* node_name);
+  template <typename T>
+  inline void TrackField(const char* edge_name,
+                         const v8::PersistentBase<T>& value,
+                         const char* node_name = nullptr);
+  template <typename T>
+  inline void TrackField(const char* edge_name,
+                         const v8::Local<T>& value,
+                         const char* node_name = nullptr);
+  template <typename T>
+  inline void TrackField(const char* edge_name,
+                         const MallocedBuffer<T>& value,
+                         const char* node_name = nullptr);
+  inline void TrackField(const char* edge_name,
+                         const v8::BackingStore* value,
+                         const char* node_name = nullptr);
+  inline void TrackField(const char* edge_name,
+                         const uv_buf_t& value,
+                         const char* node_name = nullptr);
+  inline void TrackField(const char* edge_name,
+                         const uv_timer_t& value,
+                         const char* node_name = nullptr);
+  inline void TrackField(const char* edge_name,
+                         const uv_async_t& value,
+                         const char* node_name = nullptr);
+  inline void TrackInlineField(const char* edge_name,
+                               const uv_async_t& value,
+                               const char* node_name = nullptr);
+
+  // Put a memory container into the graph, create an edge from
+  // the current node if there is one on the stack.
+  inline void Track(const CppgcMixin* retainer,
+                    const char* edge_name = nullptr);
+  inline void Track(const MemoryRetainer* retainer,
+                    const char* edge_name = nullptr);
+
+  // Useful for parents that do not wish to perform manual
+  // adjustments to its `SelfSize()` when embedding retainer
+  // objects inline.
+  // Put a memory container into the graph, create an edge from
+  // the current node if there is one on the stack - there should
+  // be one, of the container object which the current field is part of.
+  // Reduce the size of memory from the container so as to avoid
+  // duplication in accounting.
+  inline void TrackInlineField(const MemoryRetainer* retainer,
+                               const char* edge_name = nullptr);
+
+  // MemoryRetainerTraits implementation helpers.
+  template <typename T>
+  inline void TraitTrack(const T& retainer, const char* edge_name = nullptr);
+  template <typename T>
+  inline void TraitTrackInline(const T& retainer,
+                               const char* edge_name = nullptr);
+
+  inline v8::EmbedderGraph* graph() { return graph_; }
+  inline v8::Isolate* isolate() { return isolate_; }
+
+  inline explicit MemoryTracker(v8::Isolate* isolate,
+                                v8::EmbedderGraph* graph)
+    : isolate_(isolate), graph_(graph) {}
+
+  // Can be passed to Track() if it is not desirable
+  // to create a strong edge between nodes, i.e. when
+  // the node should be added to the graph and the
+  // parent node is "tracking" the target node but
+  // not directly keeping it alive.
+  static const char* const kWeakEdge;
+
+ private:
+  typedef std::unordered_map<const MemoryRetainer*, MemoryRetainerNode*>
+      NodeMap;
+
+  inline void AdjustCurrentNodeSize(int diff);
+  inline v8::EmbedderGraph::Node* CurrentNode() const;
+  inline MemoryRetainerNode* AddNode(const CppgcMixin* retainer,
+                                     const char* edge_name = nullptr);
+  inline MemoryRetainerNode* AddNode(const MemoryRetainer* retainer,
+                                     const char* edge_name = nullptr);
+  inline MemoryRetainerNode* PushNode(const CppgcMixin* retainer,
+                                      const char* edge_name = nullptr);
+  inline MemoryRetainerNode* PushNode(const MemoryRetainer* retainer,
+                                      const char* edge_name = nullptr);
+  inline MemoryRetainerNode* AddNode(const char* node_name,
+                                     size_t size,
+                                     const char* edge_name = nullptr);
+  inline MemoryRetainerNode* PushNode(const char* node_name,
+                                      size_t size,
+                                      const char* edge_name = nullptr);
+  inline void PopNode();
+  inline void AddEdge(v8::EmbedderGraph::Node* from,
+                      v8::EmbedderGraph::Node* to,
+                      const char* edge_name = nullptr);
+
+  v8::Isolate* isolate_;
+  v8::EmbedderGraph* graph_;
+  std::stack<MemoryRetainerNode*> node_stack_;
+  NodeMap seen_;
+};
+
+}  // namespace node
+
+#endif  // defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS

package/src/headers/26/module_wrap.h

@@ -0,0 +1,231 @@
+#ifndef SRC_MODULE_WRAP_H_
+#define SRC_MODULE_WRAP_H_
+
+#if defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
+
+#include <optional>
+#include <string>
+#include <unordered_map>
+#include <vector>
+#include "base_object.h"
+#include "v8-script.h"
+
+namespace node {
+
+class IsolateData;
+class Environment;
+class ExternalReferenceRegistry;
+
+namespace contextify {
+class ContextifyContext;
+}
+
+namespace loader {
+
+enum ScriptType : int {
+  kScript,
+  kModule,
+  kFunction,
+};
+
+enum HostDefinedOptions : int {
+  kID = 8,
+  kLength = 9,
+};
+
+enum ModulePhase : int {
+  kSourcePhase = 1,
+  kDeferPhase = 2,
+  kEvaluationPhase = 3,
+};
+
+/**
+ * ModuleCacheKey is used to uniquely identify a module request
+ * in the module cache. It is a composition of the module specifier
+ * and the import attributes. ModuleImportPhase is not included
+ * in the key.
+ */
+struct ModuleCacheKey : public MemoryRetainer {
+  using ImportAttributeVector =
+      std::vector<std::pair<std::string, std::string>>;
+
+  std::string specifier;
+  ImportAttributeVector import_attributes;
+  // A hash of the specifier, and import attributes.
+  // This does not guarantee uniqueness, but is used to reduce
+  // the number of comparisons needed when checking for equality.
+  std::size_t hash;
+
+  SET_MEMORY_INFO_NAME(ModuleCacheKey)
+  SET_SELF_SIZE(ModuleCacheKey)
+  void MemoryInfo(MemoryTracker* tracker) const override;
+
+  // Returns a string representation of the ModuleCacheKey.
+  std::string ToString() const;
+
+  template <int elements_per_attribute = 3>
+  static ModuleCacheKey From(v8::Local<v8::String> specifier,
+                             v8::Local<v8::FixedArray> import_attributes);
+  static ModuleCacheKey From(v8::Local<v8::ModuleRequest> v8_request);
+
+  struct Hash {
+    std::size_t operator()(const ModuleCacheKey& request) const {
+      return request.hash;
+    }
+  };
+
+  // Equality operator for ModuleCacheKey.
+  bool operator==(const ModuleCacheKey& other) const {
+    // Hash does not provide uniqueness guarantee, so ignore it.
+    return specifier == other.specifier &&
+           import_attributes == other.import_attributes;
+  }
+
+ private:
+  // Use public ModuleCacheKey::From to create instances.
+  ModuleCacheKey(std::string specifier,
+                 ImportAttributeVector import_attributes,
+                 std::size_t hash)
+      : specifier(specifier),
+        import_attributes(import_attributes),
+        hash(hash) {}
+};
+
+class ModuleWrap : public BaseObject {
+ public:
+  enum InternalFields {
+    kModuleSlot = BaseObject::kInternalFieldCount,
+    kModuleSourceObjectSlot,
+    kSyntheticEvaluationStepsSlot,
+    kContextObjectSlot,   // Object whose creation context is the target Context
+    kLinkedRequestsSlot,  // Array of linked requests, each is a ModuleWrap JS
+                          // wrapper object.
+    kInternalFieldCount
+  };
+
+  static void CreatePerIsolateProperties(IsolateData* isolate_data,
+                                         v8::Local<v8::ObjectTemplate> target);
+  static void CreatePerContextProperties(v8::Local<v8::Object> target,
+                                         v8::Local<v8::Value> unused,
+                                         v8::Local<v8::Context> context,
+                                         void* priv);
+  static void RegisterExternalReferences(ExternalReferenceRegistry* registry);
+  static void HostInitializeImportMetaObjectCallback(
+      v8::Local<v8::Context> context,
+      v8::Local<v8::Module> module,
+      v8::Local<v8::Object> meta);
+
+  v8::Local<v8::Context> context() const;
+  v8::Maybe<bool> CheckUnsettledTopLevelAwait();
+  bool HasAsyncGraph();
+
+  SET_MEMORY_INFO_NAME(ModuleWrap)
+  SET_SELF_SIZE(ModuleWrap)
+  SET_NO_MEMORY_INFO()
+
+  bool IsNotIndicativeOfMemoryLeakAtExit() const override {
+    // XXX: The garbage collection rules for ModuleWrap are *super* unclear.
+    // Do these objects ever get GC'd? Are we just okay with leaking them?
+    return true;
+  }
+
+  bool IsLinked() const { return linked_; }
+
+  static v8::Local<v8::PrimitiveArray> GetHostDefinedOptions(
+      v8::Isolate* isolate, v8::Local<v8::Symbol> symbol);
+
+  // When user_cached_data is not std::nullopt, use the code cache if it's not
+  // nullptr, otherwise don't use code cache.
+  // TODO(joyeecheung): when it is std::nullopt, use on-disk cache
+  // See: https://github.com/nodejs/node/issues/47472
+  static v8::MaybeLocal<v8::Module> CompileSourceTextModule(
+      Realm* realm,
+      v8::Local<v8::String> source_text,
+      v8::Local<v8::String> url,
+      int line_offset,
+      int column_offset,
+      v8::Local<v8::PrimitiveArray> host_defined_options,
+      std::optional<v8::ScriptCompiler::CachedData*> user_cached_data,
+      bool* cache_rejected);
+
+  static void CreateRequiredModuleFacade(
+      const v8::FunctionCallbackInfo<v8::Value>& args);
+
+ private:
+  ModuleWrap(Realm* realm,
+             v8::Local<v8::Object> object,
+             v8::Local<v8::Module> module,
+             v8::Local<v8::String> url,
+             v8::Local<v8::Object> context_object,
+             v8::Local<v8::Value> synthetic_evaluation_step);
+  ~ModuleWrap() override;
+
+  static void New(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void GetModuleRequests(
+      const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void SetModuleSourceObject(
+      const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void GetModuleSourceObject(
+      const v8::FunctionCallbackInfo<v8::Value>& args);
+
+  static void Link(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void Instantiate(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void Evaluate(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void EvaluateSync(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void GetNamespace(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void GetStatus(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void GetError(const v8::FunctionCallbackInfo<v8::Value>& args);
+
+  static void HasAsyncGraph(v8::Local<v8::Name> property,
+                            const v8::PropertyCallbackInfo<v8::Value>& args);
+
+  static void SetImportModuleDynamicallyCallback(
+      const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void SetImportMetaResolveInitializer(
+      const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void SetInitializeImportMetaObjectCallback(
+      const v8::FunctionCallbackInfo<v8::Value>& args);
+  static v8::MaybeLocal<v8::Value> SyntheticModuleEvaluationStepsCallback(
+      v8::Local<v8::Context> context, v8::Local<v8::Module> module);
+  static void SetSyntheticExport(
+      const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void CreateCachedData(const v8::FunctionCallbackInfo<v8::Value>& args);
+
+  static v8::MaybeLocal<v8::Module> ResolveModuleCallback(
+      v8::Local<v8::Context> context,
+      size_t module_request_index,
+      v8::Local<v8::Module> referrer);
+  static v8::MaybeLocal<v8::Object> ResolveSourceCallback(
+      v8::Local<v8::Context> context,
+      size_t module_request_index,
+      v8::Local<v8::Module> referrer);
+  static ModuleWrap* GetFromModule(node::Environment*, v8::Local<v8::Module>);
+
+  // This method may throw a JavaScript exception, so the return type is
+  // wrapped in a Maybe.
+  static v8::Maybe<ModuleWrap*> ResolveModule(v8::Local<v8::Context> context,
+                                              size_t module_request_index,
+                                              v8::Local<v8::Module> referrer);
+
+  std::string url_;
+  v8::Global<v8::Module> module_;
+  contextify::ContextifyContext* contextify_context_ = nullptr;
+  bool synthetic_ = false;
+  bool linked_ = false;
+  // This depends on the module to be instantiated so it begins with a
+  // nullopt value.
+  std::optional<bool> has_async_graph_ = std::nullopt;
+  int module_hash_;
+  // Corresponds to the ModuleWrap* of the wrappers in kLinkedRequestsSlot.
+  // These are populated during Link(), and are only valid after that as
+  // convenient shortcuts, but do not hold the ModuleWraps alive. The actual
+  // strong references come from the array in kLinkedRequestsSlot.
+  std::vector<ModuleWrap*> linked_module_wraps_;
+};
+
+}  // namespace loader
+}  // namespace node
+
+#endif  // defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
+
+#endif  // SRC_MODULE_WRAP_H_