Merge pull request WebAssembly#455 from WebAssembly/alias-from-js

Refine linear memory aliasing

FutureFeatures.md

@@ -398,3 +398,13 @@ significant portions of memory could be moved out of linear memory which could
 reduce fragmentation issues. Languages like Fortran which limit aliasing would be
 one use case. C/C++ compilers could also determine that some global variables never
 have their address taken.
+
+## Importing linear memory
+
+In the MVP, functions and [linear memory](Modules.md#linear-memory-section) can
+be exported, but only functions can be imported. This feature would additionally
+allow importing linear memory. One use case is sharing linear memories between
+separate WebAssembly [instances](Modules.md). Another use case is allowing, on
+the Web platform, importing a JS `ArrayBuffer` as a linear memory. This would
+allow highly efficient, specialized code to be generated for accessing the
+`ArrayBuffer`.

Modules.md

@@ -140,6 +140,14 @@ The linear memory section may also contain an optional hint declaring the expect
 maximum heap usage. This hint is not semantically visible but can help a
 WebAssembly engine to optimize `grow_memory`.
 
+The linear memory section may optionally declare that the instance's
+linear memory is *externally aliasable*. How linear memory is aliased is up
+to the host environment (as with all module exports). The 
+[Web](Web.md#aliasing-linear-memory-from-JS) would reflect exported linear
+memory to JS as an `ArrayBuffer`. The MVP does not currently provide for
+*importing* linear memory though this may be added 
+[in the future](FutureFeatures.md#importing-linear-memory).
+
 ## Code section
 
 The WebAssembly spec defines the code section of a module in terms of an

Web.md

@@ -14,30 +14,69 @@ than if the module was JavaScript.
 More concretely, the following is a list of points of contact between WebAssembly
 and the rest of the Web platform that have been considered:
 
-* WebAssembly's [modules](Modules.md) allow for natural [integration with
-  the ES6 module system](Modules.md#integration-with-es6-modules) and allow
-  synchronous calling to and from JavaScript.
-* If allowed by the module, JavaScript can alias a loaded module's linear
-  memory via Typed Arrays. (To keep the Typed Arrays' lengths constant,
-  if linear memory is resized, any extant Typed Arrays are detached.)
-* WebAssembly's security model should depend on [CORS][] and
-  [subresource integrity][] to enable distribution, especially through content
-  distribution networks and to implement
-  [dynamic linking](DynamicLinking.md).
-* Once [threads are supported](PostMVP.md#threads), a WebAssembly module would
-  be shared (including its heap) 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.
-  - WebAssembly may later standardize a more direct way to create a thread that
-    doesn't involve creating a new Worker.
-* Once [SIMD is supported](PostMVP.md#fixed-width-simd) 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).
-* Once [GC is supported](GC.md), WebAssembly code would be able to reference
-  and access JavaScript, DOM, and general WebIDL-defined objects.
+## Modules
+
+WebAssembly's [modules](Modules.md) allow for natural [integration with
+the ES6 module system](Modules.md#integration-with-es6-modules) and allow
+synchronous calling to and from JavaScript.
+
+## Aliasing linear memory from JS
+
+If [allowed by the module](Modules.md#linear-memory-section), JavaScript can
+alias a loaded module's linear memory through an exported `ArrayBuffer`.
+Module instances would additionally expose methods to JS to copy ranges of
+bytes into and out of linear memory as separate (unaliased) `ArrayBuffer`s.
+
+Since JS semantics and implementations require the `byteLength` of an
+`ArrayBuffer` to be constant, [resizing](AstSemantics.md#resizing) the
+linear memory cannot simply resize the exported `ArrayBuffer`. Instead,
+the `ArrayBuffer` would be [detached](http://people.mozilla.org/~jorendorff/es6-draft.html#sec-detacharraybuffer)
+and a new `ArrayBuffer` (with a new `byteLength`) would be exported in
+its place.
+
+When [threads](PostMVP.md#threads) are added, a
+[`SharedArrayBuffer`](https://github.com/lars-t-hansen/ecmascript_sharedmem)
+would need to be exported instead of an `ArrayBuffer`. However, the
+detach-on-resize strategy would pose significant usability and implementation 
+hazards, since resizing can happen concurrently. One solution would be
+to simply not export a `SharedArrayBuffer` when a module declared use of
+threads and resizable memory (the copy in/out methods would need to be used
+instead).
+
+Similarly, various [linear memory operations](FutureFeatures.md#finer-grained-control-over-memory)
+like `mprotect` conflict with the JS semantics of `ArrayBuffer` and
+would inhibit export. In general, `ArrayBuffer` could be viewed as an
+optimization of copy in/out that was only available when linear memory
+behaved like an `ArrayBuffer` (or `SharedArrayBuffer`).
+
+## Security
+
+WebAssembly's security model should depend on [CORS][] and
+[subresource integrity][] to enable distribution, especially through content
+distribution networks and to implement
+[dynamic linking](DynamicLinking.md).
+
+## Threads
+
+Once [threads are supported](PostMVP.md#threads), a WebAssembly module would
+be shared (including its heap) 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.
+* WebAssembly may later standardize a more direct way to create a thread that
+doesn't involve creating a new Worker.
+
+## SIMD
+
+Once [SIMD is supported](PostMVP.md#fixed-width-simd) 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).
+
+## GC
+
+Once [GC is supported](GC.md), WebAssembly code would be able to reference
+and access JavaScript, DOM, and general WebIDL-defined objects.
 
   [CORS]: https://www.w3.org/TR/cors/
   [subresource integrity]: https://www.w3.org/TR/SRI/
   [SIMD.js-in-asm.js]: http://discourse.specifiction.org/t/request-for-comments-simd-js-in-asm-js
-