JS::CompileOptions

This article covers features introduced in SpiderMonkey 17

Compile options classes.

Constructor

JS::ReadOnlyCompileOptions(); // Added in SpiderMonkey 31
JS::OwningCompileOptions(JSContext *cx); // Added in SpiderMonkey 31
JS::CompileOptions(JSContext *cx, JSVersion version = JSVERSION_UNKNOWN);
Name Type Description
cx JSContext * 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.
JSScript *introductionScript() const Returns a pointer to JSScript which introduces the file.
bool copy(JSContext *cx, const ReadOnlyCompileOptions &rhs) Copy compile options from rhs. Returns false if it failed to duplicate owning properties.
bool setFile(JSContext *cx, const char *f) Duplicate null-terminated string f for filename(). Returns false if it failed to duplicate.
bool setFileAndLine(JSContext *cx, const char *f, unsigned l) Duplicate null-terminated string f for filename() and set lineno property. Returns false if it failed to duplicate.
bool setSourceMapURL(JSContext *cx, const char16_t *s) Duplicate null-terminated string s for sourceMapURL. Returns false if it failed to duplicate.
bool setIntroducerFilename(JSContext *cx, const char *s) Duplicate null-terminated string s for introducerFilename. Returns false if it failed to duplicate.
OwningCompileOptions &setLine(unsigned l) Sets each property and returns the instance itself.
OwningCompileOptions &setElement(JSObject *e)
OwningCompileOptions &setElementAttributeName(JSString *p)
OwningCompileOptions &setIntroductionScript(JSScript *s)
OwningCompileOptions &setMutedErrors(bool mute)
OwningCompileOptions &setVersion(JSVersion v)
OwningCompileOptions &setUTF8(bool u)
OwningCompileOptions &setColumn(unsigned c)
OwningCompileOptions &setCompileAndGo(bool cng)
OwningCompileOptions &setForEval(bool eval)
OwningCompileOptions &setNoScriptRval(bool nsr)
OwningCompileOptions &setSelfHostingMode(bool shm)
OwningCompileOptions &setCanLazilyParse(bool clp)
OwningCompileOptions &setSourceIsLazy(bool l)
OwningCompileOptions &setIntroductionType(const char *t)
bool setIntroductionInfo(JSContext *cx, const char *introducerFn, const char *intro, unsigned line, JSScript *script, uint32_t offset) Duplicate null-terminated string introducerFn for introducerFilename and set introductionType, introductionLineno, introductionScriptRoot, introductionOffset, and hasIntroductionInfo properties. Returns false if it failed to duplicate.
Methods of JS::CompileOptions
Method Description
JSObject *element() const Same as JS::OwningCompileOptions.
JSString *elementAttributeName() const
JSScript *introductionScript() const
CompileOptions &setFile(const char *f) Sets each property and returns the instance itself.
CompileOptions &setLine(unsigned l)
CompileOptions &setFileAndLine(const char *f, unsigned l)
CompileOptions &setSourceMapURL(const char16_t *s)
CompileOptions &setElement(JSObject *e)
CompileOptions &setElementAttributeName(JSString *p)
CompileOptions &setIntroductionScript(JSScript *s)
CompileOptions &setMutedErrors(bool mute)
CompileOptions &setVersion(JSVersion v)
CompileOptions &setUTF8(bool u)
CompileOptions &setColumn(unsigned c)
CompileOptions &setCompileAndGo(bool cng)
CompileOptions &setForEval(bool eval)
CompileOptions &setNoScriptRval(bool nsr)
CompileOptions &setSelfHostingMode(bool shm)
CompileOptions &setCanLazilyParse(bool clp)
CompileOptions &setSourceIsLazy(bool l)
CompileOptions &setIntroductionType(const char *t)
CompileOptions &setIntroductionInfo(const char *introducerFn, const char *intro, unsigned line, JSScript *script, uint32_t offset)
CompileOptions &maybeMakeStrictMode(bool strict)

Properties

Properties of JS::ReadOnlyCompileOptions
Name Type Description
version JSVersion Version of the script.
versionSet bool true if version is set.
utf8 bool true if the character set of the source code is UTF-8.
lineno unsigned Line number of the first line of the source code (1-origin).
column unsigned Column number of the first line of the source code (0-origin).
compileAndGo bool true if the code is going to be evaluated soon after the compile (e.g., false for Function constructor and event handler).
forEval bool true if the code is for eval().
noScriptRval bool false means that the caller needs the return value of the script.
selfHostingMode bool true iff the code is self-hosted.
canLazilyParse bool true if the source code can be parsed lazily (check only syntax for first time, and fully parse when it's really needed).
strictOption bool true if the code is strict mode ("use strict").
extraWarningsOption bool Show extra warning.
werrorOption bool Treat warning as error.
asmJSOption bool true if asm.js is allowed in the code.
forceAsync bool false means JS::CanCompileOffThread may returns false depends on the length of the code.
installedFile bool true iff pre-compiling js file in packaged app.
sourceIsLazy bool true indicates that, after compilation, script source should not be cached by the JS engine and should be lazily loaded from the embedding as-needed.
introductionType const char

A statically allocated C string: one of following in general:

  • "eval" - code passed to eval
  • "Function" - code passed to the Function constructor.
  • "GeneratorFunction" - code passed to the GeneratorFunction constructor.

In addition to above, the following are used in browser:

  • "Worker" - code loaded by calling the Web worker constructor—the worker's main script.
  • "importScript" - code by calling importScripts in a web worker.
  • "eventHandler" - code assigned to DOM elements' event handler IDL attributes as a string.
  • "scriptElement" - code belonging to <script> elements.
  • "javascriptURL" - code presented in javascript: URLs.
  • "setTimeout" - code passed to setTimeout as a string.
  • "setInterval" - code passed to setInterval as a string.

The following are used in js shell:

  • "js shell file"
  • "js shell interactive"
  • "js shell load"
  • "js shell evaluate"
  • "js shell run"
  • "js shell disFile"
  • "js shell compFile"
  • "js shell parse"
  • "js shell syntaxParse"
  • "js shell offThreadCompileScript"

And the following are used in self-hosted code and debugger:

  • "self-hosted"
  • "debugger eval"
introductionLineno unsigned Line number in the source code which introduces this source code.
introductionOffset uint32_t Bytecode offset in the code which introduces this source code.
hasIntroductionInfo bool true if setIntroductionInfo is called.

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.

See Also

Document Tags and Contributors

Tags: 
 Contributors to this page: kscarfone, arai
 Last updated by: kscarfone,