A marshalling layer for WASI and WebAsembly
APACHE-2.0 License
This library provides two things:
The intention is to provide support to "drop in" publicly available libraries that can be compiled into a wasm module.
The package can be installed from npm.
npm install --save @jetblack/wasi-marshalling
Three WASI domains are implemented:
console.log
and console.error
.setlocale
which in turnmalloc
and free
to manageThe implementation of the WASI layer is provided through a class of the same name. Here is an example of initializing the library.
import { Marshaller } from '@jetblack/wasi-marshalling'
// Create the Marshaller instance passing in environment variables.
const marshaller = new Marshaller({})
// Instantiate the wasm module.
WebAssembly.instantiateStreaming(
fetch('example.wasm'), {
wasi_snapshot_preview1: marshaller.wasiImplementation()
})
.then(res => {
// Initialize the Marshaller instance
marshaller.init(res.instance)
// Do something interesting ...
})
Given the following C function call which multiplies two arrays.
#include <stdlib.h>
__attribute__((used)) double* multiplyFloat64ArraysReturningPtr (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(
marshaller.memoryManager,
marshaller.instance.exports.multiplyFloat64ArraysReturningPtr,
[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(
marshaller.memoryManager,
marshaller.instance.exports.multiplyFloat64ArraysReturningPtr,
[1, 2, 3, 4],
[5, 6, 7, 8],
4)
console.log(result)
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(
marshaller.memoryManager,
marshaller.instance.exports.multiplyFloat64ArraysReturningPtr,
marshaller.memoryManager.createTypedArray(Float64Array, [1, 2, 3, 4]),
marshaller.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.
The framework handles the following types:
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