1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
.. _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.
|
