WebAssembly.instantiate()

Baseline Widely available *

Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis ⁨octobre 2017⁩.

* Certaines parties de cette fonctionnalité peuvent bénéficier de prise en charge variables.

La méthode statiqueWebAssembly.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'untableau typé ou d'unArrayBuffer 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 moduleWebAssembly.Module compilé et de sa première instanceWebAssembly.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éthodeWebAssembly.instantiateStreaming(), car elle est plus efficace et récupère, compile et instancie un module en une seule étape à partir dubytecode et il n'est pas nécessaire de passer par une conversion enArrayBuffer.

Syntaxe

Première forme : utiliser le code binaire WebAssembly

WebAssembly.instantiate(bufferSource, importObject);

Paramètres

bufferSource: Untableau typé ou unArrayBuffer qui contient lebytecode du module WebAssembly qu'on souhaite compiler ou un objetWebAssembly.Module.
importObjectFacultatif: Un objet qui contient les valeurs à importer dans l'instance qui sera créée. Ces valeurs peuvent être des fonctions ou des objetsWebAssembly.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 exceptionWebAssembly.LinkError sera levée.

Valeur de retour

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

module: Un objetWebAssembly.Module qui représente le module WebAssembly compilé. Ce module peut être instancié à nouveau grâce àpostMessage() ou viaun cache.
instance: Un objetWebAssembly.Instance qui contient l'ensembledes fonctions WebAssembly exportées.

Exceptions

Si l'un des paramètres n'a pas le bon type ou la bonne structure, une exceptionTypeError sera levée.
Si l'opération échoue, la promesse est rompue avec une exceptionWebAssembly.CompileError,WebAssembly.LinkError, ouWebAssembly.RuntimeError selon l'origine de l'échec.

Seconde forme : utiliser une instance d'un module

WebAssembly.instantiate(module, importObject);

Paramètres

module: L'objetWebAssembly.Module qui doit être instancié.
importObjectFacultatif: Un objet qui contient les valeurs à importer dans l'instance qui sera créée. Ces valeurs peuvent être des fonctions ou des objetsWebAssembly.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 exceptionWebAssembly.LinkError sera levée.

Valeur de retour

Une promesse qui est résolue en un objetWebAssembly.Instance.

Exceptions

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

Exemples

Note :Dans la plupart des cas, on utilisera plus vraisemblablementWebAssembly.instantiateStreaming() qui est plus efficace queinstantiate().

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 fonctionWebAssembly.instantiate() et on importe une fonction JavaScript dans le module lors de cette étape. Ensuite, on invoqueune fonction WebAssembly exportée via l'instance.

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 fichierindex.html sur GitHub (ainsi que la démonstration associée).

Seconde forme

Dans l'exemple qui suit (tiré du fichierindex-compile.html sur GitHub et qui dispose d'une démonstration), on compile lebytecode du module chargésimple.wasm grâce à la fonctionWebAssembly.compileStreaming() puis on envoie le résultat à unworker grâce à la méthodepostMessage().

const worker = new Worker("wasm_worker.js");WebAssembly.compileStreaming(fetch("simple.wasm")).then((mod) =>  worker.postMessage(mod),);

Dans leworker (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 lethread principal. Lorsqu'on reçoit le module, on en crée une instance grâce à la méthodeWebAssembly.instantiate() puis on appelle une fonction exportée depuis le module.

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();  });};