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 WebAssembly.instantiate() Funktion 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 löst sich sowohl in ein kompiliertes WebAssembly.Module als auch in seine erste WebAssembly.Instance auf.
  • Die sekundäre Überladung nimmt ein bereits kompiliertes WebAssembly.Module und gibt ein Promise zurück, das in eine Instance dieses Module aufgelöst wird. Diese Überladung ist nützlich, wenn das Module bereits kompiliert wurde.

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

Syntax

Primäre Überladung — übergibt Wasm-Binärcode

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

Parameter

bufferSource

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

importObject Optional

Ein Objekt, das die Werte enthält, die in die neu erstellte Instance importiert werden sollen, 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.

compileOptions Optional

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

builtins Optional

Ein Array von Zeichenfolgen, das die Verwendung von JavaScript builtins im kompilierten Wasm-Modul ermöglicht. Die Zeichenfolgen definieren die zu aktivierenden Builtins. 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 spezifiziert. 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 — übergibt ein Modulobjektexemplar

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

compileOptions Optional

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

builtins Optional

Ein Array von Zeichenfolgen, das die Verwendung von JavaScript builtins im kompilierten Wasm-Modul ermöglicht. Die Zeichenfolgen definieren die zu aktivierenden Builtins. 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 spezifiziert. 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 werden Sie wahrscheinlich WebAssembly.instantiateStreaming() verwenden wollen, da es effizienter ist als instantiate().

Erstes Überladung-Beispiel

Nachdem Sie mit fetch etwas WebAssembly-Bytecode abgerufen haben, kompilieren und instanziieren wir das Modul mit der WebAssembly.instantiate() Funktion und importieren eine JavaScript-Funktion in das WebAssembly-Modul im Prozess. Wir rufen dann 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 (sehen Sie es sich auch live an).

Zweites Überladung-Beispiel

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

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, dann richten wir einen Ereignishandler ein, um das Modul vom Haupt-Thread zu empfangen. Wenn das Modul empfangen wird, erstellen wir eine Instanz daraus mit der WebAssembly.instantiate() Methode und rufen eine darin 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();
  });
};

Aktivieren von JavaScript builtins und globalen Zeichenfolgenimporten

Dieses Beispiel aktiviert JavaScript-String-Builtins und importierte globale Zeichenfolgenkonstanten, wenn das Wasm-Modul mit instantiate() kompiliert und instanziiert wird, bevor die exportierte main() Funktion (die "hello world!" in die Konsole protokolliert) ausgeführt wird. 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

BCD tables only load in the browser

Siehe auch