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.

* Some parts of this feature may have varying levels of support.

Die Funktion WebAssembly.instantiate() ermöglicht es Ihnen, WebAssembly-Code zu kompilieren und zu instanziieren. Diese Funktion verfügt über zwei Überladungen:

  • Die primäre Überladung nimmt den WebAssembly-Binärcode in Form eines typisierten Arrays oder eines ArrayBuffer und führt sowohl die Kompilierung als auch die Instanziierung in einem Schritt durch. Das zurückgegebene Promise löst sich zu einem kompilierten WebAssembly.Module und seiner ersten WebAssembly.Instance auf.
  • Die sekundäre Überladung nimmt ein bereits kompiliertes WebAssembly.Module und gibt ein Promise zurück, das sich zu einer Instance dieses Moduls auflöst. Diese Überladung ist nützlich, wenn das Modul 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 aus dem Rohbytecode abruft, kompiliert und instanziiert, und daher keine Konvertierung in einen ArrayBuffer erfordert.

Syntax

js
// Taking Wasm binary code WebAssembly.instantiate(bufferSource) WebAssembly.instantiate(bufferSource, importObject) WebAssembly.instantiate(bufferSource, importObject, compileOptions) // Taking a module object instance WebAssembly.instantiate(module) WebAssembly.instantiate(module, importObject) WebAssembly.instantiate(module, importObject, compileOptions)

Parameter

bufferSource

Ein typisiertes Array oder ArrayBuffer, das den Binärcode des Wasm-Moduls enthält, das Sie kompilieren möchten, oder ein WebAssembly.Module.

module

Das WebAssembly.Module-Objekt, das instanziiert werden soll.

importObjectOptional

Ein Objekt, das die Werte enthält, die in die neu erstellte Instance importiert werden sollen, wie etwa Funktionen oder WebAssembly.Memory-Objekte. Es muss eine übereinstimmende Eigenschaft für jeden deklarierten Import des kompilierten Moduls vorhanden sein, andernfalls wird ein WebAssembly.LinkError ausgelöst.

compileOptionsOptional

Ein Objekt, das Kompilierungsoptionen enthält. Eigenschaften können Folgendes umfassen:

builtinsOptional

Ein Array von Zeichenketten, das die Verwendung von JavaScript-Builtins im kompilierten Wasm-Modul ermöglicht. Die Zeichenketten definieren die Builtins, die Sie aktivieren möchten. Derzeit ist der einzige verfügbare Wert "js-string", der JavaScript-String-Builtins aktiviert.

importedStringConstantsOptional

Eine Zeichenkette, die einen Namespace für importierte globale Zeichenkettenkonstanten angibt. Diese Eigenschaft muss angegeben werden, wenn Sie importierte globale Zeichenkettenkonstanten im Wasm-Modul verwenden möchten.

Rückgabewert

Wenn ein bufferSource übergeben wird, gibt es ein Promise zurück, das sich zu einem ResultObject mit zwei Feldern auflöst:

Wenn ein module übergeben wird, gibt es ein Promise zurück, das sich zu einem WebAssembly.Instance-Objekt auflöst.

Ausnahmen

Beispiele

Hinweis: In den meisten Fällen werden Sie wahrscheinlich WebAssembly.instantiateStreaming() verwenden wollen, da es effizienter ist als instantiate().

Beispiel für die erste Überladung

Nach dem Abrufen einiger WebAssembly-Bytecodes mit fetch kompilieren und instanziieren wir das Modul mithilfe der Funktion WebAssembly.instantiate(), wobei wir eine JavaScript-Funktion in das WebAssembly-Modul importieren. Dann rufen wir eine Exportierte WebAssembly-Funktion auf, die von der Instance exportiert wird.

js
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: Dieses Beispiel finden Sie auch unter index.html auf GitHub (auch live ansehen).

Beispiel für die zweite Überladung

Das folgende Beispiel (siehe unser index-compile.html Demo auf GitHub und auch live ansehen) kompiliert den geladenen simple.wasm-Bytecode mit der Methode WebAssembly.compileStreaming() und sendet ihn dann an einen Worker mithilfe von postMessage().

js
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 zur Verwendung, richten dann einen Ereignishandler ein, um das Modul vom Hauptthread zu empfangen. Wenn das Modul empfangen wird, erstellen wir eine Instanz daraus mithilfe der Methode WebAssembly.instantiate() und rufen eine exportierte Funktion von innen auf.

js
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(); }); };

Aktivieren von JavaScript-Builtins und globalen Zeichenkettenimporten

Dieses Beispiel aktiviert JavaScript-String-Builtins und importierte globale Zeichenkettenkonstanten beim Kompilieren und Instanziieren des Wasm-Moduls mit instantiate(), bevor die exportierte main() Funktion ausgeführt wird (die "hello world!" in die Konsole protokolliert). Hier live sehen.

js
const importObject = { // Regular import m: { log: console.log, }, }; const compileOptions = { builtins: ["js-string"], // Enable JavaScript string builtins importedStringConstants: "string_constants", // Enable imported global string constants }; fetch("log-concat.wasm") .then((response) => response.arrayBuffer()) .then((bytes) => WebAssembly.instantiate(bytes, importObject, compileOptions)) .then((result) => result.instance.exports.main());

Spezifikationen

Specification
WebAssembly JavaScript Interface
# dom-webassembly-instantiate

Browser-Kompatibilität

Siehe auch