Source code
Revision control
Copy as Markdown
Other Tools
/* -*- 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
#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