Pointer to a JS context from which to derive runtime information. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext.

version

JSVersion

JavaScript version used to compile the script.

Methods

Some methods of JS::OwningCompileOptions and JS::CompileOptions return the instance itself to allow method chain.

Methods of JS::ReadOnlyCompileOptions

Method

Description

bool mutedErrors() const

Determines if errors are muted.

The Web Platform allows scripts to be loaded from arbitrary cross-origin sources. This allows an attack by which a malicious website loads a sensitive file (say, a bank statement) cross-origin (using the user's cookies), and sniffs the generated syntax errors (via a window.onerror handler) for juicy morsels of its contents.

To counter this attack, HTML5 specifies that script errors should be sanitized ("muted") when the script is not same-origin with the global for which it is loaded. Callers should set this flag for cross-origin scripts, and it will be propagated appropriately to child scripts and passed back in JSErrorReports.

const char *filename() const

Returns filename of the source code.

const char *introducerFilename() const

Returns filename of the file which introduces the file.

const char16_t *sourceMapURL() const

Returns the URL of the source map.

Methods of JS::OwningCompileOptions

Method

Description

JSObject *element() const

Returns the DOM element to which this source code belongs, if any, or NULL if it belongs to no DOM element. Source belongs to a DOM element in the following cases:

Source belongs to a <script> element if it is the element's text content (that is, it is written out as the body of the <script> element in the markup text), or is the source document referenced by its src attribute.

Source belongs to a DOM element if it is an event handler content attribute (that is, if it is written out in the markup text as an attribute value).

Source belongs to a DOM element if it was assigned to one of the element's event handler IDL attributes as a string. (Note that one may assign both strings and functions to DOM elements' event handler IDL attributes. If one assigns a function, that function's script's source does
not
belong to the DOM element; the function's definition must appear elsewhere.)

JSString *elementAttributeName() const

If this source belongs to a DOM element because it is an event handler content attribute or an event handler IDL attribute, this returns the name of that attribute, a string. Otherwise, this returns NULL.

Description

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; strings will not 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, and 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.

So, we have a class hierarchy that reflects these three use cases:

ReadOnlyCompileOptions is the common base class. It can be used by code that simply needs to access options set elsewhere, like the compiler.

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.

ReadOnlyCompileOptions

ReadOnlyCompileOptions is the common base class for the CompileOptions hierarchy.

Use this in code that only needs to access compilation options created elsewhere, like the compiler. Don't instantiate this class (the constructor is protected anyway); instead, create instances only of the derived classes: CompileOptions and OwningCompileOptions.

OwningCompileOptions

OwningCompileOptions is the 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.

Note that this *roots* any JS values it refers to - they're live unconditionally. Thus, instances of this type can't be owned, directly or indirectly, by a JavaScript object: if any value that this roots ever comes to refer to the object that owns this, then the whole cycle, and anything else it entrains, will never be freed.

CompileOptions

CompileOptions is the 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.