futhark-0.26.1: docs/js-api.rst
.. _js-api:
JavaScript API Reference
========================
The :ref:`futhark-wasm(1)`, :ref:`futhark-wasm-multicore(1)`, and
:ref:`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:
.. code-block:: javascript
import { newFutharkContext } from './futlib.mjs';
var fc;
newFutharkContext().then(x => fc = x);
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.
Top-level wrapper objects
-------------------------
The top-level JavaScript interface differs between backends.
WASM wrapper
~~~~~~~~~~~~
The WASM backend exports a ``newFutharkContext()`` factory function that
asynchronously constructs a ``FutharkContext``.
.. js:function:: newFutharkContext()
Asynchronously create a new ``FutharkContext`` object.
.. js:class:: FutharkContext()
A bookkeeping class representing an instance of a compiled Futhark
program.
.. js:function:: 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.
WebGPU wrapper
~~~~~~~~~~~~~~
The WebGPU backend generates a ``FutharkModule`` wrapper class. This
wrapper is initialised with the generated backend runtime module.
.. js:class:: FutharkModule()
A bookkeeping class representing an instance of a compiled Futhark
program.
.. js:function:: FutharkModule.init(module)
Asynchronously initialise the ``FutharkModule`` object with the
generated backend runtime module.
.. js:function:: FutharkModule.free()
Frees the Futhark context and configuration associated with the
module.
.. js:function:: FutharkModule.context_sync()
Wait for pending backend work associated with the context to finish.
.. js:function:: FutharkModule.clear_caches()
Clear backend caches associated with the context.
.. js:function:: FutharkModule.report()
Return a profiling report string.
.. js:function:: FutharkModule.pause_profiling()
Pause profiling.
.. js:function:: FutharkModule.unpause_profiling()
Resume profiling.
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.
FutharkArray
------------
The exact ``FutharkArray`` API differs slightly between backends.
WASM wrapper
~~~~~~~~~~~~
.. js:function:: FutharkArray.toArray()
Returns a nested JavaScript array.
.. js:function:: FutharkArray.toTypedArray()
Returns a flat typed array of the underlying data.
.. js:function:: FutharkArray.shape()
Returns the shape of the ``FutharkArray`` as an array of ``BigInt`` values.
.. js:function:: FutharkArray.free()
Frees the memory used by the ``FutharkArray``.
WebGPU wrapper
~~~~~~~~~~~~~~
The WebGPU backend generates per-type subclasses of ``FutharkArray``.
.. js:function:: FutharkArray.get_shape()
Returns the shape of the array as a ``BigInt64Array``.
.. js:function:: FutharkArray.values()
Asynchronously returns a flat typed array containing the array data.
.. js:function:: 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``:
.. js:function:: FutharkContext.new_i32_1d_from_jsarray(jsarray)
Creates and returns a one-dimensional ``i32`` ``FutharkArray``
representing the JavaScript array ``jsarray``.
.. js:function:: 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.
.. js:function:: 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.
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.
.. js:function:: FutharkOpaque.free()
Frees memory used by FutharkOpaque. Should be called when Futhark
Opaque is no longer used.
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:
.. js:function:: 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.