WebAssembly.instantiate()

Syntaxe

Premire forme : utiliser le code binaire WebAssembly

WebAssembly.instantiate(bufferSource, importObject);

Paramtres

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 cre. Ces valeurs peuvent tre des fonctions ou des objets WebAssembly.Memory. Il doit y avoir une proprit correspondante au sein du module compil pour chacun des imports, si ce n'est pas le cas, une exception WebAssembly.LinkError sera leve.

Valeur de retour

Une promesse qui est rsolue en un objet qui contient deux champs :

module

Un objet WebAssembly.Module qui reprsente le module WebAssembly compil. Ce module peut tre instanci nouveau grce postMessage() ou via un cache.

instance

Un objet WebAssembly.Instance qui contient l'ensemble des fonctions WebAssembly exportes.

Exceptions

• Si l'un des paramtres n'a pas le bon type ou la bonne structure, une exception TypeError sera leve.
• Si l'opration 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

WebAssembly.instantiate(module, importObject);

Paramtres

module

L'objet WebAssembly.Module qui doit tre instanci.

importObject Facultatif

Un objet qui contient les valeurs importer dans l'instance qui sera cre. Ces valeurs peuvent tre des fonctions ou des objets WebAssembly.Memory. Il doit y avoir une proprit correspondante au sein du module compil pour chacun des imports, si ce n'est pas le cas, une exception WebAssembly.LinkError sera leve.

Valeur de retour

Une promesse qui est rsolue en un objet WebAssembly.Instance.

Exceptions

• Si l'un des paramtres n'est pas du bon type ou n'a pas la bonne structure, une exception TypeError est leve.
• Si l'opration choue, la promesse sera rompue avec une exception WebAssembly.CompileError, WebAssembly.LinkError, ou WebAssembly.RuntimeError selon l'origine de l'chec.

Exemples

Premire forme

Aprs avoir rcupr le code binaire WebAssembly grce fetch(), on compile et on instancie le module grce la fonction WebAssembly.instantiate() et on importe une fonction JavaScript dans le module lors de cette tape. Ensuite, on invoque une fonction WebAssembly exporte 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());

Seconde forme

Dans l'exemple qui suit (tir du fichier index-compile.html sur GitHub et qui dispose d'une dmonstration), on compile le bytecode du module charg simple.wasm grce la fonction WebAssembly.compileStreaming() puis on envoie le rsultat un worker grce la mthode postMessage().

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 dfinit un objet d'import qui sera utilis par le module puis on paramtre un gestionnaire d'vnement afin de recevoir le module depuis le thread principal. Lorsqu'on reoit le module, on en cre une instance grce la mthode WebAssembly.instantiate() puis on appelle une fonction exporte 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();
  });
};

Spcifications

Compatibilit des navigateurs

Voir aussi

• Le portail WebAssembly
• Les concepts relatifs WebAssembly
• Utiliser l'API JavaScript WebAssembly