SpiderMonkey Internals

  • Revision slug: SpiderMonkey/Internals
  • Revision title: SpiderMonkey Internals
  • Revision id: 47526
  • Created:
  • Creator: Dmandelin
  • Is current revision? No
  • Comment 2 words added, 3 words removed

Revision Content

{{ tree("en/SpiderMonkey/Internals") }}

Design walk-through

At heart, SpiderMonkey is a fast interpreter that runs an untyped bytecode and operates on values of type jsval—type-tagged double-sized values that represent the full range of JavaScript values. In addition to the interpreter, SpiderMonkey contains a Just-In-Time (JIT) compiler, a garbage collector, code implementing the basic behavior of JavaScript values, a standard library implementing {{ Es3_spec("15") }} with various extensions, and a few public APIs.

Interpreter

Like many portable interpreters, SpiderMonkey's interpreter is mainly a single, tremendously long function that steps through the bytecode one instruction at a time, using a switch statement (or faster alternative, depending on the compiler) to jump to the appropriate chunk of code for the current instruction. A JS-to-JS function call pushes a JavaScript stack frame without growing the C stack. But since JS-to-C-to-JS call stacks are common, the interpreter is reentrant.

Some SpiderMonkey bytecode operations have many special cases, depending on the type of their arguments. Common cases are inlined in the interpreter loop, breaking any abstractions that stand in the way. So optimizations such as dense arrays and the property cache are, alas, not transparently tucked away in the jsarray.* and jsobj.* files. Both guest-star in jsinterp.cpp (to thunderous applause from Firefox users).

All state associated with an interpreter instance is passed through formal parameters to the interpreter entry point; most implicit state is collected in a type named JSContext. Therefore, almost all functions in SpiderMonkey, API or not, take a JSContext pointer as their first argument.

Compiler

The compiler consumes JavaScript source code and produces a script which contains bytecode, source annotations, and a pool of string, number, and identifier literals. The script also contains objects, including any functions defined in the source code, each of which has its own, nested script.

The compiler consists of: a random-logic rather than table-driven lexical scanner, a recursive-descent parser that produces an AST, and a tree-walking code generator. Semantic and lexical feedback are used to disambiguate hard cases such as missing semicolons, assignable expressions ("lvalues" in C parlance), and whether / is the division symbol or the start of a regular expression. The compiler attempts no error recovery; it bails out on the first error. The emitter does some constant folding and a few codegen optimizations; about the fanciest thing it does is to attach source notes to the script for the decompiler's benefit.

The decompiler implements Function.toSource(), which reconstructs a function's source code. It translates postfix bytecode into infix source by consulting a separate byte-sized code, called source notes, to disambiguate bytecodes that result from more than one grammatical production.

Garbage collector

The GC is a mark-and-sweep, non-conservative (exact) collector. It is used to hold JS objects and string descriptors (but not property lists or string bytes), and double-precision floating point numbers. It runs automatically only when maxbytes (as passed to JS_NewRuntime) bytes of GC things have been allocated and another thing-allocation request is made. JS API users should call JS_GC or JS_MaybeGC between script executions or from the branch callback, as often as necessary.

Because the GC is exact, C/C++ applications must ensure that all live objects, strings, and numbers are GC-reachable. Many techniques are available; see SpiderMonkey Garbage Collection Tips.

JavaScript values

The jsval type is a signed machine word that contains either a signed integer value (if the low bit is set), or a type-tagged pointer or special value (if the low bit is clear). Tagged pointers all refer to 8-byte-aligned things in the GC heap. The special values are JSVAL_NULL, JSVAL_VOID (undefined), JSVAL_TRUE, and JSVAL_FALSE. Another special value, JSVAL_HOLE, is used internally only (to represent deleted Array elements, for example). This value is never exposed to scripts or even via the JSAPI.

Objects consist of a possibly shared structural description, called the map or scope; and unshared property values in a vector, called the slots. Each property has an id, either a nonnegative integer or an atom (unique string), with the same tagged-pointer encoding as a jsval.

The atom manager consists of a hash table associating strings uniquely with scanner/parser information such as keyword type, index in script or function literal pool, etc. Atoms play three roles: as literals referred to by unaligned 16-bit immediate bytecode operands, as unique string descriptors for efficient property name hashing, and as members of the root GC set for exact GC.

Standard library

The methods for arrays, booleans, dates, functions, numbers, and strings are implemented using the JS API. Most are JSFastNatives. Most string methods are customized to accept a primitive string as the this argument. (Otherwise, SpiderMonkey converts primitive values to objects before invoking their methods, per {{ Es3_spec("11.2.1") }}.)

Error handling

SpiderMonkey has two interdependent error-handling systems: JavaScript exceptions (which are not implemented with, or even compatible with, any kind of native C/C++ exception handling) and error reporting. In general, both functions inside SpiderMonkey and JSAPI callback functions signal errors by calling JS_ReportError or one of its variants, or JS_SetPendingException, and returning JS_FALSE or NULL.

Public APIs

The public C/C++ interface, called the JSAPI, is in most places a thin (but source-compatible across versions) layer over the implementation. See the JSAPI User Guide. There is an additional public API for JavaScript debuggers, JSDBGAPI, but {{ Source("js/jsd/jsdebug.h") }} might be a better API for debuggers. Another API, JSXDRAPI, provides serialization for JavaScript scripts. (XUL Fastload uses this.)

Just-In-Time trace compiler

{{ jsapi_minversion_inline("1.8.1") }} SpiderMonkey contains a just-in-time trace compiler that converts bytecode to machine code for faster execution. The JIT works by detecting commonly executed loops, tracing the executed bytecodes in those loops as they run in the interpreter, and then compiling the trace to machine code. SpiderMonkey's tracing JIT is based on JVM work by Andreas Gal et al (PDF) but the basic technique has been around at least since the Dynamo project in the late 1990s. See the page about the Tracing JIT for more details.

File walkthrough

jsapi.cpp, jsapi.h

The public API to be used by almost all client code.

jspubtd.h, jsprvtd.h

These files exist to group struct and scalar typedefs so they can be used everywhere without dragging in struct definitions from N different files. The jspubtd.h file contains public typedefs, and is included automatically when needed. The jsprvtd.h file contains private typedefs and is included by various .h files that need type names, but not type sizes or declarations.

jsdbgapi.cpp, jsdbgapi.h

The debugging API. Provided so far:

Traps, with which breakpoints, single-stepping, step over, step out, and so on can be implemented. The debugger will have to consult jsopcode.def on its own to figure out where to plant trap instructions to implement functions like step out, but a future jsdbgapi.h will provide convenience interfaces to do these things. At most one trap per bytecode can be set. When a script (JSScript) is destroyed, all traps set in its bytecode are cleared.

Watchpoints, for intercepting set operations on properties and running a debugger-supplied function that receives the old value and a pointer to the new one, which it can use to modify the new value being set.

Line number to PC and back mapping functions. The line-to-PC direction "rounds" toward the next bytecode generated from a line greater than or equal to the input line, and may return the PC of a for-loop update part, if given the line number of the loop body's closing brace. Any line after the last one in a script or function maps to a PC one byte beyond the last bytecode in the script. An example, from perfect.js:

14   function perfect(n)
15   {
16       print("The perfect numbers up to " + n + " are:");
17
18       // We build sumOfDivisors[i] to hold a string expression for
19       // the sum of the divisors of i, excluding i itself.
20       var sumOfDivisors = new ExprArray(n+1,1);
21       for (var divisor = 2; divisor <= n; divisor++) {
22           for (var j = divisor + divisor; j <= n; j += divisor) {
23               sumOfDivisors[j] += " + " + divisor;
24           }
25           // At this point everything up to 'divisor' has its sumOfDivisors
26           // expression calculated, so we can determine whether it's perfect
27           // already by evaluating.
28           if (eval(sumOfDivisors[divisor]) == divisor) {
29               print("" + divisor + " = " + sumOfDivisors[divisor]);
30           }
31       }
32       delete sumOfDivisors;
33       print("That's all.");
34   }

The line number to PC and back mappings can be tested using the js program with the following script:

load("perfect.js");
print(perfect);
dis(perfect);
print();
for (var ln = 0; ln <= 40; ln++) {
    var pc = line2pc(perfect, ln);
    var ln2 = pc2line(perfect, pc);
    print("\tline " + ln + " => pc " + pc + " => line " + ln2);
}

The result of the for loop over lines 0 to 40 inclusive is:

line 0 => pc 0 => line 16
line 1 => pc 0 => line 16
line 2 => pc 0 => line 16
line 3 => pc 0 => line 16
line 4 => pc 0 => line 16
line 5 => pc 0 => line 16
line 6 => pc 0 => line 16
line 7 => pc 0 => line 16
line 8 => pc 0 => line 16
line 9 => pc 0 => line 16
line 10 => pc 0 => line 16
line 11 => pc 0 => line 16
line 12 => pc 0 => line 16
line 13 => pc 0 => line 16
line 14 => pc 0 => line 16
line 15 => pc 0 => line 16
line 16 => pc 0 => line 16
line 17 => pc 19 => line 20
line 18 => pc 19 => line 20
line 19 => pc 19 => line 20
line 20 => pc 19 => line 20
line 21 => pc 36 => line 21
line 22 => pc 53 => line 22
line 23 => pc 74 => line 23
line 24 => pc 92 => line 22
line 25 => pc 106 => line 28
line 26 => pc 106 => line 28
line 27 => pc 106 => line 28
line 28 => pc 106 => line 28
line 29 => pc 127 => line 29
line 30 => pc 154 => line 21
line 31 => pc 154 => line 21
line 32 => pc 161 => line 32
line 33 => pc 172 => line 33
line 34 => pc 172 => line 33
line 35 => pc 172 => line 33
line 36 => pc 172 => line 33
line 37 => pc 172 => line 33
line 38 => pc 172 => line 33
line 39 => pc 172 => line 33
line 40 => pc 172 => line 33
jsconfig.h

Various configuration macros defined as 0 or 1 depending on how JS_VERSION is defined (as 10 for JavaScript 1.0, 11 for JavaScript 1.1, etc.). Not all macros are tested around related code yet. In particular, JS 1.0 support is missing from SpiderMonkey.

js.cpp, jsshell.msg

The "JS shell", a simple interpreter program that uses the JS API and more than a few internal interfaces (some of these internal interfaces could be replaced by jsapi.h calls). The js program built from this source provides a test vehicle for evaluating scripts and calling functions, trying out new debugger primitives, etc.

A look at the places where jsshell.msg is used in js.cpp shows how error messages can be handled in JSAPI applications. These messages can be localized at compile time by replacing the .msg file; or, with a little modification to the source, at run time.

More information on the JavaScript shell.

js.msg

SpiderMonkey error messages.

jsarray.*, jsbool.*, jsdate.*, jsfun.*, jsmath.*, jsnum.*, jsstr.*

These file pairs implement the standard classes and (where they exist) their underlying primitive types. They have similar structure, generally starting with class definitions and continuing with internal constructors, finalizers, and helper functions.

jsobj.*, jsscope.*

These two pairs declare and implement the JS object system. All of the following happen here:

  • creating objects by class and prototype, and finalizing objects;
  • defining, looking up, getting, setting, and deleting properties;
  • creating and destroying properties and binding names to them.

The details of a native object's map (scope) are mostly hidden in jsscope.{{ mediawiki.external('ch') }}.

jsatom.cpp, jsatom.h

The atom manager. Contains well-known string constants, their atoms, the global atom hash table and related state, the js_Atomize() function that turns a counted string of bytes into an atom, and literal pool (JSAtomMap) methods.

jsarena.cpp, jsarena.h

Last-In-First-Out allocation macros that amortize malloc costs and allow for en-masse freeing. See the paper mentioned in jsarena.h's major comment.

jsgc.cpp, jsgc.h

The garbage collector and tracing routines.

jsinterp.*, jscntxt.*, jsinvoke.cpp

The bytecode interpreter, and related functions such as Call and AllocStack, live in jsinterp.cpp. The JSContext constructor and destructor are factored out into jscntxt.cpp for minimal linking when the compiler part of JS is split from the interpreter part into a separate program.

jsinvoke.cpp is a build hack used on some platforms to build js_Interpret under different compiler options from the rest of jsinterp.cpp.

jstracer.*, nanojit/*

The tracing JIT. The interface between the JIT and the rest of SpiderMonkey is conceptually small—the interpreter calls into the trace recorder—but as with everything else, there are tendrils everywhere.

jsemit.*, jsopcode.tbl, jsopcode.*, jsparse.*, jsscan.*, jsscript.*

Compiler and decompiler modules. The jsopcode.tbl file is a C preprocessor source that defines almost everything there is to know about JS bytecodes. See its major comment for how to use it. For now, a debugger will use it and its dependents such as jsopcode.h directly, but over time we intend to extend jsdbgapi.h to hide uninteresting details and provide conveniences. The code generator is split across paragraphs of code in jsparse.cpp, and the utility methods called on JSCodeGenerator appear in jsemit.cpp. Source notes generated by jsparse.cpp and jsemit.cpp are used in jsscript.cpp to map line number to program counter and back.

jstypes.h

Fundamental representation types and utility macros. This file alone among all .h files in SpiderMonkey must be included first by .cpp files. It is not nested in .h files, as other prerequisite .h files generally are, since it is also a direct dependency of most .cpp files and would be over-included if nested in addition to being directly included.

jsbit.h, jslog2.cpp

Bit-twiddling routines. Most of the work here is selectively enabling compiler-specific intrinsics such as GCC's __builtin_ctz, which is useful in calculating base-2 logarithms of integers.

jsutil.cpp, jsutil.h

The JS_ASSERT macro is used throughout the source as a proof device to make invariants and preconditions clear to the reader, and to hold the line during maintenance and evolution against regressions or violations of assumptions that it would be too expensive to test unconditionally at run-time. Certain assertions are followed by run-time tests that cope with assertion failure, but only where I'm too smart or paranoid to believe the assertion will never fail...

jsclist.h

Doubly-linked circular list struct and macros.

jscpucfg.cpp

This standalone program generates jscpucfg.h, a header file containing bytes per word and other constants that depend on CPU architecture and C compiler type model. It tries to discover most of these constants by running its own experiments on the build host, so if you are cross-compiling, beware.

jsdtoa.cpp, jsdtoa.h, dtoa.c

dtoa.c contains David Gay's portable double-precision floating point to string conversion code, with Permission To Use notice included. jsdtoa.cpp #includes this file.

jshash.cpp, jshash.h, jsdhash.cpp, jsdhash.h

Portable, extensible hash tables. These use multiplicative hash for strength reduction over division hash, yet with very good key distribution over power of two table sizes. jshash resolves collisions via chaining, so each entry burns a malloc and can fragment the heap. jsdhash uses open addressing.

jslong.cpp, jslong.h

64-bit integer emulation, and compatible macros that use intrinsic C types, like long long, on platforms where they exist (most everywhere, these days).

jsprf.*

Portable, buffer-overrun-resistant sprintf and friends. For no good reason save lack of time, the %e, %f, and %g formats cause your system's native sprintf, rather than JS_dtoa(), to be used. This bug doesn't affect SpiderMonkey, because it uses its own JS_dtoa() call in jsnum.cpp to convert from double to string, but it's a bug that we'll fix later, and one you should be aware of if you intend to use a JS_*printf() function with your own floating type arguments - various vendor sprintf's mishandle NaN, +/-Inf, and some even print normal floating values inaccurately.

prmjtime.c, prmjtime.h

Time functions. These interfaces are named in a way that makes local vs. universal time confusion likely. Caveat emptor, and we're working on it. To make matters worse, Java (and therefore JavaScript) uses "local" time numbers (offsets from the epoch) in its Date class.

jsfile.cpp, jsfile.h, jsfile.msg

Obsolete. Do not use these files.

Makefile.in, build.mk

Mozilla makefiles. If you're building Gecko or Firefox, the larger build system will use these files. They are also used for current standalone builds.

Makefile.ref, rules.mk, config.mk, config/*

Obsolete SpiderMonkey standalone makefiles from 1.8 and earlier. See SpiderMonkey Build Documentation.

See also

jsd

Revision Source

<p>{{ tree("en/SpiderMonkey/Internals") }}</p>
<h3 name="Design_walk-through">Design walk-through</h3>
<p>At heart, SpiderMonkey is a fast interpreter that runs an untyped bytecode and operates on values of type <code><a href="/En/SpiderMonkey/JSAPI_Reference/Jsval" title="En/SpiderMonkey/JSAPI_Reference/Jsval">jsval</a></code>—type-tagged <a class="external" href="http://blog.mozilla.com/rob-sayre/2010/08/02/mozillas-new-javascript-value-representation/" title="http://blog.mozilla.com/rob-sayre/2010/08/02/mozillas-new-javascript-value-representation/">double-sized</a> values that represent the full range of JavaScript values. In addition to the interpreter, SpiderMonkey contains a Just-In-Time (JIT) compiler, a garbage collector, code implementing the basic behavior of JavaScript values, a standard library implementing {{ Es3_spec("15") }} with various extensions, and a few public APIs.</p>
<h4>Interpreter</h4>
<p>Like many portable interpreters, SpiderMonkey's interpreter is mainly a single, tremendously long function that steps through the bytecode one instruction at a time, using a <code>switch</code> statement (or faster alternative, depending on the compiler) to jump to the appropriate chunk of code for the current instruction. A JS-to-JS function call pushes a JavaScript stack frame without growing the C stack. But since JS-to-C-to-JS call stacks are common, the interpreter is reentrant.</p>
<p>Some SpiderMonkey bytecode operations have many special cases, depending on the type of their arguments. Common cases are inlined in the interpreter loop, breaking any abstractions that stand in the way. So optimizations such as dense arrays and the property cache are, alas, <em>not</em> transparently tucked away in the <code>jsarray.*</code> and <code>jsobj.*</code> files. Both guest-star in <code>jsinterp.cpp</code> (to thunderous applause from Firefox users).</p>
<p>All state associated with an interpreter instance is passed through formal parameters to the interpreter entry point; most implicit state is collected in a type named <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/SpiderMonkey/JSAPI_Reference/JSRuntime">JSContext</a></code>. Therefore, almost all functions in SpiderMonkey, API or not, take a <code>JSContext</code> pointer as their first argument.</p>
<h4>Compiler</h4>
<p>The compiler consumes JavaScript source code and produces a <em>script</em> which contains bytecode, source annotations, and a pool of string, number, and identifier literals. The script also contains objects, including any functions defined in the source code, each of which has its own, nested script.</p>
<p>The compiler consists of: a random-logic rather than table-driven lexical scanner, a recursive-descent parser that produces an AST, and a tree-walking code generator. Semantic and lexical feedback are used to disambiguate hard cases such as missing semicolons, assignable expressions ("lvalues" in C parlance), and whether <code>/</code> is the division symbol or the start of a regular expression. The compiler attempts no error recovery; it bails out on the first error. The emitter does some constant folding and a few codegen optimizations; about the fanciest thing it does is to attach source notes to the script for the decompiler's benefit.</p>
<p>The decompiler implements <code>Function.toSource()</code>, which reconstructs a function's source code. It translates postfix bytecode into infix source by consulting a separate byte-sized code, called <em>source notes</em>, to disambiguate bytecodes that result from more than one grammatical production.</p>
<h4>Garbage collector</h4>
<p>The GC is a mark-and-sweep, non-conservative (exact) collector. It is used to hold JS objects and string descriptors (but not property lists or string bytes), and double-precision floating point numbers. It runs automatically only when maxbytes (as passed to <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_NewRuntime" title="en/SpiderMonkey/JSAPI_Reference/JS_NewRuntime">JS_NewRuntime</a></code>) bytes of GC things have been allocated and another thing-allocation request is made. JS API users should call <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_GC" title="en/SpiderMonkey/JSAPI_Reference/JS_GC">JS_GC</a></code> or <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_MaybeGC" title="en/SpiderMonkey/JSAPI_Reference/JS_MaybeGC">JS_MaybeGC</a></code> between script executions or from the <a href="/en/SpiderMonkey/JSAPI_Reference/JS_SetBranchCallback" title="en/SpiderMonkey/JSAPI_Reference/JS_SetBranchCallback">branch callback</a>, as often as necessary.</p>
<p>Because the GC is exact, C/C++ applications must ensure that all live objects, strings, and numbers are GC-reachable. Many techniques are available; see <a href="/en/SpiderMonkey_Garbage_Collection_Tips" title="en/SpiderMonkey_Garbage_Collection_Tips">SpiderMonkey Garbage Collection Tips</a>.</p>
<h4>JavaScript values</h4>
<p>The <code><a href="/En/SpiderMonkey/JSAPI_Reference/Jsval" title="En/SpiderMonkey/JSAPI_Reference/Jsval">jsval</a></code> type is a signed machine word that contains either a signed integer value (if the low bit is set), or a type-tagged pointer or special value (if the low bit is clear). Tagged pointers all refer to 8-byte-aligned things in the GC heap. The special values are <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_NULL" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_NULL">JSVAL_NULL</a></code>, <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_VOID" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_VOID">JSVAL_VOID</a></code> (<code>undefined</code>), <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_TRUE" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_TRUE">JSVAL_TRUE</a></code>, and <code><a href="/en/JSVAL_FALSE" title="en/JSVAL_FALSE">JSVAL_FALSE</a></code>. Another special value, <code><a href="/en/JSVAL_HOLE" title="en/JSVAL_HOLE">JSVAL_HOLE</a></code>, is used internally only (to represent deleted <code>Array</code> elements, for example). This value is never exposed to scripts or even via the JSAPI.</p>
<p>Objects consist of a possibly shared structural description, called the map or scope; and unshared property values in a vector, called the slots. Each property has an <a href="/en/SpiderMonkey/JSAPI_Reference/jsid" title="en/SpiderMonkey/JSAPI_Reference/jsid">id</a>, either a nonnegative integer or an atom (unique string), with the same tagged-pointer encoding as a <code>jsval</code>.</p>
<p>The atom manager consists of a hash table associating strings uniquely with scanner/parser information such as keyword type, index in script or function literal pool, etc. Atoms play three roles: as literals referred to by unaligned 16-bit immediate bytecode operands, as unique string descriptors for efficient property name hashing, and as members of the root GC set for exact GC.</p>
<h4>Standard library</h4>
<p>The methods for arrays, booleans, dates, functions, numbers, and strings are implemented using the JS API. Most are <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSFastNative" title="en/SpiderMonkey/JSAPI_Reference/JSFastNative">JSFastNative</a></code>s. Most string methods are customized to accept a primitive string as the <code>this</code> argument. (Otherwise, SpiderMonkey converts primitive values to objects before invoking their methods, per {{ Es3_spec("11.2.1") }}.)</p>
<h4>Error handling</h4>
<p>SpiderMonkey has two interdependent error-handling systems: JavaScript exceptions (which are <em>not</em> implemented with, or even compatible with, any kind of native C/C++ exception handling) and error reporting. In general, both functions inside SpiderMonkey and JSAPI callback functions signal errors by calling <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_ReportError" title="en/SpiderMonkey/JSAPI_Reference/JS_ReportError">JS_ReportError</a></code> or one of its variants, or <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_SetPendingException" title="en/SpiderMonkey/JSAPI_Reference/JS_SetPendingException">JS_SetPendingException</a></code>, and returning <code><a href="/En/SpiderMonkey/JSAPI_Reference/JSBool" title="En/SpiderMonkey/JSAPI_Reference/JSBool">JS_FALSE</a></code> or <code>NULL</code>.</p>
<h4>Public APIs</h4>
<p>The public C/C++ interface, called the JSAPI, is in most places a thin (but source-compatible across versions) layer over the implementation. See the <a href="/En/SpiderMonkey/JSAPI_User_Guide" title="en/JSAPI_User_Guide">JSAPI User Guide</a>. There is an additional public API for JavaScript debuggers, <a href="/en/JSDBGAPI_Reference" title="en/JSDBGAPI_Reference">JSDBGAPI</a>, but {{ Source("js/jsd/jsdebug.h") }} might be a better API for debuggers. Another API, <a href="/en/JSXDRAPI" title="en/JSXDRAPI">JSXDRAPI</a>, provides serialization for JavaScript scripts. (XUL Fastload uses this.)</p>
<h4>Just-In-Time trace compiler</h4>
<p>{{ jsapi_minversion_inline("1.8.1") }} SpiderMonkey contains a just-in-time trace compiler that converts bytecode to machine code for faster execution. The JIT works by detecting commonly executed loops, tracing the executed bytecodes in those loops as they run in the interpreter, and then compiling the trace to machine code. SpiderMonkey's tracing JIT is based on <a class="external" href="http://www.usenix.org/events/vee06/full_papers/p144-gal.pdf" title="HotpathVM: An Effective JIT Compiler for Resource-constrained Devices (PDF)">JVM work by Andreas Gal et al</a> (PDF) but the basic technique has been around at least since the <a class="external" href="http://www.hpl.hp.com/techreports/1999/HPL-1999-77.html" title="HP Labs: Paper: Transparent Dynamic Optimization">Dynamo project</a> in the late 1990s. See the page about the <a class="internal" href="/En/SpiderMonkey/Internals/Tracing_JIT" title="En/SpiderMonkey/Internals/Tracing JIT">Tracing JIT</a> for more details.</p>
<h3 name="File_walkthrough">File walkthrough</h3>
<h5 name="jsapi.cpp.2C_jsapi.h">jsapi.cpp, jsapi.h</h5>
<p>The public API to be used by almost all client code.</p>
<h5 name="jspubtd.h.2C_jsprvtd.h">jspubtd.h, jsprvtd.h</h5>
<p>These files exist to group struct and scalar typedefs so they can be used everywhere without dragging in struct definitions from N different files. The <code>jspubtd.h</code> file contains public typedefs, and is included automatically when needed. The <code>jsprvtd.h</code> file contains private typedefs and is included by various .h files that need type names, but not type sizes or declarations.</p>
<h5 name="jsdbgapi.cpp.2C_jsdbgapi.h">jsdbgapi.cpp, jsdbgapi.h</h5>
<p>The debugging API. Provided so far:</p>
<p><strong>Traps</strong>, with which breakpoints, single-stepping, step over, step out, and so on can be implemented. The debugger will have to consult jsopcode.def on its own to figure out where to plant trap instructions to implement functions like step out, but a future jsdbgapi.h will provide convenience interfaces to do these things. At most one trap per bytecode can be set. When a script (<code><a href="/en/JSScript" title="en/JSScript">JSScript</a></code>) is destroyed, all traps set in its bytecode are cleared.</p>
<p><strong>Watchpoints</strong>, for intercepting set operations on properties and running a debugger-supplied function that receives the old value and a pointer to the new one, which it can use to modify the new value being set.</p>
<p><strong>Line number</strong> to PC and back mapping functions. The line-to-PC direction "rounds" toward the next bytecode generated from a line greater than or equal to the input line, and may return the PC of a for-loop update part, if given the line number of the loop body's closing brace. Any line after the last one in a script or function maps to a PC one byte beyond the last bytecode in the script. An example, from perfect.js:</p>
<pre class="eval">14   function perfect(n)
15   {
16       print("The perfect numbers up to " + n + " are:");
17
18       // We build sumOfDivisors[i] to hold a string expression for
19       // the sum of the divisors of i, excluding i itself.
20       var sumOfDivisors = new ExprArray(n+1,1);
21       for (var divisor = 2; divisor &lt;= n; divisor++) {
22           for (var j = divisor + divisor; j &lt;= n; j += divisor) {
23               sumOfDivisors[j] += " + " + divisor;
24           }
25           // At this point everything up to 'divisor' has its sumOfDivisors
26           // expression calculated, so we can determine whether it's perfect
27           // already by evaluating.
28           if (eval(sumOfDivisors[divisor]) == divisor) {
29               print("" + divisor + " = " + sumOfDivisors[divisor]);
30           }
31       }
32       delete sumOfDivisors;
33       print("That's all.");
34   }
</pre>
<p>The line number to PC and back mappings can be tested using the js program with the following script:</p>
<pre class="eval">load("perfect.js");
print(perfect);
dis(perfect);
print();
for (var ln = 0; ln &lt;= 40; ln++) {
    var pc = line2pc(perfect, ln);
    var ln2 = pc2line(perfect, pc);
    print("\tline " + ln + " =&gt; pc " + pc + " =&gt; line " + ln2);
}
</pre>
<p>The result of the for loop over lines 0 to 40 inclusive is:</p>
<pre class="eval">line 0 =&gt; pc 0 =&gt; line 16
line 1 =&gt; pc 0 =&gt; line 16
line 2 =&gt; pc 0 =&gt; line 16
line 3 =&gt; pc 0 =&gt; line 16
line 4 =&gt; pc 0 =&gt; line 16
line 5 =&gt; pc 0 =&gt; line 16
line 6 =&gt; pc 0 =&gt; line 16
line 7 =&gt; pc 0 =&gt; line 16
line 8 =&gt; pc 0 =&gt; line 16
line 9 =&gt; pc 0 =&gt; line 16
line 10 =&gt; pc 0 =&gt; line 16
line 11 =&gt; pc 0 =&gt; line 16
line 12 =&gt; pc 0 =&gt; line 16
line 13 =&gt; pc 0 =&gt; line 16
line 14 =&gt; pc 0 =&gt; line 16
line 15 =&gt; pc 0 =&gt; line 16
line 16 =&gt; pc 0 =&gt; line 16
line 17 =&gt; pc 19 =&gt; line 20
line 18 =&gt; pc 19 =&gt; line 20
line 19 =&gt; pc 19 =&gt; line 20
line 20 =&gt; pc 19 =&gt; line 20
line 21 =&gt; pc 36 =&gt; line 21
line 22 =&gt; pc 53 =&gt; line 22
line 23 =&gt; pc 74 =&gt; line 23
line 24 =&gt; pc 92 =&gt; line 22
line 25 =&gt; pc 106 =&gt; line 28
line 26 =&gt; pc 106 =&gt; line 28
line 27 =&gt; pc 106 =&gt; line 28
line 28 =&gt; pc 106 =&gt; line 28
line 29 =&gt; pc 127 =&gt; line 29
line 30 =&gt; pc 154 =&gt; line 21
line 31 =&gt; pc 154 =&gt; line 21
line 32 =&gt; pc 161 =&gt; line 32
line 33 =&gt; pc 172 =&gt; line 33
line 34 =&gt; pc 172 =&gt; line 33
line 35 =&gt; pc 172 =&gt; line 33
line 36 =&gt; pc 172 =&gt; line 33
line 37 =&gt; pc 172 =&gt; line 33
line 38 =&gt; pc 172 =&gt; line 33
line 39 =&gt; pc 172 =&gt; line 33
line 40 =&gt; pc 172 =&gt; line 33
</pre>
<h5 name="jsconfig.h">jsconfig.h</h5>
<p>Various configuration macros defined as 0 or 1 depending on how <code><a href="/en/JS_VERSION" title="en/JS_VERSION">JS_VERSION</a></code> is defined (as 10 for JavaScript 1.0, 11 for JavaScript 1.1, etc.). Not all macros are tested around related code yet. In particular, JS 1.0 support is missing from SpiderMonkey.</p>
<h5 name="js.cpp.2C_jsshell.msg">js.cpp, jsshell.msg</h5>
<p>The "JS shell", a simple interpreter program that uses the JS API and more than a few internal interfaces (some of these internal interfaces could be replaced by <code>jsapi.h</code> calls). The js program built from this source provides a test vehicle for evaluating scripts and calling functions, trying out new debugger primitives, etc.</p>
<p>A look at the places where <code>jsshell.msg</code> is used in <code>js.cpp</code> shows how error messages can be handled in JSAPI applications. These messages can be localized at compile time by replacing the <code>.msg</code> file; or, with a little modification to the source, at run time.</p>
<p><a href="/En/SpiderMonkey/Introduction_to_the_JavaScript_shell" title="https://developer.mozilla.org/en/introduction_to_the_javascript_shell">More information on the JavaScript shell</a>.</p>
<h5 name="js.msg">js.msg</h5>
<p>SpiderMonkey error messages.</p>
<h5 name="jsarray..2A.2C_jsbool..2A.2C_jdsdate..2A.2C_jsfun..2A.2C_jsmath..2A.2C_jsnum..2A.2C_jsstr..2A">jsarray.*, jsbool.*, jsdate.*, jsfun.*, jsmath.*, jsnum.*, jsstr.*</h5>
<p>These file pairs implement the standard classes and (where they exist) their underlying primitive types. They have similar structure, generally starting with class definitions and continuing with internal constructors, finalizers, and helper functions.</p>
<h5 name="jsobj..2A.2C_jsscope..2A">jsobj.*, jsscope.*</h5>
<p>These two pairs declare and implement the JS object system. All of the following happen here:</p>
<ul> <li>creating objects by class and prototype, and finalizing objects;</li> <li>defining, looking up, getting, setting, and deleting properties;</li> <li>creating and destroying properties and binding names to them.</li>
</ul>
<p>The details of a native object's map (scope) are mostly hidden in <code>jsscope.{{ mediawiki.external('ch') }}</code>.</p>
<h5 name="jsatom.cpp.2C_jsatom.h">jsatom.cpp, jsatom.h</h5>
<p>The atom manager. Contains well-known string constants, their atoms, the global atom hash table and related state, the js_Atomize() function that turns a counted string of bytes into an atom, and literal pool (<code>JSAtomMap</code>) methods.</p>
<h5 name="jsarena.cpp.2C_jsarena.h">jsarena.cpp, jsarena.h</h5>
<p>Last-In-First-Out allocation macros that amortize malloc costs and allow for en-masse freeing. See the paper mentioned in <code>jsarena.h</code>'s major comment.</p>
<h5 name="jsgc.cpp.2C_jsgc.h">jsgc.cpp, jsgc.h</h5>
<p>The garbage collector and tracing routines.</p>
<h5 name="jsinterp..2A.2C_jscntxt..2A.2C_jsinvoke.cpp">jsinterp.*, jscntxt.*, jsinvoke.cpp</h5>
<p>The bytecode interpreter, and related functions such as Call and AllocStack, live in <em>jsinterp.cpp</em>. The JSContext constructor and destructor are factored out into <em>jscntxt.cpp</em> for minimal linking when the compiler part of JS is split from the interpreter part into a separate program.</p>
<p><code>jsinvoke.cpp</code> is a build hack used on some platforms to build <code>js_Interpret</code> under different compiler options from the rest of <code>jsinterp.cpp</code>.</p>
<h5>jstracer.*, nanojit/*</h5>
<p><a class="internal" href="/En/SpiderMonkey/Internals/Tracing_JIT" title="En/SpiderMonkey/Internals/Tracing JIT">The tracing JIT</a>. The interface between the JIT and the rest of SpiderMonkey is conceptually small—the interpreter calls into the trace recorder—but as with everything else, there are tendrils everywhere.</p>
<h5 name="jsemit..2A.2C_jsopcode.tbl.2C_jsopcode..2A.2C_jsparse..2A.2C_jsscan..2A.2C_jsscript..2A">jsemit.*, jsopcode.tbl, jsopcode.*, jsparse.*, jsscan.*, jsscript.*</h5>
<p>Compiler and decompiler modules. The <em>jsopcode.tbl</em> file is a C preprocessor source that defines almost everything there is to know about JS bytecodes. See its major comment for how to use it. For now, a debugger will use it and its dependents such as <em>jsopcode.h</em> directly, but over time we intend to extend <em>jsdbgapi.h</em> to hide uninteresting details and provide conveniences. The code generator is split across paragraphs of code in <em>jsparse.cpp</em>, and the utility methods called on <code>JSCodeGenerator</code> appear in <em>jsemit.cpp</em>. Source notes generated by <em>jsparse.cpp</em> and <em>jsemit.cpp</em> are used in <em>jsscript.cpp</em> to map line number to program counter and back.</p>
<h5 name="jstypes.h">jstypes.h</h5>
<p>Fundamental representation types and utility macros. This file alone among all .h files in SpiderMonkey must be included first by .cpp files. It is not nested in .h files, as other prerequisite .h files generally are, since it is also a direct dependency of most .cpp files and would be over-included if nested in addition to being directly included.</p>
<h5 name="jsbit.h.2C_jslog2.cpp">jsbit.h, jslog2.cpp</h5>
<p>Bit-twiddling routines. Most of the work here is selectively enabling compiler-specific intrinsics such as GCC's <code>__builtin_ctz</code>, which is useful in calculating base-2 logarithms of integers.</p>
<h5 name="jsutil.cpp.2C_jsutil.h">jsutil.cpp, jsutil.h</h5>
<p>The <code>JS_ASSERT</code> macro is used throughout the source as a proof device to make invariants and preconditions clear to the reader, and to hold the line during maintenance and evolution against regressions or violations of assumptions that it would be too expensive to test unconditionally at run-time. Certain assertions are followed by run-time tests that cope with assertion failure, but only where I'm too smart or paranoid to believe the assertion will never fail...</p>
<h5 name="jsclist.h">jsclist.h</h5>
<p>Doubly-linked circular list struct and macros.</p>
<h5 name="jscpucfg.cpp">jscpucfg.cpp</h5>
<p>This standalone program generates <em>jscpucfg.h</em>, a header file containing bytes per word and other constants that depend on CPU architecture and C compiler type model. It tries to discover most of these constants by running its own experiments on the build host, so if you are cross-compiling, beware.</p>
<h5 name="jsdtoa.cpp.2C_jsdtoa.h.2C_dtoa.c">jsdtoa.cpp, jsdtoa.h, dtoa.c</h5>
<p>dtoa.c contains David Gay's portable double-precision floating point to string conversion code, with Permission To Use notice included. jsdtoa.cpp <code>#include</code>s this file.</p>
<h5 name="jshash.cpp.2C_jshash.h.2C_jsdhash.cpp.2C_jsdhash.h">jshash.cpp, jshash.h, jsdhash.cpp, jsdhash.h</h5>
<p>Portable, extensible hash tables. These use multiplicative hash for strength reduction over division hash, yet with very good key distribution over power of two table sizes. jshash resolves collisions via chaining, so each entry burns a malloc and can fragment the heap. jsdhash uses open addressing.</p>
<h5 name="jslong.cpp.2C_jslong.h">jslong.cpp, jslong.h</h5>
<p>64-bit integer emulation, and compatible macros that use intrinsic C types, like <code>long long</code>, on platforms where they exist (most everywhere, these days).</p>
<h5 name="jsprf..2A">jsprf.*</h5>
<p>Portable, buffer-overrun-resistant sprintf and friends. For no good reason save lack of time, the %e, %f, and %g formats cause your system's native sprintf, rather than <code>JS_dtoa()</code>, to be used. This bug doesn't affect SpiderMonkey, because it uses its own <code>JS_dtoa()</code> call in <code>jsnum.cpp</code> to convert from double to string, but it's a bug that we'll fix later, and one you should be aware of if you intend to use a <code>JS_*printf()</code> function with your own floating type arguments - various vendor sprintf's mishandle NaN, +/-Inf, and some even print normal floating values inaccurately.</p>
<h5 name="prmjtime.c.2C_prmjtime.h">prmjtime.c, prmjtime.h</h5>
<p>Time functions. These interfaces are named in a way that makes local vs. universal time confusion likely. Caveat emptor, and we're working on it. To make matters worse, Java (and therefore JavaScript) uses "local" time numbers (offsets from the epoch) in its Date class.</p>
<h5 name="jsfile.cpp.2C_jsfile.h.2C_jsfile.msg">jsfile.cpp, jsfile.h, jsfile.msg</h5>
<p>Obsolete. Do not use these files.</p>
<h5 name="Makefile.in.2C_build.mk">Makefile.in, build.mk</h5>
<p>Mozilla makefiles. If you're building Gecko or Firefox, the larger build system will use these files. They are also used for current standalone builds.</p>
<h5 name="Makefile.ref.2C_rules.mk.2C_config.mk.2C_config.2F.2A">Makefile.ref, rules.mk, config.mk, config/*</h5>
<p>Obsolete SpiderMonkey standalone makefiles from 1.8 and earlier. See <a href="/En/SpiderMonkey/Build_Documentation#Building_SpiderMonkey_1.8_or_earlier" title="En/SpiderMonkey/Build Documentation#Building SpiderMonkey 1.8 or earlier">SpiderMonkey Build Documentation</a>.</p>
<h4>See also</h4>
<p><a href="/jsd" title="jsd">jsd</a></p>
Revert to this revision