Assert that code is only ever called from a GC callback, disable the static
rooting hazard analysis and assert if any allocation that could potentially
trigger a GC occurs while this guard object is live.
Diagnostic assert (see MOZ_DIAGNOSTIC_ASSERT) that GC cannot occur while this
class is live. This class does not disable the static rooting hazard
analysis.
Pass a subclass of this “abstract” class to callees to require that they
never GC. Subclasses can use assertions or the hazard analysis to ensure no
GC happens.
Save and later restore the current exception state of a given JSContext.
This is useful for implementing behavior in C++ that’s like try/catch
or try/finally in JS.
Supply an alternative stack to incorporate into captured SavedFrame
backtraces as the imputed caller of asynchronous JavaScript calls, like async
function resumptions and DOM callbacks.
Compilation options stored on the stack. An instance of this type
simply holds references to dynamically allocated resources (element;
filename; source map URL) that are owned by something else. If you
create an instance of this type, it’s up to you to guarantee that
everything you store in it will outlive it.
Capture the first frame with the given principals. By default, do not
consider self-hosted frames with the given principals as satisfying the stack
capture.
Reference to a T that has been rooted elsewhere. This is most useful
as a parameter type, which guarantees that the T lvalue is properly
rooted. See “Move GC Stack Rooting” above.
A saved job queue, represented however the JobQueue implementation pleases.
Use AutoDebuggerJobQueueInterruption rather than trying to construct one of
these directly; see documentation there.
Holds data about a notable class (one whose combined object and shape
instances use more than a certain amount of memory) so we can report it
individually.
Holds data about a notable script source file (one whose combined
script sources use more than a certain amount of memory) so we can report it
individually.
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:
Compilation options, with dynamic lifetime. An instance of this type
makes a copy of / holds / roots all dynamically allocated resources
(principals; elements; strings) that it refers to. Its destructor frees
/ drops / unroots them. This is heavier than CompileOptions, below, but
unlike CompileOptions, it can outlive any given stack frame.
A structure that represents a property on an object, or the absence of a
property. Use {,Mutable}Handle to interact with
instances of this structure rather than interacting directly with member
fields.
RealmCreationOptions specifies options relevant to creating a new realm, that
are either immutable characteristics of that realm or that are discarded
after the realm has been created.
RealmOptions specifies realm characteristics: both those that can’t be
changed on a realm once it’s been created (RealmCreationOptions), and those
that can be changed on an existing realm (RealmBehaviors).
Regular expression flag values, suitable for initializing a collection of
regular expression flags as defined below in |RegExpFlags|. Flags are listed
in alphabetical order by syntax – /d, /g, /i, /m, /s, /u, /v, /y.
SafelyInitialized::create() creates a safely-initialized |T|, suitable for
use as a default value in situations requiring a safe but arbitrary |T|
value. Implemented as a static method of a struct to allow partial
specialization for subclasses via the Enable template parameter.
This class holds information about the memory taken up by identical copies of
a particular string. Multiple JSStrings may have their sizes aggregated
together into one StringInfo object. Note that two strings with identical
chars will not be aggregated together if one is a short string and the other
is not.
The TenuredHeap class is similar to the Heap class above in that it
encapsulates the GC concerns of an on-heap reference to a JS object. However,
it has two important differences:
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.
During global creation, we fire notifications to callbacks registered
via the Debugger API. These callbacks are arbitrary script, and can touch
the global in arbitrary ways. When that happens, the global should not be
in a half-baked state. But this creates a problem for consumers that need
to set slots on the global to put it in a consistent state.
If IsIncrementalGCInProgress(cx), this call aborts the ongoing collection and
performs whatever work needs to be done to return the collector to its idle
state. This may take an arbitrarily long time. When this function returns,
IsIncrementalGCInProgress(cx) will always be false.
Advise the GC of external memory owned by a JSObject. This is used to
determine when to collect zones. Calls must be matched by calls to
RemoveAssociatedMemory() when the memory is deallocated or no longer owned by
the object.
Convert the given BigInt to a Number value as if calling the Number
constructor on it
(https://tc39.es/ecma262/#sec-number-constructor-number-value). The value
may be rounded if it doesn’t fit without loss of precision.
Given a SavedFrame JSObject stack, stringify it in the same format as
Error.prototype.stack. The stringified stack out parameter is placed in the
cx’s compartment. Defaults to the empty string.
Create a Promise with the given fulfill/reject handlers, that will be
fulfilled/rejected with the value/reason that the promise promise is
fulfilled/rejected with.
Capture the current call stack as a chain of SavedFrame JSObjects, and set
|stackp| to the SavedFrame for the youngest stack frame, or nullptr if there
are no JS frames on the stack.
Check whether the given source is a valid regexp. If the regexp parses
successfully, returns true and sets |error| to undefined. If the regexp
has a syntax error, returns true, sets |error| to that error object, and
clears the exception. Returns false on OOM or over-recursion.
Compile a function with envChain plus the global as its scope chain.
envChain must contain objects in the current compartment of cx. The actual
scope chain used for the function will consist of With wrappers for those
objects, followed by the current global of the compartment cx is in. This
global must not be explicitly included in the scope chain.
Compile a function with envChain plus the global as its scope chain.
envChain must contain objects in the current compartment of cx. The actual
scope chain used for the function will consist of With wrappers for those
objects, followed by the current global of the compartment cx is in. This
global must not be explicitly included in the scope chain.
Parse the given source buffer as a JSON module in the scope of the current
global of cx and return a synthetic module record. An error is reported if a
UTF-8 encoding error is encountered.
Parse the given source buffer as a module in the scope of the current global
of cx and return a source text module record. An error is reported if a
UTF-8 encoding error is encountered.
Compile the UTF-8 contents of the given file into a script. It is an error
if the file contains invalid UTF-8. Return the script on success, or return
null on failure (usually with an error reported).
Compile the UTF-8 contents of the file at the given path into a script.
(The path itself is in the system encoding, not [necessarily] UTF-8.) It
is an error if the file’s contents are invalid UTF-8. Return the script on
success, or return null on failure (usually with an error reported).
Returns true if there are any live SharedArrayBuffer objects, including those
for wasm memories, associated with the context. This is conservative,
because it does not run GC. Some dead objects may not have been collected
yet and thus will be thought live.
Given a SavedFrame object, convert it and its transitive parents to plain
objects. Because SavedFrame objects store their properties on the prototype,
they cannot be usefully stringified to JSON. Assigning their properties to
plain objects allow those objects to be stringified and the saved frame stack
can be encoded as a string.
Attempt to disable Wasm’s usage of reserving a large virtual memory
allocation to avoid bounds checking overhead. This must be called before any
Wasm module or memory is created in this process, or else this function will
fail.
As above, but providing an explicit scope chain. envChain must not include
the global object on it; that’s implicit. It needs to contain the other
objects that should end up on the script’s scope chain.
Evaluate the provided UTF-8 data in the scope of the current global of |cx|,
and return the completion value in |rval|. If the data contains invalid
UTF-8, an error is reported.
Evaluate the UTF-8 contents of the file at the given path, and return the
completion value in |rval|. (The path itself is UTF-8 encoded, too.) If
the contents contain any malformed UTF-8, an error is reported.
If the given object is an exception object (or an unwrappable
cross-compartment wrapper for one), return the stack for that exception, if
any. Will return null if the given object is not an exception object
(including if it’s null or a security wrapper that can’t be unwrapped) or if
the exception has no stack.
Execute a regexp on a given input, starting from |indexp|.
This is the same as ExecuteRegExp, except it does not update the RegExp
statics and can be called without a global object.
If IsIncrementalGCInProgress(cx), this call finishes the ongoing collection
by performing an arbitrarily long slice. If !IsIncrementalGCInProgress(cx),
this is equivalent to NonIncrementalGC. When this function returns,
IsIncrementalGCInProgress(cx) will always be false.
Return a pointer to the start of the data referenced by a typed array. The
data is still owned by the typed array, and should not be modified on
another thread. Furthermore, the pointer can become invalid on GC (if the
data is small and fits inside the array’s GC header), so callers must take
care not to hold on across anything that could GC.
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 args.get(0) is one of the strings “string”, “number”, or “default”, set
result to JSTYPE_STRING, JSTYPE_NUMBER, or JSTYPE_UNDEFINED accordingly and
return true. Otherwise, return false with a TypeError pending.
Get the global object associated with an object’s realm. The object must not
be a cross-compartment wrapper (because CCWs are shared by all realms in the
compartment).
Returns the given Promise’s activation behavior state flag per above as a
JS::PromiseUserInputEventHandlingState value. All promises are created with
the DontCare state by default.
Given a SavedFrame JSObject, get its asyncParent SavedFrame object or nullptr
if there is no asyncParent. The asyncParentp out parameter is NOT
guaranteed to be in the cx’s compartment. Defaults to nullptr.
Given a SavedFrame JSObject, get its functionDisplayName string, or nullptr
if SpiderMonkey was unable to infer a name for the captured frame’s
function. Defaults to nullptr.
Given a SavedFrame JSObject, get its parent SavedFrame object or nullptr if
it is the oldest frame in the stack. The parentp out parameter is NOT
guaranteed to be in the cx’s compartment. Defaults to nullptr.
Informs the JS engine that the scripted caller should be hidden. This can be
used by the embedding to maintain an override of the scripted caller in its
calculations, by hiding the scripted caller in the JS engine and pushing data
onto a separate stack, which it inspects when DescribeScriptedCaller returns
null.
Return whether an incremental GC has work to do on the foreground thread and
would make progress if a slice was run now. If this returns false then the GC
is waiting for background threads to finish their work and a slice started
now would return immediately.
Perform a slice of an ongoing incremental collection. When this function
returns, the collection may not be complete. It must be called repeatedly
until !IsIncrementalGCInProgress(cx).
Identical to IsArray above, but the nature of the object (if successfully
determined) is communicated via |*answer|. In particular this method
returns true and sets |*answer = IsArrayAnswer::RevokedProxy| when called on
a revoked proxy.
Check whether obj supports the JS::GetArrayBufferMaybeShared* APIs. Note
that this may return false if a security wrapper is encountered that denies
the unwrapping. If this test succeeds, then it is safe to call the various
predicate and accessor JSAPI calls defined below.
Determine whether |value| is an Array object or a wrapper around one. (An
ES6 proxy whose target is an Array object, e.g.
|var target = [], handler = {}; Proxy.revocable(target, handler).proxy|, is
not considered to be an Array.)
Determine whether |obj| is an Array object or a wrapper around one. (An
ES6 proxy whose target is an Array object, e.g.
|var target = [], handler = {}; Proxy.revocable(target, handler).proxy|, is
not considered to be an Array.)
Return true if the given object is a constructor. In ES6 terms, an object is
a constructor if it has a [Construct] internal method. The expression
new obj() throws a TypeError if obj is not a constructor.
Check whether the obj is a detached ArrayBufferObject. Note that this may
return false if a security wrapper is encountered that denies the
unwrapping.
Whether we are poisoning unused/released data for error detection. Governed
by the JS_GC_ALLOW_EXTRA_POISONING #ifdef as well as the
javascript.options.extra_gc_poisoning pref.
Returns true if incremental GC is enabled. Simply having incremental GC
enabled is not sufficient to ensure incremental collections are happening.
See the comment “Incremental GC” above for reasons why incremental GC may be
suppressed. Inspection of the “nonincremental reason” field of the
GCDescription returned by GCSliceCallback may help narrow down the cause if
collections are not happening incrementally when expected.
Check whether the obj is ArrayBufferObject and memory mapped. Note that this
may return false if a security wrapper is encountered that denies the
unwrapping.
Check whether obj supports the JS::GetSharedArrayBuffer* APIs. Note that
this may return false if a security wrapper is encountered that denies the
unwrapping. If this test succeeds, then it is safe to call the various
accessor JSAPI calls defined below.
This function calls |realmCallback| on every realm. Beware that there is no
guarantee that the realm will survive after the callback returns. Also,
barriers are disabled via the TraceSession.
Inform the runtime that the job queue is empty and the embedding is going to
execute its last promise job. The runtime may now choose to skip creating
promise jobs for asynchronous execution and instead continue execution
synchronously. More specifically, this optimization is used to skip the
standard job queuing behavior for await operations in async functions.
Inform the runtime that job queue is no longer empty. The runtime can now no
longer skip creating promise jobs for asynchronous execution, because
pending jobs in the job queue must be executed first to preserve the FIFO
(first in - first out) property of the queue. This effectively undoes
JobQueueIsEmpty and re-enables the standard job queuing behavior.
Create an Array from the current realm with the given length and allocate
memory for all its elements. (The elements nonetheless will not exist as
properties on the returned array until values have been assigned to them.)
Create a new function based on the given JSFunctionSpec, *fs.
id is the result of a successful call to
PropertySpecNameToId(cx, fs->name, &id) or
PropertySpecNameToPermanentId(cx, fs->name, &id).
Create a new mapped ArrayBuffer with the given memory mapped contents. It
must be legal to free the contents pointer by unmapping it. On success,
ownership is transferred to the new mapped ArrayBuffer.
Create a new SharedArrayBuffer with the given byte length. This
may only be called if
JS::RealmCreationOptionsRef(cx).getSharedMemoryAndAtomicsEnabled() is
true.
Like NewStringFromLatin1Buffer, but can be used to avoid refcounting overhead
in cases where the returned string doesn’t use the buffer. The caller must
ensure the buffer outlives this call.
Like NewStringFromUTF8Buffer, but can be used to avoid refcounting overhead
in cases where the returned string doesn’t use the buffer. The caller must
ensure the buffer outlives this call.
Create a BigInt from a floating-point value. If the number isn’t integral
(that is, if it’s NaN, an infinity, or contains a fractional component),
this function returns null and throws an exception.
On success, returns true, setting |*isRegExp| to true if |obj| is a RegExp
object or a wrapper around one, or to false if not. Returns false on
failure.
When performing an incremental GC, the zones that were selected for the
previous incremental slice must be selected in subsequent slices as well.
This function selects those slices automatically.
Release the allocated resource of mapped ArrayBuffer contents before the
object is created.
If a new object has been created by JS::NewMappedArrayBufferWithContents()
with this content, then JS::DetachArrayBuffer() should be used instead to
release the resource used by the object.
Advise the GC that external memory reported by JS::AddAssociatedMemory() is
no longer owned by a JSObject. Calls must match those to
AddAssociatedMemory().
An uncatchable exception is used to terminate execution by returning false
or nullptr without reporting a pending exception on the context. These
exceptions are called “uncatchable” because try-catch can’t be used to catch
them.
Re-query the system to determine the current time zone adjustment from UTC,
including any component due to DST. If the time zone has changed, this will
cause all Date object non-UTC methods and formatting functions to produce
appropriately adjusted results.
Stores |SameValue(v1, v2)| to |*equal| – using the SameValue operation
defined in ECMAScript, initially exposed to script as |Object.is|. SameValue
behaves identically to strict equality, except that it equates two NaN values
and does not equate differently-signed zeroes. It performs no conversions on
|v1| or |v2| before comparing.
Called when generating a GC slice budget. It allows the embedding to control
the duration of slices and potentially check an interrupt flag as well. For
internally triggered GCs, the given millis parameter is the JS engine’s
internal scheduling decision, which the embedding can choose to ignore.
(Otherwise, it will be the value that was passed to eg
JS::IncrementalGCSlice()).
The GC slice callback is called at the beginning and end of each slice. This
callback may be used for GC notifications as well as to perform additional
marking.
Tell JS engine whether Profile Timeline Recording is enabled or not.
If Profile Timeline Recording is enabled, data shown there like stack won’t
be optimized out.
This is global state and not associated with specific runtime or context.
Sets the callback that’s invoked whenever a Promise is rejected without
a rejection handler, and when a Promise that was previously rejected
without a handler gets a handler attached.
When a JSRuntime is destroyed it implicitly cancels all async tasks in
progress, releasing any roots held by the task. However, this is not soon
enough for cycle collection, which needs to have roots dropped earlier so
that the cycle collector can transitively remove roots for a future GC. For
these and other cases, the set of pending async tasks can be canceled
with this call earlier than JSRuntime destruction.
Begin an incremental collection and perform one slice worth of work. When
this function returns, the collection may not be complete.
IncrementalGCSlice() must be called repeatedly until
!IsIncrementalGCInProgress(cx).
Steal the contents of the given ArrayBuffer. The ArrayBuffer has its length
set to 0 and its contents array cleared. The caller takes ownership of the
return value and must free it or transfer ownership via
JS::NewArrayBufferWithContents when done using it.
Create a BigInt by parsing a string using the ECMAScript StringToBigInt
algorithm (https://tc39.es/ecma262/#sec-stringtobigint). Latin1 and two-byte
character ranges are supported. It may be convenient to use
JS::ConstLatin1Chars or JS::ConstTwoByteChars.
Performs the JSON.stringify operation, as specified by ECMAScript, except
writing stringified data by one call of |callback|, passing |data| as
argument.
An API akin to JS_Stringify but with the goal of not having observable
side-effects when the stringification is performed. This means it does not
allow a replacer or a custom space and has the following constraints on its
input:
Unsets the gray bit for anything reachable from |thing|. |kind| should not be
JS::TraceKind::Shape. |thing| should be non-null. The return value indicates
if anything was unmarked.
Return the buildId (represented as a sequence of characters) associated with
the currently-executing build. If the JS engine is embedded such that a
single cache entry can be observed by different compiled versions of the JS
engine, it is critical that the buildId shall change for each new build of
the JS engine.
Reference to a T that has been rooted elsewhere. This is most useful
as a parameter type, which guarantees that the T lvalue is properly
rooted. See “Move GC Stack Rooting” above.
Reference to a T that has been rooted elsewhere. This is most useful
as a parameter type, which guarantees that the T lvalue is properly
rooted. See “Move GC Stack Rooting” above.
Reference to a T that has been rooted elsewhere. This is most useful
as a parameter type, which guarantees that the T lvalue is properly
rooted. See “Move GC Stack Rooting” above.
Reference to a T that has been rooted elsewhere. This is most useful
as a parameter type, which guarantees that the T lvalue is properly
rooted. See “Move GC Stack Rooting” above.
Reference to a T that has been rooted elsewhere. This is most useful
as a parameter type, which guarantees that the T lvalue is properly
rooted. See “Move GC Stack Rooting” above.
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.
Unlike the error reporter, which is only called if the exception for an OOM
bubbles up and is not caught, the OutOfMemoryCallback is called immediately
at the OOM site to allow the embedding to capture the current state of heap
allocation before anything is freed. If the large-allocation-failure callback
is called at all (not all allocation sites call the large-allocation-failure
callback on failure), it is called before the out-of-memory callback; the
out-of-memory callback is only called if the allocation still fails after the
large-allocation-failure callback has returned.
Result is intended to be the return type of JSAPI calls and internal
functions that can run JS code or allocate memory from the JS GC heap. Such
functions can:
Local variable of type T whose value is always rooted. This is typically
used for local variables, or for non-rooted values being passed to a
function that requires a handle, e.g. Foo(Root(cx, x)).
Local variable of type T whose value is always rooted. This is typically
used for local variables, or for non-rooted values being passed to a
function that requires a handle, e.g. Foo(Root(cx, x)).