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 to futhark 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 be

    present 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 the FutharkContext is done being used. It is an error use a FutharkArray or FutharkOpaque after the FutharkContext 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.