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 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é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
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 objetWebAssembly.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 exceptionWebAssembly.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
, ouWebAssembly.RuntimeError
selon l'origine de l'échec.
Seconde forme : utiliser une instance d'un module
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 exceptionWebAssembly.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
, ouWebAssembly.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.
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()
.
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.
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