5. JavaScript API Reference¶
The futhark-wasm and futhark-wasm-multicore compilers produce JavaScript wrapper code to allow JavaScript programs to invoke the generated WebAssembly code. This chapter describes the API exposed by the wrapper.
First a warning: the JavaScript API is experimental. It may change incompatibly even in minor versions of the compiler.
A Futhark program futlib.fut
compiled with a WASM backend as a library
with the --library
command line option produces four files:
futlib.c
,futlib.h
: Implementation and header C files generated by the compiler, similar tofuthark c
. You can delete these - they are not needed at run-time.futlib.class.js
: An intermediate build artifact. Feel free to delete it.futlib.wasm
: A compiled WebAssembly module, which must bepresent at runtime.
futlib.mjs
: An ES6 module that can can be imported by other JavaScript code, and implements the API given in the following.
The module exports a function, newFutharkContext
, which is a factory
function that returns a Promise producing a FutharkContext
instance (see below). A simple usage example:
import { newFutharkContext } from './futlib.mjs';
var fc;
newFutharkContext().then(x => fc = x);
5.1. General concerns¶
Memory management is completely manual, as JavaScript does not support finalizers that could let Futhark hook into the garbage collector. You are responsible for eventually freeing all objects produced by the API, using the appropriate methods.
5.2. FutharkContext¶
FutharkContext is a class that contains information about the context and configuration from the C API. It has methods for invoking the Futhark entry points and creating FutharkArrays on the WebAssembly heap.
- newFutharkContext()¶
Asynchronously create a new
FutharkContext
object.
- class FutharkContext()¶
A bookkeeping class representing an instance of a Futhark program. Do not directly invoke its constructor - always use the
newFutharkContext()
factory function.
- FutharkContext.free()¶
Frees all memory created by the
FutharkContext
object. Should be called when theFutharkContext
is done being used. It is an error use aFutharkArray
orFutharkOpaque
after theFutharkContext
on which they were defined has been freed.
5.3. Values¶
Numeric types u8
, u16
, u32
, i8
, i16
, i32
, f32
,
and f64
are mapped to JavaScript’s standard number type. 64-bit integers
u64
, and i64
are mapped to BigInt
. bool
is mapped to
JavaScript’s boolean
type. Arrays are represented by the FutharkArray
.
complex types (records, nested tuples, etc) are represented by the
FutharkOpaque
class.
5.4. FutharkArray¶
FutharkArray
has the following API
- FutharkArray.toArray()¶
Returns a nested JavaScript array
- FutharkArray.toTypedArray()¶
Returns a flat typed array of the underlying data.
- FutharkArray.shape()¶
Returns the shape of the FutharkArray as an array of BigInts.
- FutharkArray.free()¶
Frees the memory used by the FutharkArray class
FutharkContext
also contains two functions for creating
FutharkArrays
from JavaScript arrays, and typed arrays for each
array type that appears in an entry point. All array types share
similar API methods on the FutharkContext
, which is illustrated
here for the case of the type []i32
.
- FutharkContext.new_i32_1d_from_jsarray(jsarray)¶
Creates and returns a one-dimensional
i32
FutharkArray
representing the JavaScript array jsarray
- FutharkContext.new_i32_1d(array, dim1)¶
Creates and returns a one-dimensional
i32
FutharkArray
representing the typed array of array, with the size given by dim1.
5.5. FutharkOpaque¶
Complex types (records, nested tuples, etc) are represented by
FutharkOpaque
. It has no use outside of being accepted and
returned by entry point functions. For this reason the method only has
one function for freeing the memory when FutharkOpaque
is no
longer used.
- FutharkOpaque.free()¶
Frees memory used by FutharkOpaque. Should be called when Futhark Opaque is no longer used.
5.6. Entry Points¶
Each entry point in the compiled futhark program has an entry point method on the FutharkContext
- FutharkContext.<entry_point_name>(in1, ..., inN)¶
The entry point function taking the N arguments of the Futhark entry point function, and returns the result. If the result is a tuple the return value is an array.