SpiderMonkey 1.8.7

DRAFT IN PROGRESS - This is a draft, and right now it's mostly just a copy of the 1.8.5 release notes.

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 APIs

• JS_ASSERT_STRING_IS_FLAT
• JS_AddGCThingRoot
• JS_AddNamedGCThingRoot
• JS_AddNamedObjectRoot
• JS_AddNamedStringRoot
• JS_AddNamedValueRoot
• JS_AddObjectRoot
• JS_AddStringRoot
• JS_AddValueRoot
• JS_AlreadyHasOwnPropertyById
• JS_AnchorPtr
• JS_BeginJSONParse (removed in future releases, replaced with JS_ParseJSON)
• JS_CompileFileHandleForPrincipalsVersion
• JS_CompileScriptForPrincipalsVersion
• JS_CompileUCFunctionForPrincipalsVersion
• JS_CompileUCScriptForPrincipalsVersion
• JS_ConsumeJSONText (removed in future releases, replaced with JS_ParseJSON)
• JS_DecompileScriptObject
• JS_DeepFreezeObject
• JS_DefineFunctionById
• JS_DefineOwnProperty
• JS_DefinePropertyById
• JS_DeletePropertyById
• JS_DeletePropertyById2
• JS_DoubleIsInt32
• JS_EncodeStringToBuffer
• JS_EnterCrossCompartmentCall
• JS_EvaluateScriptForPrincipalsVersion
• JS_EvaluateUCScriptForPrincipalsVersion
• JS_ExecuteRegExp
• JS_ExecuteRegExpNoStatics
• JS_ExecuteScriptVersion
• JS_FORGET_STRING_FLATNESS
• JS_FileEscapedString
• JS_FinishJSONParse (removed in future releases, replaced with JS_ParseJSON)
• JS_FlatStringEqualsAscii
• JS_FlattenString
• JS_FlushCaches
• JS_FreezeObject
• JS_GetCompartmentPrivate
• JS_GetEmptyString
• JS_GetFlatStringChars
• JS_GetGCParameter
• JS_GetGCParameterForThread
• JS_GetGlobalForScopeChain
• JS_GetInternedStringChars
• JS_GetInternedStringCharsAndLength
• JS_GetOwnPropertyDescriptor
• JS_GetPropertyAttrsGetterAndSetterById
• JS_GetPropertyById
• JS_GetPropertyByIdDefault
• JS_GetPropertyDefault
• JS_GetPropertyDescriptorById
• JS_GetRuntimeSecurityCallbacks
• JS_GetSecurityCallbacks
• JS_GetStringCharsAndLength
• JS_GetStringCharsZ
• JS_GetStringCharsZAndLength
• JS_GetStringEncodingLength
• JS_HasPropertyById
• JS_InitCTypesClass
• JS_InternJSString
• JS_IsConstructing_PossiblyWithGivenThisObject
• JS_IsExtensible
• JS_IsInRequest
• JS_LeaveCrossCompartmentCall
• JS_LookupPropertyById
• JS_LookupPropertyWithFlagsById
• JS_New
• JS_NewCompartmentAndGlobalObject
• JS_NewDateObject
• JS_NewDateObjectMsec
• JS_NewFunctionById
• body

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.

• JSAutoRequest
• JSAutoSuspendRequest
• JSAutoCheckRequest
• JSAutoEnterCompartment
• JS::Anchor<>
• JS::Call

Obsolete APIs

• JS_ClearNewbornRoots
• JS_EnterLocalRootScope
• JS_LeaveLocalRootScope
• JS_LeaveLocalRootScopeWithResult
• JS_ForgetLocalRoot
• JS_NewGrowableString

Deleted APIs

• JS_GetScopeChain use JS_GetGlobalForScopeChain

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.

RegExp APIs

JS_ClearRegExpStatics, JS_NewRegExpObject, JS_NewRegUCExpObject, and 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.

Property accessors

JS_PropertyStub, 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.

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:

• JS_CompileScript
• JS_CompileScriptForPrincipals
• JS_CompileScriptForPrincipalsVersion
• JS_CompileUCScript
• JS_CompileUCScriptForPrincipals
• JS_CompileUCScriptForPrincipalsVersion
• JS_CompileFile
• JS_CompileFileHandle
• JS_CompileFileHandleForPrincipals
• JS_CompileFileHandleForPrincipalsVersion
• JS_CompileFunction
• JS_CompileFunctionForPrincipals
• JS_CompileUCFunctionForPrincipalsVersion
• JS_ExecuteScript
• JS_ExecuteScriptVersion

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.

Strings

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_NewString, JS_GetStringBytes, and JS_GetStringChars were removed, replaced by fallible interfaces like JS_GetStringCharsZAndLength and JS_EncodeStringToBuffer (not an exhaustive list). 

Numbers

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 jsints, not 64-bit integers).  The jsval now also stores jsdoubles directly, rather than storing them on the heap. The JSVAL_TO_DOUBLE and DOUBLE_TO_JSVAL macros have been updated to work directly on jsdoubles rather than their pointers, and the JS_NewDoubleValue and JS_NewDouble interfaces have been removed.

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:

JS_CONFIG        ?= /path/to/js-config
UNAME_SYSTEM      = $(shell uname -s)
JSAPI_LDFLAGS     = $(shell $(JS_CONFIG) --libs)
ifeq ($(UNAME_SYSTEM),Darwin)
JSAPI_LDFLAGS    := $(filter -l%,$(JSAPI_LDFLAGS)) $(filter -L%,$(JSAPI_LDFLAGS))\
        $(filter -%_namespace,$(JSAPI_LDFLAGS))\
        $(filter -Wl%,$(JSAPI_LDFLAGS))
JSAPI_LDFLAGS    := $(filter-out $(MOZJS_INSTALL_NAME_OPT),$(JSAPI_LDFLAGS))
endif
JSAPI_LDFLAGS    := $(filter-out %libffi.a,$(JSAPI_LDFLAGS))
LDFLAGS          += $(JSAPI_LDFLAGS)

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