SpiderMonkey 1.8.5 is the JavaScript engine that shipped in Firefox 4.0. It is much faster than SpiderMonkey 1.8, implements ES-5 (ECMA 262, 5th Edition), and contains many new language and API features, described in detail below.

Platform support

SpiderMonkey 1.8.7 is supported on all the platforms where Firefox 10 runs.

SpiderMonkey 1.8.7 includes type inference, which boosts the speed of the JägerMonkey JIT by about 30% over version 1.8.5. Type inference largely obviates TraceMonkey, so the TraceMonkey JIT has been removed. The JIT is supported only on x86, x86_64 and ARM architectures. On other platforms, the JIT is simply disabled; JavaScript code runs in an interpreter, as in previous versions. It's the same language, just not as fast.

Migrating to SpiderMonkey 1.8.7

This covers migrating from version 1.8.5. See the 1.8.5 release notes for information on migrating from earlier versions.

The following features in earlier versions of SpiderMonkey have been dropped.

XXX is there anything here?

SpiderMonkey 1.8.7 is not binary-compatible with previous releases, nor is it source-code compatible. Many JSAPI types, functions, and callback signatures have changed, though most of them still have the same names and do the same things. Applications will need significant changes, but most of those changes will be detected by the C/C++ compiler, so they are easy to detect and updating the code is a fairly straightforward job. Here is a list of the most significant changes.

XXX is there anything here?

These and other changes are explained in detail below.

New JavaScript language features

XXX needs updating

JavaScript 1.8.5 adds support for ECMAScript Edition 5, including ES5 strict mode. For details, see New in JavaScript 1.8.5. Note that there are a very small number of incompatibilities between ES5 and and ES3, the version of ECMAScript supported by SpiderMonkey versions 1.5 through 1.8. These are discussed in Annex E of the ES5 specification.

SpiderMonkey 1.8.5 also ships with js-ctypes, a foreign-function interface for privileged JavaScript. To enable js-ctypes in your embedding, you must configure with the --enable-ctypes option and choose one of the configuration options to enable NSPR (e.g. --with-system-nspr).

XXX all sections below need updating

Garbage Collection

SpiderMonkey 1.8.5 introduces a conservative stack-scanning garbage collector. Unlike the exact garbage collector, the new garbage collector will scan the C stack and registers in your embedding, looking for bits that it can treat as potential GC roots. The approach eliminates the need for the JS_EnterLocalRootScope API, and in many cases the need to explicitly root GC things or use the "root as you go" approach popular with earlier SpiderMonkey releases. Since this is a conservative collector, it will often find "garbage" addresses which can trigger warnings from certain code analysis tools. If you are running valgrind on your embedding, be sure to build SpiderMonkey with the --enable-valgrind option to suppress superflous error messages triggered by the garbage collector. This also means that objects will be finalized in a non-deterministic order in SpiderMonkey 1.8.5. This is not a bug, and, any embedding which depends upon deterministic finalization is fatally flawed.

Typed Rooting API

The rooting API has been changed from an error-prone void ** interface to an interface which accepts pointers to specific types. JS_AddRoot has been replaced by JS_AddObjectRoot, JS_AddValueRoot and JS_AddStringRoot; similar changes were made for JS_AddNamedRoot and JS_RemoveRoot. Since jsdoubles are now stored in the jsval, instead of on the heap, we no longer need to define roots for them.

Compartments

SpiderMonkey 1.8.5 introduces the concept of compartments. A compartment is a global object, a context, and a set of related objects with no outside references (CrossCompartment wrappers excepted). The new garbage collector can perform per-container garbage collection, which can be a significant performance improvement for certain workloads. No compartment may execute JS code or call into JSAPI on two OS threads at the same time. For more information, see SpiderMonkey compartments.

Type Changes

jsval

The base data type, jsval, which represents all possible values in JavaScript, has changed from 32- to 64-bits wide, and the underlying representation has changed from a C integer type to a C struct. This change to a struct means that certain tricks, such as writing switch statements in C with jsval cases are no longer legal. Additionally, because not all fields are used by all jsvals, it is no longer safe to compare jsvals as though they were C values. Instead, jsvals should be converted to their C equivalents with the appropriate JSVAL_TO_* macro and then compared.

JSAPI no longer represents floating-point numbers (and integers more than 31 bits long) as pointers to jsdouble; instead, the jsdouble value is directly stored in the jsval. This affects macros like DOUBLE_TO_JSVAL and JSVAL_TO_DOUBLE, which now operate directly on jsdouble rather than jsdouble pointers.

Previous SpiderMonkey versions usually represented integer values smaller than 2^31 as jsvals encoding jsint; e.g. so that JSVAL_IS_INT was true. While this was never specified behaviour, it is no longer true; numeric values which are integers are frequently encoded as jsdouble inside the jsval. Embedders must be careful when converting numbers from jsvals into C. Note also that SpiderMonkey can now fit a full 32-bit integer (jsint) inside a jsval without promoting to a jsdouble.

JSExtendedClass

JSExtendedClass has been removed from the API entirely.

jsid

Previous SpiderMonkey versions could freely interchange jsid and jsval. They are no longer compatible; using JS_ValueToId and JS_IdToValue to convert between the two is mandatory.

JSNative, JSFastNative

Previous versions of JSAPI supported two types of native functions -- JSNative and JSFastNative. The so-called "Slow Natives" are no longer supported; as such JSFastNative has been renamed to JSNative and relevant interfaces have been updated accordingly. Embedders converting functions from old-JSNative to new-JSNative (JSFastNative) should study the JSFastNative documentation thoroughly, and pay particular that they do not reference negative indices of argv in SpiderMonkey 1.8.5; the JS_CALLEE, JS_THIS, etc. macros must be used instead. See bug 581263.

Global Objects

Global objects have been specialized, and must be be created with either JS_NewGlobalObject or JS_NewCompartmentAndGlobalObject. JS_NewObject and JS_NewObjectWithGivenProto remain the correct APIs for creating other objects. Global objects must also have the JSCLASS_GLOBAL_FLAGS flag set. Merely setting JSCLASS_IS_GLOBAL is insufficient.

New C++ helpers

While JSAPI remains a C API, the engine is now implemented in C++. Some C++ helpers have been introduced into the API, to help embedders writing C++ projects. Please note that SpiderMonkey reserves the JS:: namespace for itself.

Obsolete APIs

Deleted APIs

API changes

Operation callback

JS_SetOperationCallback was introduced in JS 1.8.0, replacing the branch callback, in anticipation of the addition of the tracing JIT (TraceMonkey). The interface was finalized only after JS 1.8.0 shipped, with bug 477187. The primary change in this interface is that it no longer counts operations; embedders are expected find another mechanism (such as a watchdog thread) to trigger regular callbacks, via JS_TriggerOperationCallback.

Garbage collection

JS_MarkGCThing was changed in bug 549143 to mark jsvals rather than void pointers (GC root addresses), improving the typed rooting API which was introduced in bug 565157. A conservative stack-scanning collector was also added for SpiderMonkey 1.8.5, making the *LocalRootScope APIs obsolete; they are now NOPs. Bug 614138 introduces a C++ JS::Anchor<> template class to help tie lexical scope to the conservative GC for cases where the compiler might optimize away important stack/register roots (such as when we access the jschars in a JSString). A C analogue, JS_AnchorPtr, was introduced with bug 630209.

Bug 630209 also removed the need for JS_NewScriptObject, by modifying the script compilation interfaces to handle the creation and management of the object wrapper directly; similarly, the script execution interfaces now accept a JSObject pointer than a pointer to JSScript. Affected interfaces are:

Native functions

JSNatives now use the "fast native" calling convention; see bug 581263. The JS_FS macro has been adjusted, losing its third (unused) argument. JS_IsConstructing, used to differentiate between calls to native constructors with and without the new keyword, now takes a pointer to the native's vp, along with the native's context pointer, to figure out how the function was called.

JavaScript shell changes

There are many new built-in functions in the JavaScript shell, mostly useful for testing SpiderMonkey. The scatter function has been removed, and a shell worker class (similar to HTML DOM Workers) has been added.

Known Issues

Mac OS X 10.5 (Leopard) and XCode 3.2

SpiderMonkey will not build with certain builds of Apple's GCC 4.2 C++ compiler. To check what version you are running, issue the command /usr/bin/g++-4.2 -v from a Terminal window. The following builds are known to not work:

i686-apple-darwin9-g++-4.2.1 (GCC) 4.2.1 (Apple Inc. build 5574)

To work around this issue, either upgrade your XCode or use an alternate version of GCC, such as the one that shipped with Leopard. To select an alternate C++ compiler, invoke configure thus:

CXX=/usr/bin/g++-4.0 /path/configure --my-configuration-options

js-config

The new configure-based build system does not correctly generate the js-config script on many platforms, nor when js-ctypes are enabled. If you are building your project with a GNU-make based build system, the following workaround can be integrated into your build system to generate the correct LDFLAGS, with a strong likelihood that it will work with future versions when js-config is fixed:

Future Direction

The SpiderMonkey 1.8.5 source release includes an experimental library versioning scheme. This versioning scheme will not be rolled back into the upstream Mozilla source tree(s), and may not be used in future source releases. Comments in bug 628723 with regard to its usefulness are appreciated. Bugs with the source release tar ball should be copied to wes@page.ca.

SpiderMonkey embedders should also be aware that

Mozilla has no plans to keep the JSAPI, nor the JSDBGAPI stable for embedders. We have chosen to concentrate on performance and correctness as primary concerns instead.