| 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.
|
6405 |
| Array.h |
Array-related operations. |
4384 |
| ArrayBuffer.h |
ArrayBuffer functionality. |
12719 |
| ArrayBufferMaybeShared.h |
Functions for working with either ArrayBuffer or SharedArrayBuffer objects
in agnostic fashion.
|
3968 |
| BigInt.h |
BigInt. |
7623 |
| 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.
|
11627 |
| CallNonGenericMethod.h |
js_CallNonGenericMethod_h |
4839 |
| 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.
|
13787 |
| Class.h |
JSClass definition and its component types, plus related interfaces. |
29157 |
| 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. |
11691 |
| 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.
|
18706 |
| Context.h |
JavaScript API. |
3310 |
| ContextOptions.h |
JavaScript API. |
9065 |
| Conversions.h |
ECMAScript conversion operations. |
21020 |
| Date.h |
JavaScript date/time computation and creation functions. |
8734 |
| Debug.h |
Defined in vm/Debugger.cpp. |
14247 |
| 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.
|
16506 |
| 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 |
|
8 |
| ForOfIterator.h |
A convenience class that makes it easy to perform the operations of a for-of
loop.
|
3358 |
| friend |
|
10 |
| GCAnnotations.h |
js_GCAnnotations_h |
4630 |
| GCAPI.h |
High-level interface to the JS garbage collector.
|
45749 |
| GCHashTable.h |
|
25780 |
| GCPolicyAPI.h |
|
6802 |
| GCTypeMacros.h |
Higher-order macros enumerating public untagged and tagged GC pointer types.
|
1495 |
| GCVariant.h |
|
5576 |
| GCVector.h |
|
11543 |
| 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. |
27934 |
| HelperThreadAPI.h |
API for supplying an external thread pool to run internal work off the main
thread.
|
987 |
| Id.h |
|
10778 |
| Initialization.h |
SpiderMonkey initialization and shutdown APIs. |
6924 |
| 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 |
| JSON.h |
JSON serialization and deserialization operations.
|
3504 |
| LocaleSensitive.h |
Functions and structures related to locale-sensitive behavior, including
exposure of the default locale (used by operations like toLocaleString).
|
3862 |
| MapAndSet.h |
Weak Maps.
|
3008 |
| 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. |
3395 |
| MemoryMetrics.h |
These are the measurements used by Servo. |
29476 |
| Modules.h |
JavaScript module (as in, the syntactic construct) operations. |
8601 |
| 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|.
|
4800 |
| OffThreadScriptCompilation.h |
Types and functions related to the compilation of JavaScript off the
direct JSAPI-using thread.
|
1985 |
| Principals.h |
JSPrincipals and related interfaces. |
5160 |
| Printf.h |
Wrappers for mozilla::Smprintf and friends that are used throughout
JS. |
1212 |
| ProfilingCategory.h |
js_ProfilingCategory_h |
2381 |
| ProfilingFrameIterator.h |
|
7376 |
| 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.
|
25529 |
| PropertyAndElement.h |
Property and element API. |
22658 |
| PropertyDescriptor.h |
Property descriptors and flags. |
16314 |
| PropertySpec.h |
Property descriptors and flags. |
16467 |
| ProtoKey.h |
A higher-order macro for enumerating all JSProtoKey values. |
9371 |
| Proxy.h |
|
30353 |
| 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)(JSFreeOp* fop, 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);
/*
Ways to get various per-Realm objects. All the getters declared below operate
on the JSContext's current Realm.
|
6877 |
| 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.
|
13120 |
| RefCounted.h |
js_RefCounted_h |
2442 |
| RegExp.h |
Regular expression-related operations. |
4156 |
| RegExpFlags.h |
Regular expression flags. |
4658 |
| 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`.
## Checking Results when your return type is not Result
This header defines alternatives to MOZ_TRY and MOZ_TRY_VAR for when you
need to call a `Result` function from a function that uses false or nullptr
to indicate errors:
JS_TRY_OR_RETURN_FALSE(cx, DefenestrateObject(cx, obj));
JS_TRY_VAR_OR_RETURN_FALSE(cx, v, GetObjectThrug(cx, obj));
JS_TRY_OR_RETURN_NULL(cx, DefenestrateObject(cx, obj));
JS_TRY_VAR_OR_RETURN_NULL(cx, v, GetObjectThrug(cx, obj));
When TRY is not what you want, because you need to do some cleanup or
recovery on error, use this idiom:
if (!cx->resultToBool(expr_that_is_a_Result)) {
... your recovery code here ...
}
In place of a tail call, you can use one of these methods:
return cx->resultToBool(expr); // false on error
return cx->resultToPtr(expr); // null on error
Once we are using `Result` everywhere, including in public APIs, all of
these will go away.
## 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.
|
9454 |
| 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.
|
51198 |
| SavedFrameAPI.h |
Functions and types related to SavedFrame objects created by the Debugger
API.
|
6096 |
| ScalarType.h |
An enumeration of all possible element types in typed data. |
4811 |
| 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 |
|
7 |
| 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.
|
4354 |
| 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;
}
|
10709 |
| StableStringChars.h |
Safely access the contents of a string even as GC can cause the string's
contents to move around in memory.
|
4078 |
| 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.
|
6981 |
| Stream.h |
JSAPI functions and callbacks related to WHATWG Stream objects.
Much of the API here mirrors the standard algorithms and standard JS methods
of the objects defined in the Streams standard. One difference is that the
functionality of the JS controller object is exposed to C++ as functions
taking ReadableStream instances instead, for convenience.
|
21954 |
| 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. |
20337 |
| 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.
|
29459 |
| SweepingAPI.h |
|
3715 |
| Symbol.h |
Symbols. |
3782 |
| TelemetryTimers.h |
Timing information for telemetry purposes * |
1157 |
| TraceKind.h |
name type canBeGray inCCGraph |
9614 |
| TraceLoggerAPI.h |
SpiderMonkey TraceLogger APIs. |
7963 |
| TracingAPI.h |
Returns a static string equivalent of |kind|. |
17908 |
| Transcoding.h |
Structures and functions for transcoding compiled scripts and functions to
and from memory.
|
4285 |
| TypeDecls.h |
js_TypeDecls_h |
4693 |
| UbiNode.h |
|
45717 |
| UbiNodeBreadthFirst.h |
|
10136 |
| UbiNodeCensus.h |
|
8180 |
| 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.
|
10407 |
| UbiNodeUtils.h |
|
1239 |
| UniquePtr.h |
js_UniquePtr_h |
1547 |
| Utility.h |
The public JS engine namespace. |
22593 |
| Value.h |
JS::Value implementation. |
44702 |
| ValueArray.h |
GC-safe representations of consecutive JS::Value in memory. |
4157 |
| 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 |
8770 |
| 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.
|
1105 |
| WeakMapPtr.h |
namespace JS |
1415 |
| 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.
|
25087 |
| 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. |
3016 |