summaryrefslogtreecommitdiffstats
path: root/js/public/TraceKind.h
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
commit26a029d407be480d791972afb5975cf62c9360a6 (patch)
treef435a8308119effd964b339f76abb83a57c29483 /js/public/TraceKind.h
parentInitial commit. (diff)
downloadfirefox-26a029d407be480d791972afb5975cf62c9360a6.tar.xz
firefox-26a029d407be480d791972afb5975cf62c9360a6.zip
Adding upstream version 124.0.1.upstream/124.0.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'js/public/TraceKind.h')
-rw-r--r--js/public/TraceKind.h273
1 files changed, 273 insertions, 0 deletions
diff --git a/js/public/TraceKind.h b/js/public/TraceKind.h
new file mode 100644
index 0000000000..268db56957
--- /dev/null
+++ b/js/public/TraceKind.h
@@ -0,0 +1,273 @@
+/* -*- 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_TraceKind_h
+#define js_TraceKind_h
+
+#include "mozilla/UniquePtr.h"
+
+#include "js/TypeDecls.h"
+
+// Forward declarations of all the types a TraceKind can denote.
+class JSLinearString;
+
+namespace js {
+class BaseScript;
+class BaseShape;
+class GetterSetter;
+class PropMap;
+class RegExpShared;
+class Shape;
+class Scope;
+namespace jit {
+class JitCode;
+} // namespace jit
+} // namespace js
+
+namespace JS {
+
+// When tracing a thing, the GC needs to know about the layout of the object it
+// is looking at. There are a fixed number of different layouts that the GC
+// knows about. The "trace kind" is a static map which tells which layout a GC
+// thing has.
+//
+// Although this map is public, the details are completely hidden. Not all of
+// the matching C++ types are exposed, and those that are, are opaque.
+//
+// See Value::gcKind() and JSTraceCallback in Tracer.h for more details.
+enum class TraceKind {
+ // These trace kinds have a publicly exposed, although opaque, C++ type.
+ // Note: The order here is determined by our Value packing. Other users
+ // should sort alphabetically, for consistency.
+ // Note: Nursery allocatable kinds go first. See js::gc::NurseryTraceKinds.
+ Object = 0x00,
+ BigInt = 0x01,
+ String = 0x02,
+ Symbol = 0x03,
+
+ // Shape details are exposed through JS_TraceShapeCycleCollectorChildren.
+ Shape = 0x04,
+
+ BaseShape = 0x05,
+
+ // The kind associated with a nullptr.
+ Null = 0x06,
+
+ // The following kinds do not have an exposed C++ idiom.
+ JitCode,
+ Script,
+ Scope,
+ RegExpShared,
+ GetterSetter,
+ PropMap,
+};
+
+// GCCellPtr packs the trace kind into the low bits of the pointer for common
+// kinds.
+const static uintptr_t OutOfLineTraceKindMask = 0x07;
+static_assert(uintptr_t(JS::TraceKind::Null) < OutOfLineTraceKindMask,
+ "GCCellPtr requires an inline representation for nullptr");
+
+// When this header is imported inside SpiderMonkey, the class definitions are
+// available and we can query those definitions to find the correct kind
+// directly from the class hierarchy.
+template <typename T>
+struct MapTypeToTraceKind {
+ static const JS::TraceKind kind = T::TraceKind;
+};
+
+// When this header is used outside SpiderMonkey, the class definitions are not
+// available, so the following table containing all public GC types is used.
+//
+// canBeGray: GC can mark things of this kind gray. The cycle collector
+// traverses gray GC things when looking for cycles.
+// inCCGraph: Things of this kind are represented as nodes in the CC graph. This
+// also means they can be used as a keys in WeakMap.
+
+// clang-format off
+#define JS_FOR_EACH_TRACEKIND(D) \
+ /* name type canBeGray inCCGraph */ \
+ D(BaseShape, js::BaseShape, true, false) \
+ D(JitCode, js::jit::JitCode, true, false) \
+ D(Scope, js::Scope, true, true) \
+ D(Object, JSObject, true, true) \
+ D(Script, js::BaseScript, true, true) \
+ D(Shape, js::Shape, true, false) \
+ D(String, JSString, false, false) \
+ D(Symbol, JS::Symbol, false, false) \
+ D(BigInt, JS::BigInt, false, false) \
+ D(RegExpShared, js::RegExpShared, true, true) \
+ D(GetterSetter, js::GetterSetter, true, true) \
+ D(PropMap, js::PropMap, false, false)
+// clang-format on
+
+// Returns true if the JS::TraceKind is represented as a node in cycle collector
+// graph.
+inline constexpr bool IsCCTraceKind(JS::TraceKind aKind) {
+ switch (aKind) {
+#define JS_EXPAND_DEF(name, _1, _2, inCCGraph) \
+ case JS::TraceKind::name: \
+ return inCCGraph;
+ JS_FOR_EACH_TRACEKIND(JS_EXPAND_DEF);
+#undef JS_EXPAND_DEF
+ default:
+ return false;
+ }
+}
+
+// Helper for SFINAE to ensure certain methods are only used on appropriate base
+// types. This avoids common footguns such as `Cell::is<JSFunction>()` which
+// match any type of JSObject.
+template <typename T>
+struct IsBaseTraceType : std::false_type {};
+
+#define JS_EXPAND_DEF(_, type, _1, _2) \
+ template <> \
+ struct IsBaseTraceType<type> : std::true_type {};
+JS_FOR_EACH_TRACEKIND(JS_EXPAND_DEF);
+#undef JS_EXPAND_DEF
+
+template <typename T>
+inline constexpr bool IsBaseTraceType_v = IsBaseTraceType<T>::value;
+
+// Map from all public types to their trace kind.
+#define JS_EXPAND_DEF(name, type, _, _1) \
+ template <> \
+ struct MapTypeToTraceKind<type> { \
+ static const JS::TraceKind kind = JS::TraceKind::name; \
+ };
+JS_FOR_EACH_TRACEKIND(JS_EXPAND_DEF);
+#undef JS_EXPAND_DEF
+
+template <>
+struct MapTypeToTraceKind<JSLinearString> {
+ static const JS::TraceKind kind = JS::TraceKind::String;
+};
+template <>
+struct MapTypeToTraceKind<JSFunction> {
+ static const JS::TraceKind kind = JS::TraceKind::Object;
+};
+template <>
+struct MapTypeToTraceKind<JSScript> {
+ static const JS::TraceKind kind = JS::TraceKind::Script;
+};
+
+// RootKind is closely related to TraceKind. Whereas TraceKind's indices are
+// laid out for convenient embedding as a pointer tag, the indicies of RootKind
+// are designed for use as array keys via EnumeratedArray.
+enum class RootKind : int8_t {
+// These map 1:1 with trace kinds.
+#define EXPAND_ROOT_KIND(name, _0, _1, _2) name,
+ JS_FOR_EACH_TRACEKIND(EXPAND_ROOT_KIND)
+#undef EXPAND_ROOT_KIND
+
+ // These tagged pointers are special-cased for performance.
+ Id,
+ Value,
+
+ // Everything else.
+ Traceable,
+
+ Limit
+};
+
+// Most RootKind correspond directly to a trace kind.
+template <TraceKind traceKind>
+struct MapTraceKindToRootKind {};
+#define JS_EXPAND_DEF(name, _0, _1, _2) \
+ template <> \
+ struct MapTraceKindToRootKind<JS::TraceKind::name> { \
+ static const JS::RootKind kind = JS::RootKind::name; \
+ };
+JS_FOR_EACH_TRACEKIND(JS_EXPAND_DEF)
+#undef JS_EXPAND_DEF
+
+// Specify the RootKind for all types. Value and jsid map to special cases;
+// Cell pointer types we can derive directly from the TraceKind; everything else
+// should go in the Traceable list and use GCPolicy<T>::trace for tracing.
+template <typename T>
+struct MapTypeToRootKind {
+ static const JS::RootKind kind = JS::RootKind::Traceable;
+};
+template <typename T>
+struct MapTypeToRootKind<T*> {
+ static const JS::RootKind kind =
+ JS::MapTraceKindToRootKind<JS::MapTypeToTraceKind<T>::kind>::kind;
+};
+template <>
+struct MapTypeToRootKind<JS::Realm*> {
+ // Not a pointer to a GC cell. Use GCPolicy.
+ static const JS::RootKind kind = JS::RootKind::Traceable;
+};
+template <typename T>
+struct MapTypeToRootKind<mozilla::UniquePtr<T>> {
+ static const JS::RootKind kind = JS::MapTypeToRootKind<T>::kind;
+};
+template <>
+struct MapTypeToRootKind<JS::Value> {
+ static const JS::RootKind kind = JS::RootKind::Value;
+};
+template <>
+struct MapTypeToRootKind<jsid> {
+ static const JS::RootKind kind = JS::RootKind::Id;
+};
+
+// Fortunately, few places in the system need to deal with fully abstract
+// cells. In those places that do, we generally want to move to a layout
+// templated function as soon as possible. This template wraps the upcast
+// for that dispatch.
+//
+// Given a call:
+//
+// DispatchTraceKindTyped(f, thing, traceKind, ... args)
+//
+// Downcast the |void *thing| to the specific type designated by |traceKind|,
+// and pass it to the functor |f| along with |... args|, forwarded. Pass the
+// type designated by |traceKind| as the functor's template argument. The
+// |thing| parameter is optional; without it, we simply pass through |... args|.
+template <typename F, typename... Args>
+auto DispatchTraceKindTyped(F f, JS::TraceKind traceKind, Args&&... args) {
+ switch (traceKind) {
+#define JS_EXPAND_DEF(name, type, _, _1) \
+ case JS::TraceKind::name: \
+ return f.template operator()<type>(std::forward<Args>(args)...);
+ JS_FOR_EACH_TRACEKIND(JS_EXPAND_DEF);
+#undef JS_EXPAND_DEF
+ default:
+ MOZ_CRASH("Invalid trace kind in DispatchTraceKindTyped.");
+ }
+}
+
+// Given a GC thing specified by pointer and trace kind, calls the functor |f|
+// with a template argument of the actual type of the pointer and returns the
+// result.
+template <typename F>
+auto MapGCThingTyped(void* thing, JS::TraceKind traceKind, F&& f) {
+ switch (traceKind) {
+#define JS_EXPAND_DEF(name, type, _, _1) \
+ case JS::TraceKind::name: \
+ return f(static_cast<type*>(thing));
+ JS_FOR_EACH_TRACEKIND(JS_EXPAND_DEF);
+#undef JS_EXPAND_DEF
+ default:
+ MOZ_CRASH("Invalid trace kind in MapGCThingTyped.");
+ }
+}
+
+// Given a GC thing specified by pointer and trace kind, calls the functor |f|
+// with a template argument of the actual type of the pointer and ignores the
+// result.
+template <typename F>
+void ApplyGCThingTyped(void* thing, JS::TraceKind traceKind, F&& f) {
+ // This function doesn't do anything but is supplied for symmetry with other
+ // MapGCThingTyped/ApplyGCThingTyped implementations that have to wrap the
+ // functor to return a dummy value that is ignored.
+ MapGCThingTyped(thing, traceKind, std::move(f));
+}
+
+} // namespace JS
+
+#endif // js_TraceKind_h