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ückgegebene Promise wird sowohl in ein kompiliertes WebAssembly.Module als auch seine erste WebAssembly.Instance aufgelöst.
  • Die sekundäre Überladung nimmt ein bereits kompiliertes WebAssembly.Module und gibt ein Promise zurück, das zu einer Instance dieses Module aufgelöst wird. Diese Überladung ist nützlich, wenn das Module 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

js
WebAssembly.instantiate(bufferSource, importObject);

Parameter

bufferSource

Ein Typed Array oder ein ArrayBuffer, das den Binärcode des zu kompilierenden Wasm-Moduls enthält, oder ein WebAssembly.Module.

importObject Optional

Ein Objekt, das die in die neu erstellte Instance zu importierenden Werte enthält, wie z.B. Funktionen oder WebAssembly.Memory-Objekte. Es muss eine passende Eigenschaft für jeden deklarierten Import des kompilierten Moduls vorhanden sein, sonst wird ein WebAssembly.LinkError ausgelöst.

Rückgabewert

Ein Promise, das zu einem ResultObject aufgelöst wird, das zwei Felder enthält:

Ausnahmen

Sekundäre Überladung — Verwenden einer Modulobjektinstanz

js
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 oder WebAssembly.Memory-Objekte. Es muss eine passende Eigenschaft für jeden deklarierten Import von module vorhanden sein, sonst wird ein WebAssembly.LinkError ausgelöst.

Rückgabewert

Ein Promise, das zu einem WebAssembly.Instance-Objekt aufgelöst wird.

Ausnahmen

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.

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: 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().

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

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

Spezifikationen

Specification
WebAssembly JavaScript Interface
# dom-webassembly-instantiate

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch