.. _js-api:

JavaScript API Reference
========================

The :ref:`futhark-wasm(1)` and :ref:`futhark-wasm-multicore(1)`
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:

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

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.

.. js:function:: newFutharkContext()

   Asynchronously create a new ``FutharkContext`` object.

.. js:class:: FutharkContext()

   A bookkeeping class representing an instance of a Futhark program.
   Do *not* directly invoke its constructor - always use the
   ``newFutharkContext()`` factory function.

.. js: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.

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.

FutharkArray
------------

``FutharkArray`` has the following API

.. 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 BigInts.

.. js:function:: 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``.

.. 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, dim1)

  Creates and returns a one-dimensional ``i32`` ``FutharkArray`` representing
  the typed array of array, with the size given by dim1.


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 has an entry point method on
the FutharkContext

.. 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. If the result is a tuple the return value
  is an array.