WebAssembly.instantiate()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since October 2017.
Die Funktion WebAssembly.instantiate()
ermöglicht es Ihnen, WebAssembly-Code zu kompilieren und zu instanziieren. Diese Funktion hat zwei Überladungen:
- Die primäre Überladung nimmt den WebAssembly-Binärcode in Form eines Typed Array oder eines
ArrayBuffer
und führt sowohl die Kompilierung als auch die Instanziierung in einem Schritt durch. Das zurückgegebenePromise
wird sowohl in ein kompiliertesWebAssembly.Module
als auch seine ersteWebAssembly.Instance
aufgelöst. - Die sekundäre Überladung nimmt ein bereits kompiliertes
WebAssembly.Module
und gibt einPromise
zurück, das zu einerInstance
diesesModule
aufgelöst wird. Diese Überladung ist nützlich, wenn dasModule
bereits kompiliert wurde.
Warnung: Diese Methode ist nicht die effizienteste Art, Wasm-Module abzurufen und zu instanziieren. Wenn möglich, sollten Sie stattdessen die neuere Methode WebAssembly.instantiateStreaming()
verwenden, die ein Modul in einem Schritt direkt vom Roh-Bytecode abruft, kompiliert und instanziiert, ohne eine Umwandlung in einen ArrayBuffer
zu erfordern.
Syntax
Primäre Überladung — Verwenden von Wasm-Binärcode
WebAssembly.instantiate(bufferSource, importObject);
Parameter
bufferSource
-
Ein Typed Array oder ein
ArrayBuffer
, das den Binärcode des zu kompilierenden Wasm-Moduls enthält, oder einWebAssembly.Module
. importObject
Optional-
Ein Objekt, das die in die neu erstellte
Instance
zu importierenden Werte enthält, wie z.B. Funktionen oderWebAssembly.Memory
-Objekte. Es muss eine passende Eigenschaft für jeden deklarierten Import des kompilierten Moduls vorhanden sein, sonst wird einWebAssembly.LinkError
ausgelöst.
Rückgabewert
Ein Promise
, das zu einem ResultObject
aufgelöst wird, das zwei Felder enthält:
module
: EinWebAssembly.Module
-Objekt, das das kompilierte WebAssembly-Modul repräsentiert. DiesesModule
kann erneut instanziiert, überpostMessage()
geteilt oder zwischen gespeichert werden.instance
: EinWebAssembly.Instance
-Objekt, das alle exportierten WebAssembly-Funktionen enthält.
Ausnahmen
- Wenn einer der Parameter nicht den richtigen Typ oder die richtige Struktur hat, wird das Promise mit einem
TypeError
abgelehnt. - Wenn der Vorgang fehlschlägt, wird das Promise mit einem
WebAssembly.CompileError
,WebAssembly.LinkError
oderWebAssembly.RuntimeError
abgelehnt, abhängig von der Ursache des Fehlers.
Sekundäre Überladung — Verwenden einer Modulobjektinstanz
WebAssembly.instantiate(module, importObject);
Parameter
module
-
Das
WebAssembly.Module
-Objekt, das instanziiert werden soll. importObject
Optional-
Ein Objekt, das die in die neu erstellte
Instance
zu importierenden Werte enthält, wie z.B. Funktionen oderWebAssembly.Memory
-Objekte. Es muss eine passende Eigenschaft für jeden deklarierten Import vonmodule
vorhanden sein, sonst wird einWebAssembly.LinkError
ausgelöst.
Rückgabewert
Ein Promise
, das zu einem WebAssembly.Instance
-Objekt aufgelöst wird.
Ausnahmen
- Wenn einer der Parameter nicht den richtigen Typ oder die richtige Struktur hat, wird ein
TypeError
geworfen. - Wenn der Vorgang fehlschlägt, wird das Promise mit einem
WebAssembly.CompileError
,WebAssembly.LinkError
oderWebAssembly.RuntimeError
abgelehnt, abhängig von der Ursache des Fehlers.
Beispiele
Hinweis: In den meisten Fällen werden Sie wahrscheinlich WebAssembly.instantiateStreaming()
verwenden möchten, da es effizienter als instantiate()
ist.
Erstes Überladungsbeispiel
Nachdem einige WebAssembly-Bytecodes mit fetch abgerufen wurden, kompilieren und instanziieren wir das Modul mit der Funktion WebAssembly.instantiate()
, indem wir dabei eine JavaScript-Funktion in das WebAssembly-Modul importieren. Dann rufen wir eine exportierte WebAssembly-Funktion auf, die von der Instance
exportiert wird.
const importObject = {
my_namespace: {
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());
Hinweis: Sie können dieses Beispiel auch unter index.html auf GitHub finden (sehen Sie es auch live).
Zweites Überladungsbeispiel
Das folgende Beispiel (siehe unser index-compile.html Demo auf GitHub und sehen Sie es live auch) kompiliert den geladenen simple.wasm-Bytecode mit der Methode WebAssembly.compileStreaming()
und sendet ihn dann an einen Worker mit postMessage()
.
const worker = new Worker("wasm_worker.js");
WebAssembly.compileStreaming(fetch("simple.wasm")).then((mod) =>
worker.postMessage(mod),
);
Im Worker (siehe
wasm_worker.js
) definieren wir ein Importobjekt für das Modul und richten dann einen Ereignishandler ein, um das Modul vom Hauptthread zu empfangen. Wenn das Modul empfangen wird, erstellen wir eine Instanz daraus mit der Methode WebAssembly.instantiate()
und rufen eine darin enthaltene exportierte Funktion auf.
const importObject = {
my_namespace: {
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();
});
};
Spezifikationen
Specification |
---|
WebAssembly JavaScript Interface # dom-webassembly-instantiate |
Browser-Kompatibilität
BCD tables only load in the browser