SpiderMonkey 31

  • Revision slug: SpiderMonkey/31
  • Revision title: SpiderMonkey 31
  • Revision id: 466089
  • Created:
  • Creator: sunfish
  • Is current revision? No
  • Comment

Revision Content

{{ draft() }}

These release notes are an incomplete draft and will remain so until SpiderMonkey 31 is released.

The Mozilla JavaScript team is pleased to announce the release of SpiderMonkey 31. You can download full source code here: http://ftp.mozilla.org/pub/mozilla.org/js/mozjs31.0.0.tar.gz (MD5 checksum: INSERT-CHECKSUM-HERE).

SpiderMonkey 31 is the JavaScript engine that shipped in Firefox 31. It continues to improve performance over previous SpiderMonkey releases, with a significantly improved garbage collector and other features.  It also contains new language and API features described in detail below.

Please let us know about your experiences with this release by posting in the mozilla.dev.tech.js-engine newsgroup. Or file bugs at bugzilla.mozilla.org under Product: Core, Component: JavaScript engine.

—INSERT-ACTUAL-RELEASE-DATE-HERE

Platform support

SpiderMonkey 31 is supported on all the platforms where Firefox 31 runs.  Compiling it requires a C++ compiler, and the JSAPI can only be used from C++ code.  If you are compiling with Microsoft's Visual Studio, note that the minimum supported version is MSVC10/2010: MSVC8/9 support has been dropped.

SpiderMonkey 31 includes a just-in-time compiler (JIT) that compiles JavaScript to machine code, for a significant speed increase. It is supported on x86, x86_64, and ARM architectures. On some other platforms (SPARC, MIPS), the JIT is provided but not supported.  On all 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 31

The first change most embedders will notice is that SpiderMonkey must now be initialized before it can be used, using the newly-repurposed JS_Init method.  After this method is called, normal JSAPI operations are permitted.  When all JSAPI operation has completed, the corresponding JS_ShutDown method (currently non-mandatory, but highly recommended as it may become mandatory in the future) uninitializes SpiderMonkey, cleaning up memory and allocations performed by JS_Init.

A major change to SpiderMonkey in 31 is that its APIs support a moving garbage collector.  This entailed changing the vast majority of the JSAPI from raw types, such as JS::Value or JS::Value*, to JS::Handle and JS::MutableHandle template types that encapsulate access to the provided value/string/object or its location.  The JS::Handle<JS::Value> and JS::MutableHandle<JS::Value> classes have been specialized to implement the same interface as JS::Value, for simplicity and to ease migration pain.  Changes to introduce handles to the JSAPI are not individually documented, because of the breadth of the changes involved.

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

  • XXX list removed features here

SpiderMonkey 31 is not binary-compatible with previous releases, nor is it source-code compatible. Many JSAPI types, functions, and callback signatures have changed, though most functions that have changed still have the same names and implement essentially unchanged functionality. 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:

  • Many of the garbage collector changes require type signature changes to JSAPI methods: specifically introducing JS::Rooted, JS::Handle, and JS::MutableHandle types.  These types, with the appropriate parametrizations, can roughly be substituted for plain types of GC things (values, string/object pointers, etc.).
  • The JSBool type has been removed, along with the corresponding JS_TRUE and JS_FALSE constants.  They have been replaced by bool, true, and false respectively.
  • Many JSClass and js::Class instances are now explicitly const, and several APIs have been updated to use const JSClass * and const js::Class * pointers.

These and other changes are explained in detail below.

New JavaScript language features

JavaScript 31 includes significant updates to language features, yo.

New C APIs

  • JS_Init is a new function which must be used to initialize the JS engine before any JSRuntimes are created or other JSAPI methods are called.  This method pairs with the existing (currently non-mandatory) JS_ShutDown method, which uninitializes the JS engine after all runtimes have been destroyed.
  • JS_SetICUMemoryFunctions is a new function which can be used to set the allocation and deallocation functions used by the ICU internationalization library.  This is unlikely to be of interest to embedders unless you are doing detailed memory profiling.  It must be called before JS_Init is called.

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 (and the js:: namespace for internal use).

  • ...list new C++ helpers here...

Obsolete APIs

  • ...list obsolete methods/structs/APIs here...

Deleted APIs

  • ...list other deleted APIs...

API changes

SpiderMonkey must now be initialized before it can be used.  This is performed by calling the new JS_Init method before creating any runtimes or contexts and before compiling, evaluating, or executing any JS script.  Once this method has been successfully called, it's okay to call JS_NewRuntime and all the other existing SpiderMonkey APIs as usual.  Once all JSAPI operation has completed, the corresponding JS_ShutDown method uninitializes SpiderMonkey, cleaning up memory and allocations performed by JS_Init.  It is not required to call JS_ShutDown at present, but it is strongly recommended: calling it may be required in a future SpiderMonkey release.

JavaScript shell changes

Detail added/removed methods here...

Known Issues

Detail any known issues here...

Future Direction

...insert details on future plans...

SpiderMonkey embedders should 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!

  • Don't add anything here -- this is for after the release notes are completed.  :-)

Revision Source

<p>{{ draft() }}</p>
<div class="note" style="color: black;">
  <p><strong>These release notes are an incomplete draft and will remain so until SpiderMonkey 31 is released.</strong></p>
  <p>The Mozilla JavaScript team is pleased to announce the release of <strong>SpiderMonkey 31</strong>. You can download full source code here: <a href="http://ftp.mozilla.org/pub/mozilla.org/js/mozjs17.0.0.tar.gz" title="http://ftp.mozilla.org/pub/mozilla.org/js/mozjs17.0.0.tar.gz">http://ftp.mozilla.org/pub/mozilla.org/js/mozjs31.0.0.tar.gz</a> (MD5 checksum: INSERT-CHECKSUM-HERE).</p>
  <p>SpiderMonkey 31 is the JavaScript engine that shipped in Firefox 31. It continues to improve performance over previous SpiderMonkey releases, with a significantly improved garbage collector and other features.&nbsp; It also contains new language and API features described in detail below.</p>
  <p>Please let us know about your experiences with this release by posting in the <a class="link-news" href="news://news.mozilla.org/mozilla.dev.tech.js-engine">mozilla.dev.tech.js-engine newsgroup</a>. Or file bugs at <a class="link-https" href="https://bugzilla.mozilla.org/">bugzilla.mozilla.org</a> under Product: Core, Component:&nbsp;JavaScript engine.</p>
  <p>—INSERT-ACTUAL-RELEASE-DATE-HERE</p>
</div>
<h2 id="Platform_support">Platform support</h2>
<p>SpiderMonkey 31 is supported on all the platforms where Firefox 31 runs.&nbsp; Compiling it requires a C++ compiler, and the JSAPI can only be used from C++ code.&nbsp; If you are compiling with Microsoft's Visual Studio, note that the minimum supported version is MSVC10/2010: MSVC8/9 support has been dropped.</p>
<p>SpiderMonkey 31 includes a just-in-time compiler (JIT) that compiles JavaScript to machine code, for a significant speed increase. It is supported on x86, x86_64, and ARM&nbsp;architectures. On some other platforms (SPARC, MIPS), the JIT&nbsp;is provided but not supported.&nbsp; On all 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.</p>
<h2 id="Migrating_to_SpiderMonkey_31">Migrating to SpiderMonkey 31</h2>
<p>The first change most embedders will notice is that SpiderMonkey must now be <em>initialized</em> before it can be used, using the newly-repurposed <a href="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_Init" title="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_Init"><code>JS_Init</code></a> method.&nbsp; After this method is called, normal JSAPI operations are permitted.&nbsp; When all JSAPI operation has completed, the corresponding <a href="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_ShutDown" title="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_ShutDown"><code>JS_ShutDown</code></a> method (currently non-mandatory, but highly recommended as it may become mandatory in the future) uninitializes SpiderMonkey, cleaning up memory and allocations performed by <a href="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_Init" title="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_Init"><code>JS_Init</code></a>.</p>
<p>A major change to SpiderMonkey in 31 is that its APIs support a moving garbage collector.&nbsp; This entailed changing the vast majority of the JSAPI from raw types, such as <code><a href="/en-US/docs/SpiderMonkey/JSAPI_Reference/Jsval" title="/en-US/docs/SpiderMonkey/JSAPI_Reference/Jsval">JS::Value</a> or </code><code><a href="/en-US/docs/SpiderMonkey/JSAPI_Reference/Jsval" title="/en-US/docs/SpiderMonkey/JSAPI_Reference/Jsval">JS::Value</a></code><code>*</code>, to <code>JS::Handle</code> and <code>JS::MutableHandle</code> template types that encapsulate access to the provided value/string/object or its location.&nbsp; The <code>JS::Handle&lt;<a href="/en-US/docs/SpiderMonkey/JSAPI_Reference/Jsval" title="/en-US/docs/SpiderMonkey/JSAPI_Reference/Jsval">JS::Value</a>&gt;</code> and <code>JS::MutableHandle&lt;<a href="/en-US/docs/SpiderMonkey/JSAPI_Reference/Jsval" title="/en-US/docs/SpiderMonkey/JSAPI_Reference/Jsval">JS::Value</a>&gt;</code> classes have been specialized to implement the same interface as <a href="/en-US/docs/SpiderMonkey/JSAPI_Reference/Jsval" title="/en-US/docs/SpiderMonkey/JSAPI_Reference/Jsval"><code>JS::Value</code></a>, for simplicity and to ease migration pain.&nbsp; Changes to introduce handles to the JSAPI are not individually documented, because of the breadth of the changes involved.</p>
<p>The following features in earlier versions of SpiderMonkey have been dropped.</p>
<ul>
  <li>XXX list removed features here</li>
</ul>
<p>SpiderMonkey 31 is not binary-compatible with previous releases, nor is it source-code compatible. Many JSAPI types, functions, and callback signatures have changed, though most functions that have changed still have the same names and implement essentially unchanged functionality. Applications will need significant changes, but most of those changes will be detected by the C/C++&nbsp;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:</p>
<ul>
  <li>Many of the garbage collector changes require type signature changes to JSAPI methods: specifically introducing <code>JS::Rooted</code>, <code>JS::Handle</code>, and <code>JS::MutableHandle</code> types.&nbsp; These types, with the appropriate parametrizations, can roughly be substituted for plain types of GC things (values, string/object pointers, etc.).</li>
  <li>The <code>JSBool</code> type has been removed, along with the corresponding <code>JS_TRUE</code> and <code>JS_FALSE</code> constants.&nbsp; They have been replaced by <code>bool</code>, <code>true</code>, and <code>false</code> respectively.</li>
  <li>Many <code>JSClass</code> and <code>js::Class</code> instances are now explicitly <code>const</code>, and several APIs have been updated to use <code>const JSClass *</code> and <code>const js::Class *</code> pointers.</li>
</ul>
<p>These and other changes are explained in detail below.</p>
<h2 id="New_JavaScript_language_features">New JavaScript language features</h2>
<p>JavaScript 31 includes significant updates to language features, yo.</p>
<h2 id="New_C_APIs" style="position: static;">New C APIs</h2>
<ul style="">
  <li><a href="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_Init" title="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_Init"><code>JS_Init</code></a> is a new function which must be used to initialize the JS engine before any <a href="/en-US/docs/SpiderMonkey/JSAPI_Reference/JSRuntime" title="/en-US/docs/SpiderMonkey/JSAPI_Reference/JSRuntime"><code>JSRuntime</code></a>s are created or other JSAPI methods are called.&nbsp; This method pairs with the existing (currently non-mandatory) <a href="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_ShutDown" title="/en-US/docs/"><code>JS_ShutDown</code></a> method, which uninitializes the JS engine after all runtimes have been destroyed.</li>
  <li><a href="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_SetICUMemoryFunctions" title="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_Init"><code>JS_SetICUMemoryFunctions</code></a> is a new function which can be used to set the allocation and deallocation functions used by the ICU internationalization library.&nbsp; This is unlikely to be of interest to embedders unless you are doing detailed memory profiling.&nbsp; It must be called before <a href="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_Init" title="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_Init"><code>JS_Init</code></a> is called.</li>
</ul>
<h2 id="New_C.2B.2B_helpers">New C++ helpers</h2>
<p>While JSAPI&nbsp;remains a C&nbsp;API, the engine is now implemented in C++. Some C++&nbsp;helpers have been introduced into the API, to help embedders writing C++&nbsp;projects.&nbsp; Please note that SpiderMonkey reserves the <code>JS::</code>&nbsp;namespace for itself (and the <code>js::</code> namespace for internal use).</p>
<ul>
  <li><code>...list new C++ helpers here...</code></li>
</ul>
<h2 id="Obsolete_APIs">Obsolete APIs</h2>
<ul>
  <li><code>...list obsolete methods/structs/APIs here...</code></li>
</ul>
<h2 id="Deleted_APIs">Deleted APIs</h2>
<ul>
  <li>...list other deleted APIs...</li>
</ul>
<h2 id="API_changes">API changes</h2>
<p>SpiderMonkey must now be <em>initialized</em> before it can be used.&nbsp; This is performed by calling the new <a href="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_Init" title="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_Init"><code>JS_Init</code></a> method before creating any runtimes or contexts and before compiling, evaluating, or executing any JS script.&nbsp; Once this method has been successfully called, it's okay to call <a href="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_NewRuntime" title="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_NewRuntime"><code>JS_NewRuntime</code></a> and all the other existing SpiderMonkey APIs as usual.&nbsp; Once all JSAPI operation has completed, the corresponding <a href="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_ShutDown" title="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_ShutDown"><code>JS_ShutDown</code></a> method uninitializes SpiderMonkey, cleaning up memory and allocations performed by <a href="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_Init" title="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_Init"><code>JS_Init</code></a>.&nbsp; It is not required to call <a href="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_ShutDown" title="/en-US/docs/SpiderMonkey/JSAPI_Reference/JS_ShutDown"><code>JS_ShutDown</code></a> at present, but it is strongly recommended: calling it may be required in a future SpiderMonkey release.</p>
<h2 id="JavaScript_shell_changes">JavaScript shell changes</h2>
<p>Detail added/removed methods here...</p>
<h2 id="Known_Issues">Known Issues</h2>
<p>Detail any known issues here...</p>
<h2 id="Future_Direction">Future Direction</h2>
<p>...insert details on future plans...</p>
<p>SpiderMonkey embedders should be aware that</p>
<ul>
  <li>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.</li>
  <li>The team is considering the removal of TinyIDs</li>
  <li>JS_THREADSAFE is going away, with future versions supporting only thread-safe builds</li>
  <li>A new debugging API is on the way to replace JSD.</li>
</ul>
<h2 id="Release_Notes_Errata">Release Notes Errata</h2>
<p>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!</p>
<ul>
  <li>Don't add anything here -- this is for after the release notes are completed.&nbsp; :-)</li>
</ul>
Revert to this revision