Table of Contents

• Introduction
• Build instructions
• Debugging notes
• Naming and coding conventions
• Using the JS API
• Design walk-through
• Additional Resources (links, API docs, and newsgroups)

Introduction

JSRef builds a library or DLL containing the JavaScript runtime (compiler, interpreter, decompiler, garbage collector, atom manager, standard classes). It then compiles a small "shell" program and links that with the library to make an interpreter that can be used interactively and with test .js files to run scripts.  The code has no dependencies on the rest of the Mozilla codebase.

Quick start tip: skip to "Using the JS API" below, build the js shell, and play with the object named "it" (start by setting 'it.noisy = true').

Build instructions

To build the standalone JavaScript engine, see the SpiderMonkey build documentation page.

To build within the browser, use the Mozilla build documentation instead.

Debugging notes

• To turn on GC instrumentation, define JS_GCMETER.
• To dump the JS heap use the JS_DumpHeap API, available in DEBUG builds. For an example of how to call it, see the DumpHeap function in js.cpp.
• To turn on the arena package's instrumentation, define JS_ARENAMETER.
• To turn on the hash table package's metering, define JS_HASHMETER.

Naming and coding conventions

• Public function names begin with JS_ followed by capitalized "intercaps", e.g. JS_NewObject.
• Extern but library-private function names use a js_ prefix and mixed case, e.g. js_SearchScope.
• Most static function names have unprefixed, mixed-case names: GetChar.
• But static native methods of JS objects have lowercase, underscore-separated or intercaps names, e.g., str_indexOf.
• And library-private and static data use underscores, not intercaps (but library-private data do use a js_ prefix).
• Scalar type names are lowercase and js-prefixed: jsdouble.
• Aggregate type names are JS-prefixed and mixed-case: JSObject.
• Macros are generally ALL_CAPS and underscored, to call out potential side effects, multiple uses of a formal argument, etc.
• Four spaces of indentation per statement nesting level.
• Tabs are taken to be eight spaces, and an Emacs magic comment at the top of each file tries to help. If you're using MSVC or similar, you'll want to set tab width to 8, and help convert these files to be space-filled. Do not add hard tabs to source files; do remove them whenever possible.
• DLL entry points have their return type expanded within a JS_PUBLIC_API() macro call, to get the right Windows secret type qualifiers in the right places for all build variants.
• Callback functions that might be called from a DLL are similarly macroized with JS_STATIC_DLL_CALLBACK (if the function otherwise would be static to hide its name) or JS_DLL_CALLBACK (this macro takes no type argument; it should be used after the return type and before the function name).

Using the JS API

The core JSAPI documentation is hosted on the Mozilla Developer Center.

• The JSAPI User Guide explains the basic JSAPI concepts and includes large chunks of sample code.

• The JSAPI Phrasebook shows the JSAPI translation of some commonly used JavaScript expressions and statements.

• The JSAPI Reference contains detailed documentation for each JSAPI feature.

Debugging API

Design walk-through

JS "JavaScript Proper"

JavaScript uses untyped bytecode and runtime type tagging of data 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 boolean value (if the low bit is clear). Tagged pointers all refer to 8-byte-aligned things in the GC heap.

Objects consist of a possibly shared structural description, called the map or scope; and unshared property values in a vector, called the slots. Object properties are associated with nonnegative integers stored in jsval's, or with atoms (unique string descriptors) if named by an identifier or a non-integral index expression.

Scripts contain bytecode, source annotations, and a pool of string, number, and identifier literals. Functions are objects that extend scripts or native functions with formal parameters, a literal syntax, and a distinct primitive type ("function").

The compiler consists of a recursive-descent parser and a random-logic rather than table-driven lexical scanner. Semantic and lexical feedback are used to disambiguate hard cases such as missing semicolons, assignable expressions ("lvalues" in C parlance), etc. The parser generates bytecode as it parses, using fixup lists for downward branches and code buffering and rewriting for exceptional cases such as for loops. It attempts no error recovery. The interpreter executes the bytecode of top-level scripts, and calls itself indirectly to interpret function bodies (which are also scripts). 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, all API and almost all other functions in JSRef take a JSContext pointer as their first argument.

The decompiler 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.

The GC is a mark-and-sweep, non-conservative (exact) collector. It can allocate only fixed-sized things -- the current size is two machine words. It is used to hold JS object 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.

An important point about the GC's "exactness": you must add roots for new objects created by your native methods if you store references to them into a non-JS structure in the malloc heap or in static data. Also, if you make a new object in a native method, but do not store it through the rval result parameter (see math_abs in the "Using the JS API" section above) so that it is in a known root, the object is guaranteed to survive only until another new object is created. Either lock the first new object when making two in a row, or store it in a root you've added, or store it via rval. See the GC tips document for more.

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 in JSRef: 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.

Native objects and methods for arrays, booleans, dates, functions, numbers, and strings are implemented using the JS API and certain internal interfaces used as "fast paths".

In general, errors are signaled by false or unoverloaded-null return values, and are reported using JS_ReportError() or one of its variants by the lowest level in order to provide the most detail. Client code can substitute its own error reporting function and suppress errors, or reflect them into Java or some other runtime system as exceptions, GUI dialogs, etc..

File walk-through (OUT OF DATE!)

jsapi.c, jsapi.h

jspubtd.h, jsprvtd.h

jsdbgapi.c, jsdbgapi.h

• 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

js.c

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

jsobj.*, jsscope.*

• 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.

jsatom.c, jsatom.h

jsgc.c, jsgc.h

jsinterp.*, jscntxt.*

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

jstypes.h, jslog2.c

jsarena.c, jsarena.h

jsutil.c, jsutil.h

jsclist.h

jscpucfg.c

prdtoa.c, prdtoa.h

prhash.c, prhash.h

prlong.c, prlong.h

jsprf.*

prmjtime.c, prmjtime.h

Additional Resources (links, API docs, and newsgroups)

• http://developer.mozilla.org/en/docs/JavaScript
• http://developer.mozilla.org/en/docs/SpiderMonkey
• news://news.mozilla.org/mozilla.dev.tech.js-engine