--- title: WebAssembly.instantiate() slug: Web/JavaScript/Reference/Global_Objects/WebAssembly/instantiate tags: - API - JavaScript - Méthode - Reference - WebAssembly translation_of: Web/JavaScript/Reference/Global_Objects/WebAssembly/instantiate original_slug: Web/JavaScript/Reference/Objets_globaux/WebAssembly/instantiate ---
{{JSRef}}

La fonction WebAssembly.instantiate() permet de compiler et d'instancier du code WebAssembly. Cette fonction possède deux formes :

Attention ! Tant que faire se peut, utiliser la méthode {{jsxref("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 {{jsxref("ArrayBuffer")}}.

Syntaxe

Première forme : utiliser le bytecode WebAssembly

Promise<ResultObject> WebAssembly.instantiate(bufferSource, importObject);

Paramètres

bufferSource
Un tableau typé ou un {{jsxref("ArrayBuffer")}} qui contient le bytecode du module WebAssembly qu'on souhaite compiler.
importObject {{optional_inline}}
Un objet qui contient les valeurs à importer dans l'instance qui sera créée. Ces valeurs peuvent être des fonctions ou des objets {{jsxref("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 {{jsxref("WebAssembly.LinkError")}} sera levée.

Valeur de retour

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

Exceptions

Seconde forme : utiliser une instance d'un module

Promise<WebAssembly.Instance> WebAssembly.instantiate(module, importObject);

Paramètres

module
L'objet {{jsxref("WebAssembly.Module")}} qui doit être instancié.
importObject {{optional_inline}}
Un objet qui contient les valeurs à importer dans l'instance qui sera créée. Ces valeurs peuvent être des fonctions ou des objets {{jsxref("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 {{jsxref("WebAssembly.LinkError")}} sera levée.

Valeur de retour

Une promesse qui est résolue en un objet {{jsxref("WebAssembly.Instance")}}.

Exceptions

Exemples

Note : Dans la plupart des cas, on utilisera plus vraisemblablement {{jsxref("WebAssembly.instantiateStreaming()")}} qui est plus efficace que instantiate().

Première forme

Après avoir récupéré le bytecode WebAssembly grâce à fetch(), on compile et on instancie le module grâce à la fonction  {{jsxref("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.

var importObject = {
  imports: {
    imported_func: function(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) qui contient un exemple analogue et qui utilise la fonction utilitaire fetchAndInstantiate().

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 {{jsxref("WebAssembly.compileStreaming()")}} puis on envoie le résultat à un worker grâce à la méthode {{domxref("Worker.postMessage", "postMessage()")}}.

var 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 {{jsxref("WebAssembly.instantiate()")}} puis on appelle une fonction exportée depuis le module.

var importObject = {
  imports: {
    imported_func: function(arg) {
      console.log(arg);
    }
  }
};

onmessage = function(e) {
  console.log('module reçu depuis le thread principal');
  var mod = e.data;

  WebAssembly.instantiate(mod, importObject).then(function(instance) {
    instance.exports.exported_func();
  });
};

Spécifications

Spécification État Commentaires
{{SpecName('WebAssembly JS', '#webassemblyinstantiate', 'instantiate()')}} {{Spec2('WebAssembly JS')}} Brouillon de définition initiale.

Compatibilité des navigateurs

{{Compat("javascript.builtins.WebAssembly.instantiate")}}

Voir aussi