HTML
Contenu HTML de l'exemple
Contenu CSS de l'exemple
Dans le format binaire comme dans le format textuel, l'unité de code fondamentale en WebAssembly est le module. Dans le format textuel, un module est représenté par une grosse S-expression. Les S-expressions sont un format simple et ancien pour représenter des arbres logiques, et en conséquence, nous pouvons considérer un module comme un arbre de noeuds décrivant la structure du module et de son code. A l'inverse de l'Arbre Syntaxique Abstrait d'un langage de programmation, l'arbre de WebAssembly est assez plat, et consiste pour beaucoup en une liste d'instructions.
Tout d'abord, regardons à quoi ressemble une S-expression. Chaque noeud de l'arbre se situe à l'intérieur d'un couple de parenthèses — ( ... ). Le premier label dans ces parenthèses indique le type de noeud. Ensuite, il y a une liste de noeufs ou d'attributs séparés par des espaces. Donc si l'on considère la S-expression WebAssembly suivante :
(module (memory 1) (func))
Celle-ci représente un arbre avec un noeud racine "module" ainsi que deux noeuds enfants, un "memory" avec l'attribut 1, ainsi qu'un noeud "func". Nous allons bientôt voir ce que ces noeuds signifient.
Commençons avec la version la plus simple et la plus courte possible d'un module wasm.
(module) (commençons avec la version la plus simple et la plus courte possible d'un module wasm.)
Celui-ci est totalement vide, mais reste un module valide.
Si l'on convertit notre module en binaire (voir Converting WebAssembly text format to wasm), nous obtenons l'en-tête de module de 8 octets, décrite dans le format binaire.
0000000: 0061 736d ; WASM_BINARY_MAGIC 0000004: 0100 0000 ; WASM_BINARY_VERSION
Un module vide n'étant clairement pas très intéressant, prenons le temps d'y ajouter du code.
Tout code dans un module WebAssembly est regroupé en fonctions, qui ont la structure suivante (en pseudo-code):
( func <signature> <locals> <body> )
Donc les fonctions WebAssembly se rapprochent beaucoup des fonctions dans les autres langages, à l'exception près qu'elles sont représentées par un S-expression.
La signature est une séquence de déclaration des différents types d'arguments, suivie par une liste de déclarations des différents types pour les valeurs de retours. Il est important de noter que :
Chaque argument possède un type déclaré explicitement. Quatre types sont actuellement
|
|
|
|
||
|---|---|---|---|---|---|
disponible dans wasm:
i32: Entier 32-biti64: Entier 64-bitf32: Nombre à virgule flottante 32-bit floatf64: Nombre à virgule flottante 64-bit floatUn argument seul s'écrit (param i32) et le type de retour s'écrit (result i32), donc une fonction binaire prenant deux entiers 32-bit and et retournant un nombre à virgule flottante 64-bit s'écrirait ainsi :
(func (param i32) (param i32) (result f64) ... )
Après la signature, les variables locales sont listées avec leur type, par exemple (local i32). Les arguments sont juste des variables locales initialisées avec avec la valeur de l'argument correspondant, passé par la fonction appelante.
Les variables locales et les arguments peuvent être lus et écrits par le corps de la fonction, via les instructions get_local et set_local.
Les commandes get_local/set_local désignent l'élément à récupérer/définir par son index numérique : les arguments sont référencés en premier, par ordre de déclaration, suivis par les variables locales, par ordre de déclaration également. Donc, en considérant la fonction suivante :
(func (param i32) (param f32) (local f64) get_local 0 get_local 1 get_local 2)
L'instruction get_local 0 récupère l'argument i32, get_local 1 récupère l'argument f32, et get_local 2 récupère la variable locale f64.
Il y a un hic à cette manière de procéder. Le fait d'utiliser des index numériques pour faire références à des éléments du code peut être déroutant. Le format textuel de wasm vous permet pour éviter cela de nommer les arguments, variables locales et autres éléments du code, en incluant un nom préfixé par un symbol dollar ($) juste avant la déclaration du type.
Ainsi, vous pourriez ré-écrire la signature précédente ainsi :
(func (param $p1 i32) (param $p2 f32) (local $loc i32) …)
Et ensuite, vous pourriez écrire get_local $p1 en lieu et place de get_local 0, etc. (Lorsque ce texte sera converti en binaire, le code de sortie contiendra uniquement l'entier)
Avant que nous puissions écrire le corps d'une fonction, nous devons aborder une dernière chose : les automates à pile (Stack machines en anglais). Bien que le navigateur compile le wasm en quelque chose de plus efficace, l'éxecution de wasm est définie par un automate à pile où l'idée de base est que chaque type d'instruction ajoute ou retire un certain nombre de valeurs i32/i64/f32/f64 à une pile.
Par exemple, get_local est destinée à ajouter sur la pile la valeur de la variable qu'elle lit, et i32.add retire deux valeurs i32 (il récupère implicitement les deux précédentes valeurs ajoutée sur la pile), calcule leur somme (modulo 2^32) et ajoute la valeur i32 résultante.
Lorsqu'une fonction est appelée, elle débute avec une pile vide qui est peu à peu remplie et vidée durant l'exécution du corps de la fonction. Par exemple, après l'exécution de la fonction suivante :
(func (param $p i32) get_local $p get_local $p i32.add)
La pile contient exactement une valeur i32 — le résultat de l'expression ($p + $p), qui est calculé par i32.add. La valeur de retour d'une fonction est simplement la dernière valeur restante de la pile.
Les règles de validation de WebAssembly s'assurent de l'intégrité de la pile : si vous déclarez un (result f32), alors la pile doit contenir exactement un f32 à la fin. S'il n'y a pas de type de retour, alors la pile doit être vide.
Comme mentionné plus haut, le corps de la fonction est simplement une liste d'instructions qui s'enchaînent lorsque la fonction est appelée. En reprenant tout ce que nous avons déjà appris, nous pouvons enfin définir un module contenant notre simple fonction :
(module
(func (param $lhs i32) (param $rhs i32) (result i32)
get_local $lhs
get_local $rhs
i32.add))
Cette fonction prend deux arguments, fait leur somme, et retourne le résultat.
Il y a évidemment beaucoup plus de choses qui peuvent être faites au sein du corps d'une fonction, mais pour l'instant nous allons rester dans la simplicité. Vous verrez beaucoup plus d'exemples au fur et à mesure. Pour avoir la liste exhaustive du code machine disponible, consultez cette page.
Notre fonction ne va pas faire grand chose en soi — maintenant nous devons l'appeler. Mais comment faire ? Un peu comme un module ES2015, les fonctions wasm doivent être explicitement exportées par une déclaration export dans le module.
A l'image des variables locales, les fonctions sont identifiées par un index, mais par commodité, elle peuvent être nommées. Commençons par cela en premier : nous allons ajouter un nom précédé d'un symbole dollar, juste après le mot-clé func:
(func $add … )
Maintenant, nous allons ajouter la déclaration d'export, qui prend cette forme :
(export "add" (func $add))
Ici, add est le nom par lequel la fonction sera identifiée dans JavaScript, tandis que $add correspond à la fonction WebAssembly dans le module qui sera exportée.
Notre module final ressemble à ceci (pour l'instant) :
(module
(func $add (param $lhs i32) (param $rhs i32) (result i32)
get_local $lhs
get_local $rhs
i32.add)
(export "add" (func $add))
)
Si vous voulez suivre l'exemple, sauvegardez le module ci-dessus dans un fichier appelé add.wat , puis convertissez-le en un fichier binaire appelé add.wasm via wabt (cf. Converting WebAssembly text format to wasm pour plus de détails).
Ensuite, nous allons charger notre binaire dans un tableau typé appelé addCode (comme décrit dans Fetching WebAssembly Bytecode), le compiler et l'instantier, puis exécuter notre fonction add dans JavaScript (nous pouvons désormais obtenir add() dans la propriété exports de l'instance):
WebAssembly.instantiateStreaming(fetch('add.wasm'))
.then(obj => {
console.log(obj.instance.exports.add(1, 2)); // "3"
});
Note: Vous pouvez récupérer cet exemple via GitHub : add.html (démo). Voir aussi {{jsxref("WebAssembly.instantiate()")}} pour plus de détails à propos de la fonction d'instanciation, ainsi que wasm-utils.js pour le code source de fetchAndInstantiate().
Maintenant que nous avons vu les aspects basiques, continuons sur des fonctionnalités plus avancées.
L'instruction call appelle une fonction à partir de son index ou de son nom. Par exemple, le module suivant contient deux fonctions — l'une d'entre elle retourne la valeur 42, tandis que l'autre retourne le résultat de l'appel de la première plus un:
(module
(func $getAnswer (result i32)
i32.const 42)
(func (export "getAnswerPlus1") (result i32)
call $getAnswer
i32.const 1
i32.add))
Note: i32.const définit simplement un entier 32-bit et l'ajoute à la pile. Vous pouvez remplacer i32 par n'importe quel autre type disponible, et changer la valeur du const comme vous le souhaitez (ici, nous avons défini la valeur 42).
Dans cet exemple, vous avez sûrement remarqué la section (export "getAnswerPlus1") , déclarée juste après la déclaration func de la seconde fonction. C'est un moyen plus rapide de déclarer que nous voulons exporter cette fonction, et de définir le nom avec lequel nous voulont l'exporter.
Ceci revient à inclure une déclaration de fonction séparée en dehors de la fonction, autre part dans le module, de la même façon que ce que nous avons déjà fait précédemment :
(export "getAnswerPlus1" (func $functionName))
Voici le code JavaScript pour appeler notre module ci-dessus :
WebAssembly.instantiateStreaming(fetch('call.wasm'))
.then(obj => {
console.log(obj.instance.exports.getAnswerPlus1()); // "43"
});
Note: Vous pouvez récupérer cet exemple via GitHub: call.html (démo). A nouveau, voir wasm-utils.js pour les sources de fetchAndInstantiate().
Nous avons déjà vu du JavaScript appeler des fonctions WebAssembly, mais que dites-vous d'appeler des fonctions JavaScript depuis WebAssembly ? En fait, WebAssembly n'a pas nativement connaissance de JavaScript, mais il possède une méthode générique d'import de fonctions qui peut accepter des fonctions wasm ou JavaScript. Voici un exemple :
(module
(import "console" "log" (func $log (param i32)))
(func (export "logIt")
i32.const 13
call $log))
WebAssembly has a two-level namespace so the import statement here is saying that we’re asking to import the log function from the console module. You can also see that the exported logIt function calls the imported function using the call instruction we introduced above.
Imported functions are just like normal functions: they have a signature that WebAssembly validation checks statically, and they are given an index and can be named and called.
JavaScript functions have no notion of signature, so any JavaScript function can be passed, regardless of the import’s declared signature. Once a module declares an import, the caller of {{jsxref("WebAssembly.instantiate()")}} must pass in an import object that has the corresponding properties.
For the above, we need an object (let's call it importObject) such that importObject.console.log is a JavaScript function.
This would look like the following:
var importObject = {
console: {
log: function(arg) {
console.log(arg);
}
}
};
WebAssembly.instantiateStreaming(fetch('logger.wasm'), importObject)
.then(obj => {
obj.instance.exports.logIt();
});
Note: You can find this example on GitHub as logger.html (see it live also).
The above example is a pretty terrible logging function: it only prints a single integer! What if we wanted to log a text string? To deal with strings and other more complex data types, WebAssembly provides memory. According to WebAssembly, memory is just a large array of bytes that can grow over time. WebAssembly contains instructions like i32.load and i32.store for reading and writing from linear memory.
From JavaScript’s point of view, it’s as though memory is all inside one big (resizable) {{domxref("ArrayBuffer")}}. That’s literally all that asm.js has to play with (except that it isn't resizable; see the asm.js Programming model).
So a string is just a sequence of bytes somewhere inside this linear memory. Let's assume that we’ve written a suitable string of bytes to memory; how do we pass that string out to JavaScript?
The key is that JavaScript can create WebAssembly linear memory instances via the {{jsxref("WebAssembly.Memory()")}} interface, and access an existing memory instance (currently you can only have one per module instance) using the associated instance methods. Memory instances have a buffer getter, which returns an ArrayBuffer that points at the whole linear memory.
Memory instances can also grow, for example via the Memory.grow() method in JavaScript. When growth occurs, since ArrayBuffers can’t change size, the current ArrayBuffer is detached and a new ArrayBuffer is created to point to the newer, bigger memory. This means all we need to do to pass a string to JavaScript is to pass out the offset of the string in linear memory along with some way to indicate the length.
While there are many different ways to encode a string’s length in the string itself (for example, C strings); for simplicity here we just pass both offset and length as parameters:
(import "console" "log" (func $log (param i32) (param i32)))
On the JavaScript side, we can use the TextDecoder API to easily decode our bytes into a JavaScript string. (We specify utf8 here, but many other encodings are supported.)
consoleLogString(offset, length) {
var bytes = new Uint8Array(memory.buffer, offset, length);
var string = new TextDecoder('utf8').decode(bytes);
console.log(string);
}
The last missing piece of the puzzle is where consoleLogString gets access to the WebAssembly memory. WebAssembly gives us a lot of flexibility here: we can either create a Memory object in JavaScript and have the WebAssembly module import the memory, or we can have the WebAssembly module create the memory and export it to JavaScript.
For simplicity, let's create it in JavaScript then import it into WebAssembly. Our import statement is written as follows:
(import "js" "mem" (memory 1))
The 1 indicates that the imported memory must have at least 1 page of memory (WebAssembly defines a page to be 64KB.)
So let's see a complete module that prints the string “Hi”. In a normal compiled C program, you’d call a function to allocate some memory for the string, but since we’re just writing our own assembly here and we own the entire linear memory, we can just write the string contents into global memory using a data section. Data sections allow a string of bytes to be written at a given offset at instantiation time and are similar to the .data sections in native executable formats.
Our final wasm module looks like this:
(module
(import "console" "log" (func $log (param i32 i32)))
(import "js" "mem" (memory 1))
(data (i32.const 0) "Hi")
(func (export "writeHi")
i32.const 0 ;; pass offset 0 to log
i32.const 2 ;; pass length 2 to log
call $log))
Note: Above, note the double semi-colon syntax (;;) for allowing comments in WebAssembly files.
Now from JavaScript we can create a Memory with 1 page and pass it in. This results in "Hi" being printed to the console:
var memory = new WebAssembly.Memory({initial:1});
var importObj = { console: { log: consoleLogString }, js: { mem: memory } };
WebAssembly.instantiateStreaming(fetch('logger2.wasm'), importObject)
.then(obj => {
obj.instance.exports.writeHi();
});
Note: You can find the full source on GitHub as logger2.html (also see it live).
To finish this tour of the WebAssembly text format, let’s look at the most intricate, and often confusing, part of WebAssembly: tables. Tables are basically resizable arrays of references that can be accessed by index from WebAssembly code.
To see why tables are needed, we need to first observe that the call instruction we saw earlier (see {{anch("Calling functions from other functions in the same module")}}) takes a static function index and thus can only ever call one function — but what if the callee is a runtime value?
WebAssembly needed a type of call instruction to achieve this, so we gave it call_indirect, which takes a dynamic function operand. The problem is that the only types we have to give operands in WebAssembly are (currently) i32/i64/f32/f64.
WebAssembly could add an anyfunc type ("any" because the type could hold functions of any signature), but unfortunately this anyfunc type couldn’t be stored in linear memory for security reasons. Linear memory exposes the raw contents of stored values as bytes and this would allow wasm content to arbitrarily observe and corrupt raw function addresses, which is something that cannot be allowed on the web.
The solution was to store function references in a table and pass around table indices instead, which are just i32 values. call_indirect’s operand can therefore simply be an i32 index value.
So how do we place wasm functions in our table? Just like data sections can be used to initialize regions of linear memory with bytes, elem sections can be used to initialize regions of tables with functions:
(module
(table 2 anyfunc)
(elem (i32.const 0) $f1 $f2)
(func $f1 (result i32)
i32.const 42)
(func $f2 (result i32)
i32.const 13)
...
)
(table 2 anyfunc), the 2 is the initial size of the table (meaning it will store two references) and anyfunc declares that the element type of these references is "a function with any signature". In the current iteration of WebAssembly, this is the only allowed element type, but in the future, more element types will be added.func) sections are just like any other declared wasm functions. These are the functions we are going to refer to in our table (for example’s sake, each one just returns a constant value). Note that the order the sections are declared in doesn’t matter here — you can declare your functions anywhere and still refer to them in your elem section.elem section can list any subset of the functions in a module, in any order, allowing duplicates. This is a list of the functions that are to be referenced by the table, in the order they are to be referenced.(i32.const 0) value inside the elem section is an offset — this needs to be declared at the start of the section, and specifies at what index in the table function references start to be populated. Here we’ve specified 0, and a size of 2 (see above), so we can fill in two references at indexes 0 and 1. If we wanted to start writing our references at offset 1, we’d have to write (i32.const 1), and the table size would have to be 3.Note: Uninitialized elements are given a default throw-on-call value.
In JavaScript, the equivalent calls to create such a table instance would look something like this:
function() {
// table section
var tbl = new WebAssembly.Table({initial:2, element:"anyfunc"});
// function sections:
var f1 = function() { … }
var f2 = function() { … }
// elem section
tbl.set(0, f1);
tbl.set(1, f2);
};
Moving on, now we’ve defined the table we need to use it somehow. Let's use this section of code to do so:
(type $return_i32 (func (result i32))) ;; if this was f32, type checking would fail (func (export "callByIndex") (param $i i32) (result i32) get_local $i call_indirect (type $return_i32))
(type $return_i32 (func (param i32))) block specifies a type, with a reference name. This type is used when performing type checking of the table function reference calls later on. Here we are saying that the references need to be functions that return an i32 as a result.callByIndex. This will take one i32 as a parameter, which is given the argument name $i.$i.call_indirect to call a function from the table — it implicitly pops the value of $i off the stack. The net result of this is that the callByIndex function invokes the $i’th function in the table.You could also declare the call_indirect parameter explicitly during the command call instead of before it, like this:
(call_indirect (type $return_i32) (get_local $i))
In a higher level, more expressive language like JavaScript, you could imagine doing the same thing with an array (or probably more likely, object) containing functions. The pseudo code would look something like tbl[i]().
So, back to the typechecking. Since WebAssembly is typechecked, and anyfunc means "any function signature", we have to supply the presumed signature of the callee at the callsite, hence we include the $return_i32 type, to tell the program a function returning an i32 is expected. If the callee doesn’t have a matching signature (say an f32 is returned instead), a {{jsxref("WebAssembly.RuntimeError")}} is thrown.
So what links the call_indirect to the table we are calling? The answer is that there is only one table allowed right now per module instance, and that is what call_indirect is implicitly calling. In the future, when multiple tables are allowed, we would also need to specify a table identifier of some kind, along the lines of
call_indirect $my_spicy_table (type $i32_to_void)
The full module all together looks like this, and can be found in our wasm-table.wat example file:
(module
(table 2 anyfunc)
(func $f1 (result i32)
i32.const 42)
(func $f2 (result i32)
i32.const 13)
(elem (i32.const 0) $f1 $f2)
(type $return_i32 (func (result i32)))
(func (export "callByIndex") (param $i i32) (result i32)
get_local $i
call_indirect (type $return_i32))
)
We load it into a webpage using the following JavaScript:
WebAssembly.instantiateStreaming(fetch('wasm-table.wasm'))
.then(obj => {
console.log(obj.instance.exports.callByIndex(0)); // returns 42
console.log(obj.instance.exports.callByIndex(1)); // returns 13
console.log(obj.instance.exports.callByIndex(2)); // returns an error, because there is no index position 2 in the table
});
Note: You can find this example on GitHub as wasm-table.html (see it live also).
Note: Just like Memory, Tables can also be created from JavaScript (see WebAssembly.Table()) as well as imported to/from another wasm module.
Because JavaScript has full access to function references, the Table object can be mutated from JavaScript by the grow(), get() and set() methods. When WebAssembly gets reference types, WebAssembly code will be able to mutate tables itself with get_elem/set_elem instructions.
Because tables are mutable, they can be used to implement sophisticated load-time and run-time dynamic linking schemes. When a program is dynamically linked, multiple instances share the same memory and table. This is symmetric to a native application where multiple compiled .dlls share a single process’s address space.
To see this in action, we’ll create a single import object containing a Memory object and a Table object, and pass this same import object to multiple instantiate() calls.
Our .wat examples look like so:
shared0.wat:
(module (import "js" "memory" (memory 1)) (import "js" "table" (table 1 anyfunc)) (elem (i32.const 0) $shared0func) (func $shared0func (result i32) i32.const 0 i32.load) )
shared1.wat:
(module (import "js" "memory" (memory 1)) (import "js" "table" (table 1 anyfunc)) (type $void_to_i32 (func (result i32))) (func (export "doIt") (result i32) i32.const 0 i32.const 42 i32.store ;; store 42 at address 0 i32.const 0 call_indirect (type $void_to_i32)) )
These work as follows:
shared0func is defined in shared0.wat, and stored in our imported table.0, and then uses the i32.load command to load the value contained in the provided memory index. The index provided is 0 — again, it implicitly pops the previous value off the stack. So shared0func loads and returns the value stored at memory index 0.shared1.wat, we export a function called doIt — this fucntion creates two constants containing the values 0 and 42, then calls i32.store to store a provided value at a provided index of the imported memory. Again, it implicitly pops these values off the stack, so the result is that it stores the value 42 in memory index 0,0, then call the function at this index 0 of the table, which is shared0func, stored there earlier by the elem block in shared0.wat.shared0func loads the 42 we stored in memory using the i32.store command in shared1.wat.Note: The above expressions again pop values from the stack implicitly, but you could declare these explicitly inside the command calls instead, for example:
(i32.store (i32.const 0) (i32.const 42)) (call_indirect (type $void_to_i32) (i32.const 0))
After converting to assembly, we then use shared0.wasm and shared1.wasm in JavaScript via the following code:
var importObj = {
js: {
memory : new WebAssembly.Memory({ initial: 1 }),
table : new WebAssembly.Table({ initial: 1, element: "anyfunc" })
}
};
Promise.all([
WebAssembly.instantiateStreaming(fetch('shared0.wasm'), importObj),
WebAssembly.instantiateStreaming(fetch('shared1.wasm'), importObj)
]).then(function(results) {
console.log(results[1].instance.exports.doIt()); // prints 42
});
Each of the modules that is being compiled can import the same memory and table objects and thus share the same linear memory and table "address space".
Note: You can find this example on GitHub as shared-address-space.html (see it live also).
This finishes our high-level tour of the major components of the WebAssembly text format and how they get reflected in the WebAssembly JS API.