Merge pull request #147 from WebAssembly/refactor-essential-post-mvp-features

Refactor essential post-MVP features

3 files changed, 86 insertions, 43 deletions

diff --git a/EssentialPostMVPFeatures.md b/EssentialPostMVPFeatures.md
index aea0a35..9d4347f 100644
--- a/EssentialPostMVPFeatures.md
+++ b/EssentialPostMVPFeatures.md
@@ -1,47 +1,70 @@
 # Essential Post-MVP Features
 
-This is a list of essential features that are known to be needed ASAP, but were
-removed from [the MVP](MVP.md) since there was not (yet) a portably-efficient
-polyfill via JavaScript. There is a much bigger
-[list of features](FutureFeatures.md) that will be added after this list,
-prioritized by feedback and experience. These features will be available under
-[feature tests](FeatureTest.md).
+Some features are know to be essential and needed as soon as possible but aren't
+in the [Minimum Viable Product (MVP)](MVP.md) because there isn't yet a
+portably-efficient [polyfill](Polyfill.md) via JavaScript. There is a much
+bigger [list of features](FutureFeatures.md) that will be added after these
+essential features.
+
+Post-MVP features will be available under [feature tests](FeatureTest.md).
 
 ## Threads
-* Provide low-level buildings blocks for pthreads-style shared memory: shared memory,
-  atomics + futexes (or [synchronics](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4195.pdf)).
-* Import [SharedArrayBuffer proposal](https://docs.google.com/document/d/1NDGA_gZJ7M7w1Bh8S0AoDyEqwDdRh4uSoTPSNn77PFk).
-  * The goal is to reuse the specification of memory model, happens-before, etc (with TC39) and backend implementation
-    (same IR nodes and semantic invariants preserved).
-* Modules can have global variables that are either shared or thread-local.
-  * While the heap could be used for shared global variables, global variables are not aliasable
-    and thus allow more aggressive optimization.
-* Initially, a WebAssembly module is distributed between workers via `postMessage()`.
-  * This also has the effect of explicitly sharing code so that engines don't
-    perform N fetches and compile N copies.
-  * May later standardize a more direct way to create a thread from WebAssembly.
+
+Provide low-level buildings blocks for pthreads-style shared memory: shared
+memory between threads, atomics and futexes (or [synchronic][]). WebAssembly's
+approach would be similar to the [original PNaCl atomic support][] and
+[SharedArrayBuffer][] proposal: reuse the specification of memory model,
+happens-before relationship, and synchronize-with edges as defined in other
+languages.
+
+Modules can have global variables that are either shared or thread-local. While
+the heap could be used for shared global variables, global variables are not
+aliasable and thus allow more aggressive optimization.
+
+  [synchronic]: http://wg21.link/n4195
+  [original PNaCl atomic support]: https://developer.chrome.com/native-client/reference/pnacl-c-cpp-language-support#memory-model-and-atomics
+  [SharedArrayBuffer]: https://docs.google.com/document/d/1NDGA_gZJ7M7w1Bh8S0AoDyEqwDdRh4uSoTPSNn77PFk
 
 ## Fixed-width SIMD
-* Essentially, import [SIMD.js](https://github.com/johnmccutchan/ecmascript_simd).
-  * Would be statically typed analogous to [SIMD.js-in-asm.js](http://discourse.specifiction.org/t/request-for-comments-simd-js-in-asm-js).
-  * The goal is to both reuse specification of op semantics (with TC39) and backend implementation (same IR nodes)
-  * Track SIMD.js after the MVP.
-* SIMD adds new primitive variable/expression types (e.g., `float32x4`) so it has to be part of
-  the core semantics.
-* SIMD operations (e.g., `float32x4.add`) could be either builtin ops (no different than int32 add) or
-  exports of a builtin SIMD module.
-
-## 64-bit integers
-* Provide access to efficient 64-bit arithmetic.
-* Some code will want to only use 64-bit integers when running on a 64-bit system (for performance
-  reasons) so provide a "has native 64-bit integer" query.
+
+Support fixed-width SIMD vectors, initially only for 128-bit wide vectors as
+demonstrated in [PNaCl's SIMD][] and [SIMD.js][].
+
+SIMD adds new primitive variable and expression types (e.g., `float32x4`) so it
+has to be part of the core semantics. SIMD operations (e.g., `float32x4.add`)
+could be either builtin operations (no different from `int32.add`) or exports of
+a builtin SIMD module.
+
+  [PNaCl's SIMD]: https://developer.chrome.com/native-client/reference/pnacl-c-cpp-language-support#portable-simd-vectors
+  [SIMD.js]: https://github.com/johnmccutchan/ecmascript_simd
 
 ## Zero-cost Exception Handling
-* Developer access to stack unwinding and inspection.
-* This may be used to implement `setjmp`/`longjmp` (instead of the usual
-  opposite approach). This can enable all of the defined behavior of
-  `setjmp`/`longjmp`, namely unwinding the stack, but does not allow
-  the undefined behavior case of jumping forward to a stack that
-  was already unwound (which is sometimes used to implement coroutines;
-  however, explicit coroutine support is being considered separately
-  anyhow).
+
+The WebAssembly MVP (compilers and polyfills) may support four no-exception
+modes for C++:
+* Compiler transforms `throw` to `abort()`.
+* Compiler-enforced `-fno-exceptions` mode (note [caveats][]).
+* Compiler conversion of exceptions to branching at all callsites.
+* In a Web environment exception handling can be emulated using JavaScript
+  exception handling, which can provide correct semantics but isn't fast.
+
+These modes are suboptimal for code bases which rely on C++ exception handling,
+but are perfectly acceptable for C code, or for C++ code which avoids
+exceptions. This doesn't prevent developers from using the C++ standard library:
+their code will function correctly (albeit slower at times) as long as it
+doesn't encounter exceptional cases.
+
+Post-MVP, WebAssembly will gain support for developer access to stack unwinding,
+inspection, and limited manipulation. These are critical to supporting zero-cost
+exception handling by exposing [low-level capabilities][].
+
+In turn, stack unwinding, inspection, and limited manipulation will be used to
+implement `setjmp`/`longjmp`. This can enable all of the defined behavior of
+`setjmp`/`longjmp`, namely unwinding the stack without calling C++
+destructors. It does not, however, allow the undefined behavior case of jumping
+forward to a stack that was already unwound which is sometimes used to implement
+coroutines. Coroutine support is being
+[considered separately](FutureFeatures.md#Coroutines).
+
+  [caveats]: https://blog.mozilla.org/nnethercote/2011/01/18/the-dangers-of-fno-exceptions
+  [low-level capabilities]: https://extensiblewebmanifesto.org
diff --git a/FutureFeatures.md b/FutureFeatures.md
index 7021668..dbadd13 100644
--- a/FutureFeatures.md
+++ b/FutureFeatures.md
@@ -89,6 +89,13 @@ implementation running on such a platform may restrict allocations to the lower
 * Text source maps become intractably large for even moderate-sized compiled
   codes, so probably need to define new binary format for source maps.
 
+## Coroutines
+
+Coroutines will [eventually be part of C++][] and is already popular in other
+programming languages that WebAssembly will support.
+
+  [eventually be part of C++]: http://wg21.link/n4499
+
 ## Signature-restricted Proper Tail Calls
 
 See the [asm.js RFC][] for a full description of signature-restricted Proper
diff --git a/Web.md b/Web.md
index ac24b21..e1f2513 100644
--- a/Web.md
+++ b/Web.md
@@ -20,20 +20,33 @@ that the design, especially that of the [MVP](MVP.md), are sensible:
 * A [module](MVP.md#Modules) can be loaded in the same way as an ES6 module
   (`import` statements, `Reflect` API, `Worker` constructor, etc) and the result
   is reflected to JS as an ES6 module object.
-  * Exports are the ES6 module object exports.
-  * An import first passes the module name to the [module loader pipeline][] and
+  - Exports are the ES6 module object exports.
+  - An import first passes the module name to the [module loader pipeline][] and
     resulting ES6 module (which could be implemented in JS or WebAssembly) is
     queried for the export name.
-  * There is no special case for when one WebAssembly module imports another:
+  - There is no special case for when one WebAssembly module imports another:
     they have separate [heaps](MVP.md#heap) and pointers cannot be passed
     between the two. Module imports encapsulate the importer and
     importee. [Dynamic linking](FutureFeatures.md#dynamic-linking) should be
     used to share heaps and pointers across modules.
-  * To synchronously call into JavaScript from C++, the C++ code would declare
+  - To synchronously call into JavaScript from C++, the C++ code would declare
     and call an undefined `extern` function and the target JavaScript function
     would be given the (mangled) name of the `extern` and put inside the
     imported ES6 module.
+* Once [threads are supported](EssentialPostMVPFeatures.md#Threads), a
+  WebAssembly module would initially be distributed between workers via
+  `postMessage()`.
+  - This also has the effect of explicitly sharing code so that engines don't
+    perform N fetches and compile N copies.
+  - May later standardize a more direct way to create a thread from WebAssembly.
+* Once [SIMD is supported](EssentialPostMVPFeatures.md#Fixed-width-SIMD), a Web
+  implementation of WebAssembly would:
+  - Be statically typed analogous to [SIMD.js-in-asm.js][];
+  - Reuse specification of operation semantics (with TC39);
+  - Reuse backend implementation (same IR nodes).
 
   [CORS]: http://www.w3.org/TR/cors/
   [subresource integrity]: http://www.w3.org/TR/SRI/
   [module loader pipeline]: http://whatwg.github.io/loader
+  [SIMD.js-in-asm.js]: http://discourse.specifiction.org/t/request-for-comments-simd-js-in-asm-js
+