5. JavaScript API Reference

The futhark-wasm, futhark-wasm-multicore, and futhark-webgpu(1) compilers can generate JavaScript wrapper code when used with --library. This chapter describes the API exposed by those wrappers.

The exact generated files and the top-level JavaScript interface differ somewhat between the WASM-style backends and the WebGPU backend, so the relevant differences are described below.

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 --library produces generated C code as well as JavaScript-facing runtime files. Some of these files are backend-specific.

For the WASM backend, a build typically produces:

  • futlib.c, futlib.h: implementation and header C files generated by the compiler, similar to futhark c.

  • futlib.class.js: an intermediate JavaScript build artifact.

  • futlib.wasm: the compiled WebAssembly module, which must be present at runtime.

  • futlib.mjs: an ES module that exports the JavaScript wrapper API.

For the WebGPU backend, a build typically produces:

  • futlib.c, futlib.h: implementation and header C files generated by the compiler.

  • futlib.js: the generated backend runtime module.

  • futlib.wrapper.js: the JavaScript wrapper that exposes the Futhark-facing API.

  • futlib.json: manifest data used by the generated wrapper.

  • futlib.wasm: a generated WebAssembly artifact used by the runtime.

The exact file set is backend-dependent and may change over time.

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. Top-level wrapper objects

The top-level JavaScript interface differs between backends.

5.2.1. WASM wrapper

The WASM backend exports a newFutharkContext() factory function that asynchronously constructs a FutharkContext.

newFutharkContext()

Asynchronously create a new FutharkContext object.

class FutharkContext()

A bookkeeping class representing an instance of a compiled Futhark program.

FutharkContext.free()

Frees all memory created by the FutharkContext object. It is an error to use a FutharkArray or FutharkOpaque after the FutharkContext on which they were defined has been freed.

5.2.2. WebGPU wrapper

The WebGPU backend generates a FutharkModule wrapper class. This wrapper is initialised with the generated backend runtime module.

class FutharkModule()

A bookkeeping class representing an instance of a compiled Futhark program.

FutharkModule.init(module)

Asynchronously initialise the FutharkModule object with the generated backend runtime module.

FutharkModule.free()

Frees the Futhark context and configuration associated with the module.

FutharkModule.context_sync()

Wait for pending backend work associated with the context to finish.

FutharkModule.clear_caches()

Clear backend caches associated with the context.

FutharkModule.report()

Return a profiling report string.

FutharkModule.pause_profiling()

Pause profiling.

FutharkModule.unpause_profiling()

Resume profiling.

5.3. Values

Numeric types u8, u16, u32, i8, i16, i32, f16, 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 FutharkArray objects. Complex types (records, nested tuples, etc.) are represented by FutharkOpaque objects.

5.4. FutharkArray

The exact FutharkArray API differs slightly between backends.

5.4.1. WASM wrapper

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 BigInt values.

FutharkArray.free()

Frees the memory used by the FutharkArray.

5.4.2. WebGPU wrapper

The WebGPU backend generates per-type subclasses of FutharkArray.

FutharkArray.get_shape()

Returns the shape of the array as a BigInt64Array.

FutharkArray.values()

Asynchronously returns a flat typed array containing the array data.

FutharkArray.free()

Frees the memory used by the FutharkArray.

Array construction also differs a bit between backends.

For the WASM wrapper, FutharkContext contains constructor methods for each array type that appears in an entry point. For example, for 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, dim0)

Creates and returns a one-dimensional i32 FutharkArray representing the typed array array, with shape dim0.

For the WebGPU wrapper, each generated array type is represented by its own generated class, available through the FutharkModule object.

fut.i32_1d.from_data(data, dim0)

Creates and returns a one-dimensional i32 FutharkArray from a JavaScript Array or the corresponding typed array, with the given shape.

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 for the WASM wrapper has an entry point method on the FutharkContext, and for the WebGPU wrapper, each entry point is exposed through the entry field of the FutharkModule object:

FutharkContext.<entry_point_name>(in1, ..., inN)

The entry point function taking the N arguments of the Futhark entry point function, and returns the result. For the WASM wrapper, if the result is a tuple the return value is an array. For the WebGPU wrapper, if there are multiple outputs, the return value is an array of outputs in order.