SpiderMonkey 1.8

Known issues

SpiderMonkey 1.8 has one known significant regression from 1.7.

• In JS_THREADSAFE builds, some objects are not safe to be shared among threads. This includes iterators and generators (bug 349263) and arrays (bug 417501). In short, applications that share objects among threads in such a way that two threads could access an array, iterator, or generator object at the same time should not use SpiderMonkey 1.8.

There is a minor known bug in the new JavaScript 1.8 functionality.  

• When JavaScript 1.8 support is enabled, the parser accepts some incorrect programs by inserting a semicolon where it should instead throw a SyntaxError (bug 384758). This bug will be fixed in 1.8.1.

Migrating to SpiderMonkey 1.8

SpiderMonkey 1.8 is not binary-compatible with previous releases. It is source-compatible with SpiderMonkey 1.7 though, which means you can probably just recompile and relink your application. A handful of changes are not backwards-compatible:

• The result of assigning to a property with a setter has changed (bug 312354). In JavaScript 1.7 and earlier, x = [].length = "7"; would store the number 7 in x. Now this statement stores the string "7" in x. The new behavior conforms to the ECMAScript standard, ECMA 262-3 §11.13.1.
• In certain cases, the JavaScript engine no longer calls JSClass.resolve callbacks repeatedly, as it did in previous versions. Specifically, if a property lookup first calls a resolve hook which does not define the property, then finds the property on a prototype, that result can be cached. Future lookups for the same property on the same sort of object may bypass the resolve hook.
• JS_NewDouble is now deprecated. Use JS_NewDoubleValue.
• The security APIs JS_SetCheckObjectAccessCallback, JS_SetPrincipalsTranscoder, and JS_SetObjectPrincipalsFinder are still present but are deprecated in this release. In SpiderMonkey 1.8.1 they will be removed and replaced with a new set of APIs (JS_GetSecurityCallbacks and friends, bug 451729).
• js.mak, an old Windows-specific nmake file, has been deleted. It hasn't worked for a long time. It is fairly easy to create a Microsoft Visual Studio project file for SpiderMonkey 1.8 from scratch. (If you would like to contribute and maintain a project file, please feel free to contact the SpiderMonkey team via email, bugzilla, or IRC.) Alternatively, you can install MozillaBuild and run the command make -f Makefile.ref in the js/src directory.

SpiderMonkey 1.8 does not include the new TraceMonkey JIT or the configure-based build system, both of which are (a) pretty darn awesome and (b) coming in SpiderMonkey 1.8.1.

On to the fun stuff.

New JavaScript language features

JavaScript 1.8 adds Array.reduce() and reduceRight(), expression closures, and generator expressions. There is also one obscure non-backwards-compatible change. For details, see New in JavaScript 1.8.

New JSAPI features

It has been a couple years since SpiderMonkey 1.7 was released, and many improvements have been made to the JSAPI. However, one of the most important advances for JSAPI application developers is that the documentation is much improved. See the JSAPI User Guide and the JSAPI Reference.

• Native functions may implement the new callback signature JSFastNative instead of JSNative. JSFastNative can be significantly faster, but applications that use SpiderMonkey's fine-grained security features should heed the warning in its API documentation.
• New macros JS_FS, JS_FN, and JS_FS_END are recommended for populating JSFunctionSpec arrays.
• JS_NewObjectWithGivenProto is exactly like JS_NewObject except that it doesn't use a default prototype object if you pass NULL. Instead the object is created with no prototype.
• JS_AlreadyHasOwnProperty and friends are new functions for examining an object without triggering resolve hooks.
• It was possible to configure SpiderMonkey 1.7 to treat C/C++ char strings as UTF-8 by compiling with a non-default compiler option. In SpiderMonkey 1.8, it is no longer necessary to make a special build to get this behavior. Applications can turn on UTF-8 at run time by calling JS_SetCStringsAreUTF8.
• JS_EncodeString is a new variation on JS_GetStringBytes that returns a newly allocated, writable buffer which the application must JS_free.
• JS_ReportAllocationOverflow can be used (instead of JS_ReportOutOfMemory) to indicate that the script is trying to do something that would require more memory than the implementation is designed to handle. The main difference is that JS_ReportAllocationOverflow throws an exception which the application may catch.
• JS_ThrowStopIteration throws the appropriate StopIteration exception object for the given context.
• Two new context options can be used with JS_SetOptions: JSOPTION_RELIMIT, which causes extremely long-running regular expression searches to fail with an error, and JSOPTION_ANONFUNFIX, which bans anonymous functions from appearing anyplace where a statement could appear, such as in the argument to eval().
• Functions that were JS_THREADSAFE-only in SpiderMonkey 1.7 (JS_BeginRequest, for example) are now present, but do nothing, in non-JS_THREADSAFE builds. This is to help applications share and reuse code regardless of whether they use threads.
• There are two new JSExtendedClass hooks, JSExtendedClass.iteratorObject and JSExtendedClass.wrappedObject. Both are documented but obscure.

Many new memory management features have been added as well.

• The new function JS_SetScriptStackQuota limits the size of the JavaScript stack.
• Two new functions, JS_SetGCZeal and JS_DumpHeap, aim to help developers debug GC-related problems. These functions are only present in DEBUG builds. JS_SetGCZeal is especially helpful. When GC zeal is enabled, GC happens extremely frequently. This makes GC-related problems easier to reproduce, reveals GC problems that you may not have noticed before, and causes GC-safety bugs to surface much closer to their cause. JS_DumpHeap dumps parts of the GC heap and can help detect leaks.
• A new GC parameter, JSGC_STACKPOOL_LIFESPAN, controls how eagerly SpiderMonkey returns unused memory back to the system.
• The new function JS_SetExtraGCRoots provides another way to protect values from garbage collection.
• There is a new set of APIs for integrating SpiderMonkey's garbage collector with other memory management systems. These APIs are undocumented but fairly stable. The APIs include the new JSTraceOp callback.

New JavaScript shell functions

There are a few new built-in functions in the JavaScript shell, mostly useful for testing.  countHeap, dumpHeap, gcparam, gczeal, and stackQuota are related to memory management.  sleep and scatter, defined in JS_THREADSAFE builds only, are for testing thread-safety.