Name Description Size
AllocationLogging.h Embedder-supplied tracking of the allocation and deallocation of various non-garbage-collected objects in SpiderMonkey. This functionality is intended to track allocation of non-user-visible structures, for debugging the C++ of an embedding. It is not intended to give the end user visibility into allocations in JS. Instead see AllocationRecording.h for such functionality. 2730
AllocationRecording.h This struct holds the information needed to create a profiler marker payload that can represent a JS allocation. It translates JS engine specific classes, into something that can be used in the profiler. 2671
AllocPolicy.h JS allocation policies. The allocators here are for system memory with lifetimes which are not managed by the GC. See the comment at the top of vm/MallocProvider.h. 9071
Array.h Array-related operations. 4384
ArrayBuffer.h ArrayBuffer functionality. 15755
ArrayBufferMaybeShared.h Functions for working with either ArrayBuffer or SharedArrayBuffer objects in agnostic fashion. 4174
BigInt.h BigInt. 7697
BuildId.h Embedding-provided build ID information, used by SpiderMonkey to tag cached compilation data so that cached data can be reused when possible, or discarded and regenerated if necessary. 2747
CallAndConstruct.h Call and construct API. 5485
CallArgs.h [SMDOC] JS::CallArgs API Helper classes encapsulating access to the callee, |this| value, arguments, and argument count for a call/construct operation. JS::CallArgs encapsulates access to a JSNative's un-abstracted |unsigned argc, Value* vp| arguments. The principal way to create a JS::CallArgs is using JS::CallArgsFromVp: // If provided no arguments or a non-numeric first argument, return zero. // Otherwise return |this| exactly as given, without boxing. static bool Func(JSContext* cx, unsigned argc, JS::Value* vp) { JS::CallArgs args = JS::CallArgsFromVp(argc, vp); // Guard against no arguments or a non-numeric arg0. if (args.length() == 0 || !args[0].isNumber()) { args.rval().setInt32(0); return true; } // Access to the callee must occur before accessing/setting // the return value. JSObject& callee = args.callee(); args.rval().setObject(callee); // callee() and calleev() will now assert. // It's always fine to access thisv(). HandleValue thisv = args.thisv(); args.rval().set(thisv); // As the return value was last set to |this|, returns |this|. return true; } CallArgs is exposed publicly and used internally. Not all parts of its public interface are meant to be used by embedders! See inline comments to for details. It's possible (albeit deprecated) to manually index into |vp| to access the callee, |this|, and arguments of a function, and to set its return value. This does not have the error-handling or moving-GC correctness of CallArgs. New code should use CallArgs instead whenever possible. The eventual plan is to change JSNative to take |const CallArgs&| directly, for automatic assertion of correct use and to make calling functions more efficient. Embedders should start internally switching away from using |argc| and |vp| directly, except to create a |CallArgs|. Then, when an eventual release making that change occurs, porting efforts will require changing methods' signatures but won't require invasive changes to the methods' implementations, potentially under time pressure. 11865
CallNonGenericMethod.h js_CallNonGenericMethod_h 4846
CharacterEncoding.h By default, all C/C++ 1-byte-per-character strings passed into the JSAPI are treated as ISO/IEC 8859-1, also known as Latin-1. That is, each byte is treated as a 2-byte character, and there is no way to pass in a string containing characters beyond U+00FF. 15277
Class.h JSClass definition and its component types, plus related interfaces. 29707
ColumnNumber.h 13161
ComparisonOperators.h Support comparison operations on wrapper types -- e.g. |JS::Rooted<T>|, |JS::Handle<T>|, and so on -- against raw |T| values, against pointers or |nullptr| if the wrapper is a pointer wrapper, and against other wrappers around compatible types. 9711
CompilationAndEvaluation.h Functions for compiling and evaluating scripts. 10127
CompileOptions.h Options for JavaScript compilation. In the most common use case, a CompileOptions instance is allocated on the stack, and holds non-owning references to non-POD option values: strings, principals, objects, and so on. The code declaring the instance guarantees that such option values will outlive the CompileOptions itself: objects are otherwise rooted, principals have had their reference counts bumped, and strings won't be freed until the CompileOptions goes out of scope. In this situation, CompileOptions only refers to things others own, so it can be lightweight. In some cases, however, we need to hold compilation options with a non-stack-like lifetime. For example, JS::CompileOffThread needs to save compilation options where a worker thread can find them, then return immediately. The worker thread will come along at some later point, and use the options. The compiler itself just needs to be able to access a collection of options; it doesn't care who owns them, or what's keeping them alive. It does its own addrefs/copies/tracing/etc. Furthermore, in some cases compile options are propagated from one entity to another (e.g. from a script to a function defined in that script). This involves copying over some, but not all, of the options. So we have a class hierarchy that reflects these four use cases: - TransitiveCompileOptions is the common base class, representing options that should get propagated from a script to functions defined in that script. This class is abstract and is only ever used as a subclass. - ReadOnlyCompileOptions is the only subclass of TransitiveCompileOptions, representing a full set of compile options. It can be used by code that simply needs to access options set elsewhere, like the compiler. This class too is abstract and is only ever used as a subclass. - The usual CompileOptions class must be stack-allocated, and holds non-owning references to the filename, element, and so on. It's derived from ReadOnlyCompileOptions, so the compiler can use it. - OwningCompileOptions roots / copies / reference counts of all its values, and unroots / frees / releases them when it is destructed. It too is derived from ReadOnlyCompileOptions, so the compiler accepts it. 30048
Context.h JavaScript API. 4336
ContextOptions.h JavaScript API. 6544
Conversions.h ECMAScript conversion operations. 21008
Date.h JavaScript date/time computation and creation functions. 9524
Debug.h Defined in vm/Debugger.cpp. 16637
Equality.h Equality operations. 2298
ErrorInterceptor.h Callback used to intercept JavaScript errors. 1526
ErrorReport.h Error-reporting APIs. Despite the types and structures defined here existing in js/public, significant parts of their heritage date back to distant SpiderMonkey past, and they are not all universally well-thought-out as ideal, intended-to-be-permanent API. We may eventually replace this with something more consistent with ECMAScript the language and less consistent with '90s-era JSAPI inventions, but it's doubtful this will happen any time soon. 19842
Exception.h If the given object is an exception object, the exception will have (or be able to lazily create) an error report struct, and this function will return the address of that struct. Otherwise, it returns nullptr. The lifetime of the error report struct that might be returned is the same as the lifetime of the exception object. 6553
experimental
ForOfIterator.h A convenience class that makes it easy to perform the operations of a for-of loop. 3358
friend
GCAnnotations.h js_GCAnnotations_h 4947
GCAPI.h High-level interface to the JS garbage collector. 49920
GCHashTable.h 26939
GCPolicyAPI.h 10351
GCTypeMacros.h Higher-order macros enumerating public untagged and tagged GC pointer types. 1494
GCVariant.h 5576
GCVector.h 12128
GlobalObject.h Get the current realm's global. Returns nullptr if no realm has been entered. 3983
HashTable.h js_HashTable_h 1171
HeapAPI.h These values are private to the JS engine. 31110
HelperThreadAPI.h API for supplying an external thread pool to run internal work off the main thread. 1285
Id.h 12445
Initialization.h SpiderMonkey initialization and shutdown APIs. 7970
Interrupt.h These functions allow setting an interrupt callback that will be called from the JS thread some time after any thread triggered the callback using JS_RequestInterruptCallback(cx). To schedule the GC and for other activities the engine internally triggers interrupt callbacks. The embedding should thus not rely on callbacks being triggered through the external API only. Important note: Additional callbacks can occur inside the callback handler if it re-enters the JS engine. The embedding must ensure that the callback is disconnected before attempting such re-entry. 1588
Iterator.h js_Iterator_h 1386
JitCodeAPI.h SpiderMonkey API for obtaining JitCode information. 2501
JSON.h JSON serialization and deserialization operations. 7092
LocaleSensitive.h Functions and structures related to locale-sensitive behavior, including exposure of the default locale (used by operations like toLocaleString). 3862
MapAndSet.h Maps and Sets. 3012
MemoryCallbacks.h If a large allocation fails when calling pod_{calloc,realloc}CanGC, the JS engine may call the large-allocation-failure callback, if set, to allow the embedding to flush caches, possibly perform shrinking GCs, etc. to make some room. The allocation will then be retried (and may still fail.) This callback can be called on any thread and must be set at most once in a process. 1905
MemoryFunctions.h Low-level memory-allocation functions. 3148
MemoryMetrics.h These are the measurements used by Servo. 29346
Modules.h JavaScript module (as in, the syntactic construct) operations. 11966
Object.h Determine the ECMAScript "class" -- Date, String, RegExp, and all the other builtin object types (described in ECMAScript in terms of an objecting having "an [[ArrayBufferData]] internal slot" or similar language for other kinds of object -- of the provided object. If this function is passed a wrapper that can be unwrapped, the determination is performed on that object. If the wrapper can't be unwrapped, and it's not a wrapper that prefers to treat this operation as a failure, this function will indicate that the object is |js::ESClass::Other|. 5143
Prefs.h Specification for whether weak refs should be enabled and if so whether the FinalizationRegistry.cleanupSome method should be present. 4581
Principals.h JSPrincipals and related interfaces. 5472
Printer.h 20337
Printf.h Wrappers for mozilla::Smprintf and friends that are used throughout JS. 1212
ProfilingCategory.h js_ProfilingCategory_h 2381
ProfilingFrameIterator.h 9497
ProfilingStack.h 22498
Promise.h Abstract base class for an ECMAScript Job Queue: https://www.ecma-international.org/ecma-262/9.0/index.html#sec-jobs-and-job-queues SpiderMonkey doesn't schedule Promise resolution jobs itself; instead, the embedding can provide an instance of this class SpiderMonkey can use to do that scheduling. The JavaScript shell includes a simple implementation adequate for running tests. Browsers need to augment job handling to meet their own additional requirements, so they can provide their own implementation. 25981
PropertyAndElement.h Property and element API. 22581
PropertyDescriptor.h Property descriptors and flags. 16458
PropertySpec.h Property descriptors and flags. 17023
ProtoKey.h A higher-order macro for enumerating all JSProtoKey values. 10634
Proxy.h 31458
Realm.h / // [SMDOC] Realms // // Data associated with a global object. In the browser each frame has its // own global/realm. namespace js { namespace gc { JS_PUBLIC_API void TraceRealm(JSTracer* trc, JS::Realm* realm, const char* name); } // namespace gc } // namespace js namespace JS { class JS_PUBLIC_API AutoRequireNoGC; // Each Realm holds a weak reference to its GlobalObject. template <> struct GCPolicy<Realm*> : public NonGCPointerPolicy<Realm*> { static void trace(JSTracer* trc, Realm** vp, const char* name) { if (*vp) { ::js::gc::TraceRealm(trc, *vp, name); } } }; // Get the current realm, if any. The ECMAScript spec calls this "the current // Realm Record". extern JS_PUBLIC_API Realm* GetCurrentRealmOrNull(JSContext* cx); // Return the compartment that contains a given realm. inline JS::Compartment* GetCompartmentForRealm(Realm* realm) { return shadow::Realm::get(realm)->compartment(); } // Return an object's realm. All objects except cross-compartment wrappers are // created in a particular realm, which never changes. Returns null if obj is // a cross-compartment wrapper. extern JS_PUBLIC_API Realm* GetObjectRealmOrNull(JSObject* obj); // Get the value of the "private data" internal field of the given Realm. // This field is initially null and is set using SetRealmPrivate. // It's a pointer to embeddding-specific data that SpiderMonkey never uses. extern JS_PUBLIC_API void* GetRealmPrivate(Realm* realm); // Set the "private data" internal field of the given Realm. extern JS_PUBLIC_API void SetRealmPrivate(Realm* realm, void* data); typedef void (*DestroyRealmCallback)(JS::GCContext* gcx, Realm* realm); // Set the callback SpiderMonkey calls just before garbage-collecting a realm. // Embeddings can use this callback to free private data associated with the // realm via SetRealmPrivate. // // By the time this is called, the global object for the realm has already been // collected. extern JS_PUBLIC_API void SetDestroyRealmCallback( JSContext* cx, DestroyRealmCallback callback); using RealmNameCallback = void (*)(JSContext* cx, Realm* realm, char* buf, size_t bufsize, const JS::AutoRequireNoGC& nogc); // Set the callback SpiderMonkey calls to get the name of a realm, for // diagnostic output. extern JS_PUBLIC_API void SetRealmNameCallback(JSContext* cx, RealmNameCallback callback); // Get the global object for the given realm. This only returns nullptr during // GC, between collecting the global object and destroying the Realm. extern JS_PUBLIC_API JSObject* GetRealmGlobalOrNull(Realm* realm); // Initialize standard JS class constructors, prototypes, and any top-level // functions and constants associated with the standard classes (e.g. isNaN // for Number). extern JS_PUBLIC_API bool InitRealmStandardClasses(JSContext* cx); // If the current realm has the non-standard freezeBuiltins option set to true, // freeze the constructor object and seal the prototype. extern JS_PUBLIC_API bool MaybeFreezeCtorAndPrototype(JSContext* cx, HandleObject ctor, HandleObject maybeProto); /* Ways to get various per-Realm objects. All the getters declared below operate on the JSContext's current Realm. 7794
RealmIterators.h Various interfaces to iterate over the Realms given various context such as principals, compartments and GC zones. 2893
RealmOptions.h Options specified when creating a realm to determine its behavior, immutable options determining the behavior of an existing realm, and mutable options on an existing realm that may be changed when desired. 12637
RefCounted.h js_RefCounted_h 2279
RegExp.h Regular expression-related operations. 4156
RegExpFlags.h Regular expression flags. 5857
Result.h [SMDOC] JS::Result `Result` is used as the return type of many SpiderMonkey functions that can either succeed or fail. See "/mfbt/Result.h". ## Which return type to use `Result` is for return values. Obviously, if you're writing a function that can't fail, don't use Result. Otherwise: JS::Result<> - function can fail, doesn't return anything on success (defaults to `JS::Result<JS::Ok, JS::Error>`) JS::Result<JS::Ok, JS::OOM> - like JS::Result<>, but fails only on OOM JS::Result<Data> - function can fail, returns Data on success JS::Result<Data, JS::OOM> - returns Data, fails only on OOM mozilla::GenericErrorResult<JS::Error> - always fails That last type is like a Result with no success type. It's used for functions like `js::ReportNotFunction` that always return an error result. `GenericErrorResult<E>` implicitly converts to `Result<V, E>`, regardless of V. ## Checking Results when your return type is Result When you call a function that returns a `Result`, use the `MOZ_TRY` macro to check for errors: MOZ_TRY(DefenestrateObject(cx, obj)); If `DefenestrateObject` returns a success result, `MOZ_TRY` is done, and control flows to the next statement. If `DefenestrateObject` returns an error result, `MOZ_TRY` will immediately return it, propagating the error to your caller. It's kind of like exceptions, but more explicit -- you can see in the code exactly where errors can happen. You can do a tail call instead of using `MOZ_TRY`: return DefenestrateObject(cx, obj); Indicate success with `return Ok();`. If the function returns a value on success, use `MOZ_TRY_VAR` to get it: RootedValue thrug(cx); MOZ_TRY_VAR(thrug, GetObjectThrug(cx, obj)); This behaves the same as `MOZ_TRY` on error. On success, the success value of `GetObjectThrug(cx, obj)` is assigned to the variable `thrug`. ## GC safety When a function returns a `JS::Result<JSObject*>`, it is the program's responsibility to check for errors and root the object before continuing: RootedObject wrapper(cx); MOZ_TRY_VAR(wrapper, Enwrapify(cx, thing)); This is ideal. On error, there is no object to root; on success, the assignment to wrapper roots it. GC safety is ensured. `Result` has methods .isOk(), .isErr(), .unwrap(), and .unwrapErr(), but if you're actually using them, it's possible to create a GC hazard. The static analysis will catch it if so, but that's hardly convenient. So try to stick to the idioms shown above. ## Future directions At present, JS::Error and JS::OOM are empty structs. The plan is to make them GC things that contain the actual error information (including the exception value and a saved stack). The long-term plan is to remove JS_IsExceptionPending and JS_GetPendingException in favor of JS::Error. Exception state will no longer exist. 6179
RootingAPI.h [SMDOC] Stack Rooting Moving GC Stack Rooting A moving GC may change the physical location of GC allocated things, even when they are rooted, updating all pointers to the thing to refer to its new location. The GC must therefore know about all live pointers to a thing, not just one of them, in order to behave correctly. The |Rooted| and |Handle| classes below are used to root stack locations whose value may be held live across a call that can trigger GC. For a code fragment such as: JSObject* obj = NewObject(cx); DoSomething(cx); ... = obj->lastProperty(); If |DoSomething()| can trigger a GC, the stack location of |obj| must be rooted to ensure that the GC does not move the JSObject referred to by |obj| without updating |obj|'s location itself. This rooting must happen regardless of whether there are other roots which ensure that the object itself will not be collected. If |DoSomething()| cannot trigger a GC, and the same holds for all other calls made between |obj|'s definitions and its last uses, then no rooting is required. SpiderMonkey can trigger a GC at almost any time and in ways that are not always clear. For example, the following innocuous-looking actions can cause a GC: allocation of any new GC thing; JSObject::hasProperty; JS_ReportError and friends; and ToNumber, among many others. The following dangerous-looking actions cannot trigger a GC: js_malloc, cx->malloc_, rt->malloc_, and friends and JS_ReportOutOfMemory. The following family of three classes will exactly root a stack location. Incorrect usage of these classes will result in a compile error in almost all cases. Therefore, it is very hard to be incorrectly rooted if you use these classes exclusively. These classes are all templated on the type T of the value being rooted. - Rooted<T> declares a variable of type T, whose value is always rooted. Rooted<T> may be automatically coerced to a Handle<T>, below. Rooted<T> should be used whenever a local variable's value may be held live across a call which can trigger a GC. - Handle<T> is a const reference to a Rooted<T>. Functions which take GC things or values as arguments and need to root those arguments should generally use handles for those arguments and avoid any explicit rooting. This has two benefits. First, when several such functions call each other then redundant rooting of multiple copies of the GC thing can be avoided. Second, if the caller does not pass a rooted value a compile error will be generated, which is quicker and easier to fix than when relying on a separate rooting analysis. - MutableHandle<T> is a non-const reference to Rooted<T>. It is used in the same way as Handle<T> and includes a |set(const T& v)| method to allow updating the value of the referenced Rooted<T>. A MutableHandle<T> can be created with an implicit cast from a Rooted<T>*. In some cases the small performance overhead of exact rooting (measured to be a few nanoseconds on desktop) is too much. In these cases, try the following: - Move all Rooted<T> above inner loops: this allows you to re-use the root on each iteration of the loop. - Pass Handle<T> through your hot call stack to avoid re-rooting costs at every invocation. The following diagram explains the list of supported, implicit type conversions between classes of this family: Rooted<T> ----> Handle<T> | ^ | | | | +---> MutableHandle<T> (via &) All of these types have an implicit conversion to raw pointers. 55807
SavedFrameAPI.h Functions and types related to SavedFrame objects created by the Debugger API. 6198
ScalarType.h An enumeration of all possible element types in typed data. 4975
ScriptPrivate.h Set a private value associated with a script. Note that this value is shared by all nested scripts compiled from a single source file. 1676
shadow
ShadowRealmCallbacks.h 1927
SharedArrayBuffer.h ArrayBuffer functionality. 2812
SliceBudget.h This class describes a limit to the amount of work to be performed in a GC slice, so that we can return to the mutator without pausing for too long. The budget may be based on a deadline time or an amount of work to be performed, or may be unlimited. To reduce the number of gettimeofday calls, we only check the time every 1000 operations. 4689
SourceText.h SourceText encapsulates a count of char16_t (UTF-16) or Utf8Unit (UTF-8) code units (note: code *units*, not bytes or code points) and those code units ("source units"). (Latin-1 is not supported: all places where Latin-1 must be compiled first convert to a supported encoding.) A SourceText either observes without owning, or takes ownership of, source units passed to |SourceText::init|. Thus SourceText can be used to efficiently avoid copying. Rules for use: 1) The passed-in source units must be allocated with js_malloc(), js_calloc(), or js_realloc() if |SourceText::init| is instructed to take ownership of the source units. 2) If |SourceText::init| merely borrows the source units, the user must keep them alive until associated JS compilation is complete. 3) Code that calls |SourceText::take{Chars,Units}()| must keep the source units alive until JS compilation completes. Normally only the JS engine should call |SourceText::take{Chars,Units}()|. 4) Use the appropriate SourceText parameterization depending on the source units encoding. Example use: size_t length = 512; char16_t* chars = js_pod_malloc<char16_t>(length); if (!chars) { JS_ReportOutOfMemory(cx); return false; } JS::SourceText<char16_t> srcBuf; if (!srcBuf.init(cx, chars, length, JS::SourceOwnership::TakeOwnership)) { return false; } JS::Rooted<JSScript*> script(cx); if (!JS::Compile(cx, options, srcBuf, &script)) { return false; } 13555
StableStringChars.h Safely access the contents of a string even as GC can cause the string's contents to move around in memory. 4278
Stack.h Set the size of the native stack that should not be exceed. To disable stack size checking pass 0. SpiderMonkey allows for a distinction between system code (such as GCs, which may incidentally be triggered by script but are not strictly performed on behalf of such script), trusted script (as determined by JS_SetTrustedPrincipals), and untrusted script. Each kind of code may have a different stack quota, allowing embedders to keep higher-priority machinery running in the face of scripted stack exhaustion by something else. The stack quotas for each kind of code should be monotonically descending, and may be specified with this function. If 0 is passed for a given kind of code, it defaults to the value of the next-highest-priority kind. This function may only be called immediately after the runtime is initialized and before any code is executed and/or interrupts requested. 8246
StreamConsumer.h The ConsumeStreamCallback is called from an active JSContext, passing a StreamConsumer that wishes to consume the given host object as a stream of bytes with the given MIME type. On failure, the embedding must report the appropriate error on 'cx'. On success, the embedding must call consumer->consumeChunk() repeatedly on any thread until exactly one of: - consumeChunk() returns false - the embedding calls consumer->streamEnd() - the embedding calls consumer->streamError() before JS_DestroyContext(cx) or JS::ShutdownAsyncTasks(cx) is called. Note: consumeChunk(), streamEnd() and streamError() may be called synchronously by ConsumeStreamCallback. When streamEnd() is called, the embedding may optionally pass an OptimizedEncodingListener*, indicating that there is a cache entry associated with this stream that can store an optimized encoding of the bytes that were just streamed at some point in the future by having SpiderMonkey call storeOptimizedEncoding(). Until the optimized encoding is ready, SpiderMonkey will hold an outstanding refcount to keep the listener alive. After storeOptimizedEncoding() is called, on cache hit, the embedding may call consumeOptimizedEncoding() instead of consumeChunk()/streamEnd(). The embedding must ensure that the GetOptimizedEncodingBuildId() (see js/BuildId.h) at the time when an optimized encoding is created is the same as when it is later consumed. 4655
String.h JavaScript string operations. 24850
StructuredClone.h API for safe passing of structured data, HTML 2018 Feb 21 section 2.7. <https://html.spec.whatwg.org/multipage/structured-data.html> This is a serialization scheme for JS values, somewhat like JSON. It preserves some aspects of JS objects (strings, numbers, own data properties with string keys, array elements) but not others (methods, getters and setters, prototype chains). Unlike JSON, structured data: - can contain cyclic references. - handles Maps, Sets, and some other object types. - supports *transferring* objects of certain types from one realm to another, rather than cloning them. - is specified by a living standard, and continues to evolve. - is encoded in a nonstandard binary format, and is never exposed to Web content in its serialized form. It's used internally by the browser to send data from one thread/realm/domain to another, not across the network. 31340
SweepingAPI.h 3806
Symbol.h Symbols. 3988
TelemetryTimers.h Timing information for telemetry purposes * 1157
TraceKind.h name type canBeGray inCCGraph 9692
TracingAPI.h Returns a static string equivalent of |kind|. 14544
Transcoding.h Structures and functions for transcoding compiled scripts and functions to and from memory. 5622
TypeDecls.h 5379
UbiNode.h 45885
UbiNodeBreadthFirst.h 10136
UbiNodeCensus.h 8155
UbiNodeDominatorTree.h In a directed graph with a root node `R`, a node `A` is said to "dominate" a node `B` iff every path from `R` to `B` contains `A`. A node `A` is said to be the "immediate dominator" of a node `B` iff it dominates `B`, is not `B` itself, and does not dominate any other nodes which also dominate `B` in turn. If we take every node from a graph `G` and create a new graph `T` with edges to each node from its immediate dominator, then `T` is a tree (each node has only one immediate dominator, or none if it is the root). This tree is called a "dominator tree". This class represents a dominator tree constructed from a `JS::ubi::Node` heap graph. The domination relationship and dominator trees are useful tools for analyzing heap graphs because they tell you: - Exactly what could be reclaimed by the GC if some node `A` became unreachable: those nodes which are dominated by `A`, - The "retained size" of a node in the heap graph, in contrast to its "shallow size". The "shallow size" is the space taken by a node itself, not counting anything it references. The "retained size" of a node is its shallow size plus the size of all the things that would be collected if the original node wasn't (directly or indirectly) referencing them. In other words, the retained size is the shallow size of a node plus the shallow sizes of every other node it dominates. For example, the root node in a binary tree might have a small shallow size that does not take up much space itself, but it dominates the rest of the binary tree and its retained size is therefore significant (assuming no external references into the tree). The simple, engineered algorithm presented in "A Simple, Fast Dominance Algorithm" by Cooper el al[0] is used to find dominators and construct the dominator tree. This algorithm runs in O(n^2) time, but is faster in practice than alternative algorithms with better theoretical running times, such as Lengauer-Tarjan which runs in O(e * log(n)). The big caveat to that statement is that Cooper et al found it is faster in practice *on control flow graphs* and I'm not convinced that this property also holds on *heap* graphs. That said, the implementation of this algorithm is *much* simpler than Lengauer-Tarjan and has been found to be fast enough at least for the time being. [0]: http://www.cs.rice.edu/~keith/EMBED/dom.pdf 24214
UbiNodePostOrder.h A post-order depth-first traversal of `ubi::Node` graphs. No GC may occur while an instance of `PostOrder` is live. The `NodeVisitor` type provided to `PostOrder::traverse` must have the following member: bool operator()(Node& node) The node visitor method. This method is called once for each `node` reachable from the start set in post-order. This visitor function should return true on success, or false if an error occurs. A false return value terminates the traversal immediately, and causes `PostOrder::traverse` to return false. The `EdgeVisitor` type provided to `PostOrder::traverse` must have the following member: bool operator()(Node& origin, Edge& edge) The edge visitor method. This method is called once for each outgoing `edge` from `origin` that is reachable from the start set. NB: UNLIKE NODES, THERE IS NO GUARANTEED ORDER IN WHICH EDGES AND THEIR ORIGINS ARE VISITED! This visitor function should return true on success, or false if an error occurs. A false return value terminates the traversal immediately, and causes `PostOrder::traverse` to return false. 5477
UbiNodeShortestPaths.h A back edge along a path in the heap graph. 10577
UbiNodeUtils.h 1239
UniquePtr.h js_UniquePtr_h 1547
Utility.h The public JS engine namespace. 24486
Value.h JS::Value implementation. 51598
ValueArray.h GC-safe representations of consecutive JS::Value in memory. 4298
Vector.h js_Vector_h 1037
WaitCallbacks.h When the JSRuntime is about to block in an Atomics.wait() JS call or in a `wait` instruction in WebAssembly, it can notify the host by means of a call to BeforeWaitCallback. After the wait, it can notify the host by means of a call to AfterWaitCallback. Both callbacks must be null, or neither. (If you change the callbacks from null to not-null or vice versa while some thread on the runtime is in a wait, you will be sorry.) The argument to the BeforeWaitCallback is a pointer to uninitialized stack-allocated working memory of size WAIT_CALLBACK_CLIENT_MAXMEM bytes. The caller of SetWaitCallback() must pass the amount of memory it will need, and this amount will be checked against that limit and the process will crash reliably if the check fails. The value returned by the BeforeWaitCallback will be passed to the AfterWaitCallback. The AfterWaitCallback will be called even if the wakeup is spurious and the thread goes right back to waiting again. Of course the thread will call the BeforeWaitCallback once more before it goes to sleep in this situation. 2107
Warnings.h Functionality for issuing and handling warnings. Warnings are situations that aren't inherently full-blown errors (and perhaps for spec compliance *can't* be), but that may represent dubious programming practice that embeddings may wish to know about. SpiderMonkey recognizes an unspecified set of syntactic patterns and runtime behaviors as triggering a warning. Embeddings may also recognize and report additional warnings. 3230
WasmFeatures.h capitalized name 11802
WasmModule.h The WasmModule interface allows the embedding to hold a reference to the underying C++ implementation of a JS WebAssembly.Module object for purposes of efficient postMessage() and (de)serialization from a random thread. In particular, this allows postMessage() of a WebAssembly.Module: GetWasmModule() is called when making a structured clone of a payload containing a WebAssembly.Module object. The structured clone buffer holds a refcount of the JS::WasmModule until createObject() is called in the target agent's JSContext. The new WebAssembly.Module object continues to hold the JS::WasmModule and thus the final reference of a JS::WasmModule may be dropped from any thread and so the virtual destructor (and all internal methods of the C++ module) must be thread-safe. 1786
WeakMap.h Weak Maps. 1103
WeakMapPtr.h namespace JS 1443
Wrapper.h Helper for Wrapper::New default options. Callers of Wrapper::New() who wish to specify a prototype for the created Wrapper, *MUST* construct a WrapperOptions with a JSContext. 24754
WrapperCallbacks.h Callback used to ask the embedding for the cross compartment wrapper handler that implements the desired prolicy for this kind of object in the destination compartment. |obj| is the object to be wrapped. If |existing| is non-nullptr, it will point to an existing wrapper object that should be re-used if possible. |existing| is guaranteed to be a cross-compartment wrapper with a lazily-defined prototype and the correct global. It is guaranteed not to wrap a function. 1722
Zone.h JavaScript API. 3273