Update README for type embeds #76
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
torch2424
approved these changes
Apr 21, 2021
| - Wraps around the [AssemblyScript Loader](https://github.com/AssemblyScript/assemblyscript/tree/master/lib/loader). The loader handles all the heavy-lifting of passing data into WebAssembly linear memory. 💪 | ||
| - Wraps around imported JavaScript functions, and exported AssemblyScript functions of the AssemblyScript Wasm Module. This allows high-level data types to be passed directly to exported AssemblyScript functions! 🤯 | ||
| - The library works at runtime, so no generated code that you have to maintain and make it play nicely in your environment. 🏃 | ||
| - Maintains great performance (relative to generating the corresponding JavaScript code), by using [Speculative Execution](https://en.wikipedia.org/wiki/Speculative_execution), and caching types passed between functions. 🤔 | ||
| - Moves a lot of work to compile-time using [AssemblyScript Transforms](https://www.assemblyscript.org/transforms.html#transforms) and completely avoids module-specific “glue code”. 🏃 |
| - Installable from package managers (npm), with a modern JavaScript API syntax. 📦 | ||
| - The library is [< 5KB (minified and gzip'd)](https://bundlephobia.com/result?p=as-bind) and tree-shakeable! 🌲 | ||
| - This library is currently (as of January, 2020) the [wasm-bindgen](https://github.com/rustwasm/wasm-bindgen) in the Rust/Wasm ecosystem, for AssemblyScript. 😀 | ||
| - The library is [< 4KB (minified and gzip'd)](https://bundlephobia.com/result?p=as-bind), _including_ the AssemblyScript Loader ! 🌲 |
There was a problem hiding this comment.
Oooo! Thanks for shaving off a KB 😄
| - The library is [< 5KB (minified and gzip'd)](https://bundlephobia.com/result?p=as-bind) and tree-shakeable! 🌲 | ||
| - This library is currently (as of January, 2020) the [wasm-bindgen](https://github.com/rustwasm/wasm-bindgen) in the Rust/Wasm ecosystem, for AssemblyScript. 😀 | ||
| - The library is [< 4KB (minified and gzip'd)](https://bundlephobia.com/result?p=as-bind), _including_ the AssemblyScript Loader ! 🌲 | ||
| - This library is currently (as of January, 2020) the [wasm-bindgen](https://github.com/rustwasm/wasm-bindgen) of AssemblyScript. 😀 |
| - `./node_modules/as-bind/lib/assembly/as-bind.ts` - This is the as-bind entryfile, used for exporting IDs of AssemblyScript classes so we can use them for instantiating new classes | ||
| - `--runtime incremental` - This specifies that we are using the incremental runtime / garbage collection option (The AssemblyScript default). However, [all the runtime options](https://www.assemblyscript.org/garbage-collection.html) are supported (incremental, minimal, and stub). | ||
| - `--exportRuntime` - This allows us to use the [AssemblyScript Garbage Collection functions added in 0.18.x](https://www.assemblyscript.org/garbage-collection.html) | ||
| - `--transform as-bind` - This is the as-bind transform that runs at compile time. It embeds all the required type information into the WebAssembly Module. |
| @@ -167,22 +165,9 @@ asyncTask(); | |||
|
|
|||
| ## Supported Data Types | |||
|
|
|||
| **TL;DR:** Currently Numbers, Strings, Typed Arrays, and common Array<T> types are supported. Returning a high-level data type from an imported JavaScript function, and better AssemblyScript Class support will be coming later. For more detailed type support information, please see the [`lib/asbind-instance/supported-ref-types.js`](./lib/asbind-instance/supported-ref-types.js) and [`test/assembly/test.ts`](./test/assembly/test.ts). | |||
| All primitive types, ie. Numbers (`u8`, `f32`, ...) , Strings, Typed Arrays (`Uint8Array`, `Float32Array`, ...) are supported. All of those types can also be used with `Array<T>`. | |||
There was a problem hiding this comment.
Awesome! I think we may want to be more clear on what is not supported (That way we don't get issues opened if we do support it).
But I don't think it should be blocking 😄
|
|
||
| as-bind does all of its data passing at runtime. Meaning this will be slower than a code generated bindings generator, such as something like [wasm-bindgen](https://github.com/rustwasm/wasm-bindgen). This is because, as-bind needs to cycle through every supported type on every paremeter or return value for each function, whenever the function is called. However, this is mitigated due to the Speculative execution that the library implements. | ||
| The transform embeds all the required type information of imported and exported functions into a custom section of the WebAssembly module. All the runtime does is utilize the AssemblyScript Loader to convert these types from JS to ASC and vice-versa. Apart from `Array<T>`, which needs to be handled recursively, the overhead is fairly static and minimal. |
|
@surma I think you have the rights to merge? 😄 Feel free to do so! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I took a stab at updating the README for the new as-bind, in an effort to get a beta out for Wasm Summit :D
@torch2424 it does involve quite a bit of deletion as a lot of the properties are gone, but I think that’s a good thing! PTAL and let me know if you have any remarks or concerns!