A Complete Introduction to WebAssembly and It’s JavaScript API

To fully exploit the features of WebAssembly, we have to integrate it with our JavaScript code. This can be done with the help of the JavaScript WebAssembly API.

Module Compilation and Instantiation

The WebAssembly code resides in a .wasm file. This file should be compiled to machine code that is specific to the machine it is running on. You can use the WebAssembly.compile method to compile your WebAssembly module. After receiving the compiled module, you can use the WebAssembly.instantiate method to instantiate your compiled module. Alternatively, you can pass the array buffer you obtain from fetching .wasm file into the WebAssembly.instantiate method as well. This too works as the instantiate method has two overloads.

Code snippet by Author

One of the downsides of the above approach is that these methods don’t directly access the byte code, so require an extra step to turn the response into an ArrayBuffer before compiling/instantiating the wasm module.

Instead, we can use the WebAssembly.compileStreaming / WebAssembly.instantiateStreaming methods to achieve the same functionality as above, with an advantage being able to access the byte code directly without the need for turning the response into an ArrayBuffer .

Code snippet by Author

You should note that the WebAssembly.instantiate and WebAssembly.instantiateStreaming return the instance as well as the compiled module as well, which can be used to spin up instances of the module quickly.

Code snippet by Author

Import Object

When we instantiate a WebAssembly module instance, we can optionally pass an import object that would contain the values to be imported into the newly created module instance. These can be of 4 types.

  • global values
  • functions
  • memory
  • tables

The import object can be considered as the tools supplied to your module instance to help it achieve its task. If an import object is not provided, the compiler will assign default values.

Globals

WebAssembly allows you to create global variable instances that can be accessed from your JavaScript and WebAssembly modules. You can import/export these variables and use them across one or more WebAssembly module instances.

You can create a global instance by using the WebAssembly.Global() constructor.

const global = new WebAssembly.Global({
value: 'i64',
mutable: true
}, 20);

The global constructor accepts two parameters.

  • An object containing properties describing the data type and mutability of the global variable. The allowed data types are i32, i64, f32, or f64
  • The initial value of the actual variable. This value should be of the type mentioned in parameter 1. For example, if you mention the type as i32 , your variable should be a 32-bit integer. Likewise, if you mention f64 as the type, then your variable should be a 64-bit float.
Code snippet by Author

The global instance should be passed onto the importObject in order for it to be accessible in the WebAssembly module instance.

Memory

At the point of instantiation, the WebAssembly module would need a memory object allocated. This memory object should be passed with the importObject. If you fail to do so, the JIT compiler would create and attach a memory object to the instance automatically with the default values.

The memory object attached to the module instance would simply be an ArrayBuffer. This enables for easy memory access by simply using index values. Furthermore, because of being a simple ArrayBuffer , values can simply be passed and shared between JavaScript and WebAssembly.

Table

A WebAssembly Table is a resizable array that lives outside of the WebAssembly’s memory. The values of the table are function references. Although this sounds similar to the WebAssembly Memory, the major difference between them is that Memory array is of raw bytes while the Table array is of references.

The main reason for the introduction of Table is improved security.

You can use the methods set() , grow() , and get() to manipulate your table.

Author: admin

Leave a Reply

Your email address will not be published.