Adding upstream version 115.7.0esr.upstream/115.7.0esr

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 231 insertions, 0 deletions

diff --git a/js/public/UbiNodeCensus.h b/js/public/UbiNodeCensus.h
new file mode 100644
index 0000000000..4086300580
--- /dev/null
+++ b/js/public/UbiNodeCensus.h
@@ -0,0 +1,231 @@
+/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
+ * vim: set ts=8 sts=2 et sw=2 tw=80:
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+#ifndef js_UbiNodeCensus_h
+#define js_UbiNodeCensus_h
+
+#include "js/UbiNode.h"
+#include "js/UbiNodeBreadthFirst.h"
+
+// A census is a ubi::Node traversal that assigns each node to one or more
+// buckets, and returns a report with the size of each bucket.
+//
+// We summarize the results of a census with counts broken down according to
+// criteria selected by the API consumer code that is requesting the census. For
+// example, the following breakdown might give an interesting overview of the
+// heap:
+//
+//   - all nodes
+//     - objects
+//       - objects with a specific [[Class]] *
+//     - strings
+//     - scripts
+//     - DOM nodes
+//       - nsINodes with a specific name (found in nsINode::NodeName()) *
+//     - all other Node types
+//       - nodes with a specific ubi::Node::typeName *
+//
+// Obviously, the parts of this tree marked with * represent many separate
+// counts, depending on how many distinct [[Class]] values and ubi::Node type
+// names we encounter.
+//
+// The supported types of breakdowns are documented in
+// js/src/doc/Debugger/Debugger.Memory.md.
+//
+// When we parse the 'breakdown' argument to takeCensus, we build a tree of
+// CountType nodes. For example, for the breakdown shown in the
+// Debugger.Memory.prototype.takeCensus, documentation:
+//
+//    {
+//      by: "coarseType",
+//      objects: { by: "objectClass" },
+//      other:    { by: "internalType" },
+//      domNode: { by: "descriptiveType" }
+//    }
+//
+// we would build the following tree of CountType subclasses:
+//
+//    ByCoarseType
+//      objects: ByObjectClass
+//        each class: SimpleCount
+//      scripts: SimpleCount
+//      strings: SimpleCount
+//      other: ByUbinodeType
+//        each type: SimpleCount
+//      domNode: ByDomObjectClass
+//        each type: SimpleCount
+//
+// The interior nodes are all breakdown types that categorize nodes according to
+// one characteristic or another; and the leaf nodes are all SimpleType.
+//
+// Each CountType has its own concrete C++ type that holds the counts it
+// produces. SimpleCount::Count just holds totals. ByObjectClass::Count has a
+// hash table whose keys are object class names and whose values are counts of
+// some other type (in the example above, SimpleCount).
+//
+// To keep actual count nodes small, they have no vtable. Instead, each count
+// points to its CountType, which knows how to carry out all the operations we
+// need on a Count. A CountType can produce new count nodes; process nodes as we
+// visit them; build a JS object reporting the results; and destruct count
+// nodes.
+
+namespace JS {
+namespace ubi {
+
+struct Census;
+
+class CountBase;
+
+struct CountDeleter {
+  JS_PUBLIC_API void operator()(CountBase*);
+};
+
+using CountBasePtr = js::UniquePtr<CountBase, CountDeleter>;
+
+// Abstract base class for CountType nodes.
+struct CountType {
+  explicit CountType() = default;
+  virtual ~CountType() = default;
+
+  // Destruct a count tree node that this type instance constructed.
+  virtual void destructCount(CountBase& count) = 0;
+
+  // Return a fresh node for the count tree that categorizes nodes according
+  // to this type. Return a nullptr on OOM.
+  virtual CountBasePtr makeCount() = 0;
+
+  // Trace |count| and all its children, for garbage collection.
+  virtual void traceCount(CountBase& count, JSTracer* trc) = 0;
+
+  // Implement the 'count' method for counts returned by this CountType
+  // instance's 'newCount' method.
+  [[nodiscard]] virtual bool count(CountBase& count,
+                                   mozilla::MallocSizeOf mallocSizeOf,
+                                   const Node& node) = 0;
+
+  // Implement the 'report' method for counts returned by this CountType
+  // instance's 'newCount' method.
+  [[nodiscard]] virtual bool report(JSContext* cx, CountBase& count,
+                                    MutableHandleValue report) = 0;
+};
+
+using CountTypePtr = js::UniquePtr<CountType>;
+
+// An abstract base class for count tree nodes.
+class CountBase {
+  // In lieu of a vtable, each CountBase points to its type, which
+  // carries not only the implementations of the CountBase methods, but also
+  // additional parameters for the type's behavior, as specified in the
+  // breakdown argument passed to takeCensus.
+  CountType& type;
+
+ protected:
+  ~CountBase() = default;
+
+ public:
+  explicit CountBase(CountType& type)
+      : type(type), total_(0), smallestNodeIdCounted_(SIZE_MAX) {}
+
+  // Categorize and count |node| as appropriate for this count's type.
+  [[nodiscard]] bool count(mozilla::MallocSizeOf mallocSizeOf,
+                           const Node& node) {
+    total_++;
+
+    auto id = node.identifier();
+    if (id < smallestNodeIdCounted_) {
+      smallestNodeIdCounted_ = id;
+    }
+
+#ifdef DEBUG
+    size_t oldTotal = total_;
+#endif
+
+    bool ret = type.count(*this, mallocSizeOf, node);
+
+    MOZ_ASSERT(total_ == oldTotal,
+               "CountType::count should not increment total_, CountBase::count "
+               "handles that");
+
+    return ret;
+  }
+
+  // Construct a JavaScript object reporting the counts recorded in this
+  // count, and store it in |report|. Return true on success, or false on
+  // failure.
+  [[nodiscard]] bool report(JSContext* cx, MutableHandleValue report) {
+    return type.report(cx, *this, report);
+  }
+
+  // Down-cast this CountBase to its true type, based on its 'type' member,
+  // and run its destructor.
+  void destruct() { return type.destructCount(*this); }
+
+  // Trace this count for garbage collection.
+  void trace(JSTracer* trc) { type.traceCount(*this, trc); }
+
+  size_t total_;
+
+  // The smallest JS::ubi::Node::identifier() passed to this instance's
+  // count() method. This provides a stable way to sort sets.
+  Node::Id smallestNodeIdCounted_;
+};
+
+using RootedCount = JS::Rooted<CountBasePtr>;
+
+// Common data for a census traversal, shared across all CountType nodes.
+struct Census {
+  JSContext* const cx;
+  // If the targetZones set is non-empty, then only consider nodes whose zone
+  // is an element of the set. If the targetZones set is empty, then nodes in
+  // all zones are considered.
+  JS::ZoneSet targetZones;
+
+  explicit Census(JSContext* cx) : cx(cx) {}
+};
+
+// A BreadthFirst handler type that conducts a census, using a CountBase to
+// categorize and count each node.
+class CensusHandler {
+  Census& census;
+  JS::Handle<CountBasePtr> rootCount;
+  mozilla::MallocSizeOf mallocSizeOf;
+
+ public:
+  CensusHandler(Census& census, JS::Handle<CountBasePtr> rootCount,
+                mozilla::MallocSizeOf mallocSizeOf)
+      : census(census), rootCount(rootCount), mallocSizeOf(mallocSizeOf) {}
+
+  [[nodiscard]] bool report(JSContext* cx, MutableHandleValue report) {
+    return rootCount->report(cx, report);
+  }
+
+  // This class needs to retain no per-node data.
+  class NodeData {};
+
+  [[nodiscard]] JS_PUBLIC_API bool operator()(
+      BreadthFirst<CensusHandler>& traversal, Node origin, const Edge& edge,
+      NodeData* referentData, bool first);
+};
+
+using CensusTraversal = BreadthFirst<CensusHandler>;
+
+// Examine the census options supplied by the API consumer, and (among other
+// things) use that to build a CountType tree.
+[[nodiscard]] JS_PUBLIC_API bool ParseCensusOptions(JSContext* cx,
+                                                    Census& census,
+                                                    HandleObject options,
+                                                    CountTypePtr& outResult);
+
+// Parse the breakdown language (as described in
+// js/src/doc/Debugger/Debugger.Memory.md) into a CountTypePtr. A null pointer
+// is returned on error and is reported to the cx.
+JS_PUBLIC_API CountTypePtr ParseBreakdown(JSContext* cx,
+                                          HandleValue breakdownValue);
+
+}  // namespace ubi
+}  // namespace JS
+
+#endif  // js_UbiNodeCensus_h