@jetblack/wasi-marshalling
v0.7.6
Published
A simple marshalling layer for WASI
Downloads
15
Readme
WASI Marshalling
This library provides two things:
- The minimum WASI implementation required for supporting memory allocation and strings.
- A marshalling framework for calling WebAssembly functions in a wasm module from JavaScript.
The intention is to provide support to "drop in" publicly available libraries that can be compiled into a wasm module.
Installation
The package can be installed from npm.
npm install --save @jetblack/wasi-marshalling
The WASI Layer
Three WASI domains are implemented:
- stout/stderr - many libraries fall back to reporting errors over the standard
output/error. These are redirected to
console.log
andconsole.error
. - string passing with UTF-8 requires a call to
setlocale
which in turn requires a system call to request environment variables. This call is intercepted, and returns a application provided set of the environment variables. - memory management - most libraries make use of
malloc
andfree
to manage memory.
The implementation of the WASI layer is provided through a class of the same name. Here is an example of initializing the library.
import { Wasi } from '@jetblack/wasi-marshalling'
// Create the Wasi instance passing in environment variables.
const wasi = new Wasi({})
// Instantiate the wasm module.
WebAssembly.instantiateStreaming(
fetch('example.wasm'), {
wasi_snapshot_preview1: wasi.imports()
})
.then(res => {
// Initialize the wasi instance
wasi.init(res.instance)
// Do something interesting ...
})
The Marshalling Framework
Introduction
Given the following C function call which multiplies two arrays.
#include <stdlib.h>
__attribute__((used)) double* multipleFloat64ArraysReturningPtr (double* array1, double* array2, int length)
{
double* result = (double*) malloc(length * sizeof(double));
if (result == 0)
return 0;
for (int i = 0; i < length; ++i) {
result[i] = array1[i] + array2[i];
}
return result;
}
We can define and call the following function prototype.
import {
ArrayType,
Float64Type,
Int32Type,
FunctionPrototype,
In
} from '@jetblack/wasi-marshalling.develop.js'
const prototype = new FunctionPrototype(
// The arguments
[
new In(new ArrayType(new Float64Type())),
new In(new ArrayType(new Float64Type())),
new In(new Int32Type())
],
// The return type
new ArrayType(new Float64Type(), 4)
)
const result = prototype.invoke(
wasi.memoryManager,
wasi.instance.exports.multipleFloat64ArraysReturningPtr,
[1, 2, 3, 4],
[5, 6, 7, 8],
4)
console.log(result)
The framework will take care of passing the data to the wasm module, unpacking the result and allocating/deallocating the memory.
Note how a length of 4 was passed for the return type. This is because the function passes a pointer to the start of the result array, so the size is not known. However, the length of a return array is often guaranteed by the input arguments. In the above example the last parameter which specifies the length of the input arrays is also the length of the output arrays. We can use this by passing a callback function as the length argument. The function is provided with the index of the argument for which the length is being queried (or -1 for the result), and the unmarshalled input arguments.
We can re-write the prototype as follows.
import {
ArrayType,
Float64Type,
Int32Type,
FunctionPrototype,
In
} from '@jetblack/wasi-marshalling.develop.js'
const prototype = new FunctionPrototype(
// The arguments
[
new In(new ArrayType(new Float64Type())),
new In(new ArrayType(new Float64Type())),
new In(new Int32Type())
],
// The return type
new ArrayType(new Float64Type(), (i, args) => args[2]))
)
const result = prototype.invoke(
wasi.memoryManager,
wasi.instance.exports.multipleFloat64ArraysReturningPtr,
[1, 2, 3, 4],
[5, 6, 7, 8],
4)
console.log(result)
Finalizers and Typed Arrays
A recent introduction to JavaScript is the FinalizationRegistry. This allows us to register a function to call when an object is garbage collected. We can use this to handle memory management in WebAssembly.
The
TypedArray
family of objects provide transparent interoperability between Javascript and
WebAssembly. Rather than copying values (as with ArrayType
) we can simply pass a
TypedArray
via `TypedArrayType". The prototype fot the above functions would
look like this:
import {
TypedArrayType,
Float64Type,
Int32Type,
FunctionPrototype,
In
} from '@jetblack/wasi-marshalling.develop.js'
const proto = new FunctionPrototype(
[
new In(new TypedArrayType(new Float64Type())),
new In(new TypedArrayType(new Float64Type())),
new In(new Int32Type())
],
new TypedArrayType(new Float64Type(), 4)
)
const result = proto.invoke(
wasi.memoryManager,
wasi.instance.exports.multipleFloat64ArraysReturningPtr,
wasi.memoryManager.createTypedArray(Float64Array, [1, 2, 3, 4]),
wasi.memoryManager.createTypedArray(Float64Array, [5, 6, 7, 8]),
4)
console.log(result)
Note how we call createTypedArray
from the memory manager. This allocates
the memory and registers the pointer with the finalizer to ensure the memory
gets freed.
Types
The framework handles the following types:
- Int8, Int16, Int32, Int64
- Uint8, Uint16, Uint32, Uint64
- Float32, Float64
- String
- Array
- Pointer
Usage
To build the package:
npm install
npm run build
To Run the examples in the client
folder.
# Run a node example
npm run exec:nodejs
# Run code in a `<script>` tag in the browser
npm run exec:browser