WebAssembly.instantiate()
=========================

La méthode statique **`WebAssembly.instantiate()`** permet de compiler et d'instancier du code WebAssembly. Cette fonction possède deux formes :

* La première forme prend un code binaire WebAssembly sous forme d'un tableau typé ou d'un `ArrayBuffer` et effectue les étapes de compilation et d'instanciation en une fois. La valeur de résolution de la promesse renvoyée se compose d'un module `WebAssembly.Module` compilé et de sa première instance `WebAssembly.Instance`.
* La seconde forme prend un module (`WebAssembly.Module`) déjà compilé et renvoie une promesse dont la valeur de résolution est une instance de ce module. Cette forme s'avère utile lorsque le module a déjà été compilé.

**Attention :** Tant que faire se peut, utiliser la méthode `WebAssembly.instantiateStreaming()`, car elle est plus efficace et récupère, compile et instancie un module en une seule étape à partir du *bytecode* et il n'est pas nécessaire de passer par une conversion en `ArrayBuffer`.

Syntaxe
-------

### Première forme : utiliser le code binaire WebAssembly


```js
WebAssembly.instantiate(bufferSource, importObject);
```


#### Paramètres

`bufferSource`

Un tableau typé ou un `ArrayBuffer` qui contient le *bytecode* du module WebAssembly qu'on souhaite compiler ou un objet `WebAssembly.Module`.

`importObject` Facultatif

Un objet qui contient les valeurs à importer dans l'instance qui sera créée. Ces valeurs peuvent être des fonctions ou des objets `WebAssembly.Memory`. Il doit y avoir une propriété correspondante au sein du module compilé pour chacun des imports, si ce n'est pas le cas, une exception `WebAssembly.LinkError` sera levée.

#### Valeur de retour

Une promesse qui est résolue en un objet qui contient deux champs :

`module`

Un objet `WebAssembly.Module` qui représente le module WebAssembly compilé. Ce module peut être instancié à nouveau grâce à `postMessage()` ou via un cache.

`instance`

Un objet `WebAssembly.Instance` qui contient l'ensemble des fonctions WebAssembly exportées.

#### Exceptions

* Si l'un des paramètres n'a pas le bon type ou la bonne structure, une exception `TypeError` sera levée.
* Si l'opération échoue, la promesse est rompue avec une exception `WebAssembly.CompileError`, `WebAssembly.LinkError`, ou `WebAssembly.RuntimeError` selon l'origine de l'échec.
### Seconde forme : utiliser une instance d'un module


```js
WebAssembly.instantiate(module, importObject);
```


#### Paramètres

`module`

L'objet `WebAssembly.Module` qui doit être instancié.

`importObject` Facultatif

Un objet qui contient les valeurs à importer dans l'instance qui sera créée. Ces valeurs peuvent être des fonctions ou des objets `WebAssembly.Memory`. Il doit y avoir une propriété correspondante au sein du module compilé pour chacun des imports, si ce n'est pas le cas, une exception `WebAssembly.LinkError` sera levée.

#### Valeur de retour

Une promesse qui est résolue en un objet `WebAssembly.Instance`.

#### Exceptions

* Si l'un des paramètres n'est pas du bon type ou n'a pas la bonne structure, une exception `TypeError` est levée.
* Si l'opération échoue, la promesse sera rompue avec une exception `WebAssembly.CompileError`, `WebAssembly.LinkError`, ou `WebAssembly.RuntimeError` selon l'origine de l'échec.
Exemples
--------

**Note :** Dans la plupart des cas, on utilisera plus vraisemblablement `WebAssembly.instantiateStreaming()` qui est plus efficace que `instantiate()`.

### Première forme

Après avoir récupéré le code binaire WebAssembly grâce à `fetch()`, on compile et on instancie le module grâce à la fonction `WebAssembly.instantiate()` et on importe une fonction JavaScript dans le module lors de cette étape. Ensuite, on invoque une fonction WebAssembly exportée via l'instance.


```js
const importObject = {
  imports: {
    imported\_func(arg) {
      console.log(arg);
    },
  },
};

fetch("simple.wasm")
  .then((response) => response.arrayBuffer())
  .then((bytes) => WebAssembly.instantiate(bytes, importObject))
  .then((result) => result.instance.exports.exported\_func());
```


**Note :** Voir le fichier `index.html` sur GitHub (ainsi que la démonstration associée).

### Seconde forme

Dans l'exemple qui suit (tiré du fichier `index-compile.html` sur GitHub et qui dispose d'une démonstration), on compile le *bytecode* du module chargé `simple.wasm` grâce à la fonction `WebAssembly.compileStreaming()` puis on envoie le résultat à un *worker* grâce à la méthode `postMessage()`.


```js
const worker = new Worker("wasm\_worker.js");

WebAssembly.compileStreaming(fetch("simple.wasm")).then((mod) =>
  worker.postMessage(mod),
);
```


Dans le *worker* (cf. `wasm_worker.js`), on définit un objet d'import qui sera utilisé par le module puis on paramètre un gestionnaire d'évènement afin de recevoir le module depuis le *thread* principal. Lorsqu'on reçoit le module, on en crée une instance grâce à la méthode `WebAssembly.instantiate()` puis on appelle une fonction exportée depuis le module.


```js
const importObject = {
  imports: {
    imported\_func(arg) {
      console.log(arg);
    },
  },
};

onmessage = (e) => {
  console.log("module received from main thread");
  const mod = e.data;

  WebAssembly.instantiate(mod, importObject).then((instance) => {
    instance.exports.exported\_func();
  });
};
```

Spécifications
--------------

| Specification |
| --- |
| WebAssembly JavaScript Interface # dom-webassembly-instantiate |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* Le portail WebAssembly
* Les concepts relatifs à WebAssembly
* Utiliser l'API JavaScript WebAssembly