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 hat 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 in ein kompiliertes WebAssembly.Module und seine erste WebAssembly.Instance auf.
  • Die sekundäre Überladung nimmt ein bereits kompiliertes WebAssembly.Module und gibt ein Promise zurück, das sich in eine Instance dieses Module auflöst. Diese Überladung ist nützlich, wenn das Module bereits kompiliert wurde.

Warnung: Diese Methode ist nicht der effizienteste Weg, um Wasm-Module zu holen und zu instanziieren. Wenn möglich, sollten Sie die neuere Methode WebAssembly.instantiateStreaming() verwenden, die ein Modul in einem Schritt direkt aus dem Roh-Bytecode abruft, kompiliert und instanziiert, sodass keine Konvertierung in einen ArrayBuffer erforderlich ist.

Syntax

Primäre Überladung — Verarbeitung von Wasm-Binärcode

js
WebAssembly.instantiate(bufferSource);
WebAssembly.instantiate(bufferSource, importObject);
WebAssembly.instantiate(bufferSource, importObject, compileOptions);

Parameter

bufferSource

Ein typisiertes 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 Werte enthält, die in die neu erstellte Instance importiert werden sollen, wie Funktionen oder WebAssembly.Memory-Objekte. Es muss eine passende Eigenschaft für jeden deklarierten Import des kompilierten Moduls vorhanden sein, andernfalls wird ein WebAssembly.LinkError ausgelöst.

compileOptions Optional

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

builtins Optional

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

importedStringConstants Optional

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

Rückgabewert

Ein Promise, das sich in ein ResultObject auflöst, das zwei Felder enthält:

Ausnahmen

Sekundäre Überladung — Verarbeitung eines Modulobjekt-Instanz

js
WebAssembly.instantiate(module);
WebAssembly.instantiate(module, importObject);
WebAssembly.instantiate(module, importObject, compileOptions);

Parameter

module

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

importObject Optional

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

compileOptions Optional

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

builtins Optional

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

importedStringConstants Optional

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

Rückgabewert

Ein Promise, das sich in ein WebAssembly.Instance-Objekt auflöst.

Ausnahmen

Beispiele

Hinweis: In den meisten Fällen möchten Sie wahrscheinlich WebAssembly.instantiateStreaming() verwenden, da dies effizienter ist als instantiate().

Erstes Überladungsbeispiel

Nach dem Abrufen von WebAssembly-Bytecode mit fetch, kompilieren und instanziieren wir das Modul mit 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: Sie können dieses Beispiel auch unter index.html auf GitHub finden (sehen Sie es sich auch live an).

Zweites Überladungsbeispiel

Das folgende Beispiel (siehe unser index-compile.html-Demo auf GitHub und sehen Sie es sich live an 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 zur Verwendung und richten 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 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();
  });
};

Aktivierung von JavaScript-Builtins und globalen Zeichenfolgenimporten

Dieses Beispiel aktiviert JavaScript-String-Builtins und importierte globale Zeichenfolgenkonstanten bei der Kompilierung und Instanziierung des Wasm-Moduls mit instantiate(), bevor es die exportierte main()-Funktion ausführt (die "hello world!" auf die Konsole schreibt). Sehen Sie es live laufen.

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

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
instantiate() static method
compileOptions parameter

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support

Siehe auch