WebAssembly.instantiate()

La fonction 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 bytecode WebAssembly

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

Paramètres

bufferSource
Un tableau typé ou un ArrayBuffer qui contient le bytecode du module WebAssembly qu'on souhaite compiler.
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é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 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

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 bytecode 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.

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 WebAssembly.compileStreaming() puis on envoie le r√©sultat √† un worker gr√Ęce √† la m√©thode 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 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
WebAssembly JavaScript Interface
La définition de 'instantiate()' dans cette spécification.
Version de travail Brouillon de définition initiale.

Compatibilité des navigateurs

BCD tables only load in the browser

Voir aussi