This article covers features introduced in SpiderMonkey 1.8.5
Note that version 1.8.5 is outdated. The latest version of SpiderMonkey can always be found on the source download page.
—22 March 2011
SpiderMonkey 1.8.5 is supported on all the platforms where Firefox 4 runs.
Migrating to SpiderMonkey 1.8
The following features in earlier versions of SpiderMonkey have been dropped.
- Support for extended class methods (in particular, JSEqualityOp) has been removed.
- Multithreaded JS programs that race against the same objects are now explicitly not supported. Multithreaded programs are allowed, but each thread must operate on objects in a separate compartment, isolated from the other threads.
- The old build system (using Makefile.ref) is no longer supported. SpiderMonkey 1.8.5 includes a new
configure-based build system, introduced shortly after active development on the engine moved from CVS to Mercurial.
SpiderMonkey 1.8.5 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.
- Previous versions of SpiderMonkey supported two types of native functions: JSNative and JSFastNative. All support for the slow native function type has been removed, and the fast signature has been renamed to JSNative. Embeddings that defined JSNatives in previous versions must update all those functions to the new signature.
- Getters and setters of type JSPropertyOp took an id parameter of type jsval. The type of the parameter has been changed to jsid. Many getters and setters simply ignore the id anyway; if the value is needed, use JS_IdToValue.
- The type of setters has changed from JSPropertyOp to JSStrictPropertyOp (to accomodate ES5 strict mode). To migrate, simply add a
JSBool strictparameter to each setter function. It is safe for the setter to ignore the value of the argument.
- The rooting APIs (JS_AddRoot, JS_RemoveRoot, etc.) have been replaced with a family of type-safe functions (JS_AddStringRoot, JS_RemoveStringRoot, etc.) that are easier to use correctly.
- JS_NewDouble, JS_NewDoubleValue, and JS_NewNumberValue are gone. Instead use DOUBLE_TO_JSVAL, INT_TO_JSVAL, and UINT_TO_JSVAL, which are faster and can't fail.
- JS_GetStringBytes and JS_GetStringChars are gone. There is no longer an infallible way to examine string characters. Applications must use JS_GetStringCharsAndLength or JS_EncodeString/JS_free and check for errors.
These and other changes are explained in detail below.
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.
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.
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 has been removed from the API entirely.
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.
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 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 APIs
JS_BeginJSONParse (removed in future releases, replaced with JS_ParseJSON)
JS_ConsumeJSONText (removed in future releases, replaced with JS_ParseJSON)
JS_FinishJSONParse (removed in future releases, replaced with JS_ParseJSON)
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.
JS_AddNamedRoot– use JS_Add*Root
JS_AddNamedRootRT– use JS_Add*Root
JS_AddRoot– use JS_Add*Root
JS_ClearNewbornRoots– no longer needed
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_SetRegExpInput now receive a pointer to the global object. This change was made in bug 571355 to move the regexp statics out of the context, to simplify cross compartment wrappers.
JS_ResolveStub, and user-defined functions of type
JSPropertyOp (e.g. getters and setters) changed from passing
jsvals to passing
jsid as part of bug 549143. This bug introduced "fat" (64-bit) unboxed valued into the engine.
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:
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.
JS_CompareStrings received a new function signature with bug 609440, allowing us to correctly propagate exceptions when the underlying functions to retrieve the characters in the string failed. Additionally,
JS_GetStringChars were removed, replaced by fallible interfaces like
JS_EncodeStringToBuffer (not an exhaustive list).
SpiderMonkey 1.8.5 now stores integers up to 32-bits in the jsval. This means that the
INT_FITS_IN_JSVAL macro is always returns true (be careful to only use this macro with
s, not 64-bit integers). The jsval now also stores
s directly, rather than storing them on the heap. The
DOUBLE_TO_JSVAL macros have been updated to work directly on
s rather than their pointers, and the
JS_NewDouble interfaces have been removed.
scatter function has been removed, and a shell worker class (similar to HTML DOM Workers) has been added.
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
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:
JS_CONFIG ?= /path/to/js-config
UNAME_SYSTEM = $(shell uname -s)
JSAPI_LDFLAGS = $(shell $(JS_CONFIG) --libs)
JSAPI_LDFLAGS := $(filter -l%,$(JSAPI_LDFLAGS)) $(filter -L%,$(JSAPI_LDFLAGS))\
JSAPI_LDFLAGS := $(filter-out $(MOZJS_INSTALL_NAME_OPT),$(JSAPI_LDFLAGS))
JSAPI_LDFLAGS := $(filter-out %libffi.a,$(JSAPI_LDFLAGS))
LDFLAGS += $(JSAPI_LDFLAGS)
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
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.
- The team is considering the removal of TinyIDs
- JS_THREADSAFE is going away, with future versions supporting only thread-safe builds
- A new debugging API is on the way to replace JSD.
Release Notes Errata
This is a list of changes which need to be made to the release notes ASAP. Feel free to fix any problems you spot -- this is a Wiki!
- jsxdrapi changes were missed
- JSStrictPropertyOp for setters (affects JSClass) - maybe general notes about ES5 strict mode changes in JSAPI
- Tricks like argv[-2] not guaranteed to work any more; is JS_CALLEE or similar instead