WebAssembly.instantiate()

Syntax

// 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 ein ArrayBuffer, das den Binrcode des zu kompilierenden Wasm-Moduls enthlt.

module

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

importObject Optional

Ein Objekt, das die Werte enthlt, die in die neu erstellte Instance importiert werden sollen, wie z.B. Funktionen oder WebAssembly.Memory-Objekte. Es muss fr jeden deklarierten Import des kompilierten Moduls eine passende Eigenschaft geben, andernfalls wird ein WebAssembly.LinkError ausgelst.

compileOptions Optional

Ein Objekt, das Kompilierungsoptionen enthlt. Eigenschaften knnen beinhalten:

builtins Optional

Ein Array von Strings, das die Verwendung von JavaScript-Builtins im kompilierten Wasm-Modul ermglicht. Die Strings definieren die Builtins, die Sie aktivieren mchten. Derzeit ist der einzige verfgbare Wert "js-string", der JavaScript-String-Builtins aktiviert.

importedStringConstants Optional

Ein String, der einen Namensraum fr importierte globale String-Konstanten angibt. Diese Eigenschaft muss angegeben werden, wenn Sie importierte globale String-Konstanten im Wasm-Modul verwenden mchten.

Rckgabewert

Wird ein bufferSource bergeben, gibt es ein Promise zurck, das sich in ein ResultObject auflst, das zwei Felder enthlt:

• module: Ein WebAssembly.Module-Objekt, das das kompilierte WebAssembly-Modul reprsentiert. Dieses Module kann erneut instanziiert, ber postMessage() geteilt oder zwischengespeichert werden.
• instance: Ein WebAssembly.Instance-Objekt, das alle exportierten WebAssembly-Funktionen enthlt.

Wird ein module bergeben, gibt es ein Promise zurck, das sich in ein WebAssembly.Instance-Objekt auflst.

Ausnahmen

• Wenn einer der Parameter nicht den richtigen Typ oder die richtige Struktur aufweist, wird das Promise mit einem TypeError abgelehnt.
• Wenn die Operation fehlschlgt, wird das Promise mit einem WebAssembly.CompileError, WebAssembly.LinkError oder WebAssembly.RuntimeError abgelehnt, abhngig von der Ursache des Fehlers.

Beispiele

Erstes berladungsbeispiel

Nach dem Abrufen einiger WebAssembly-Bytes mit fetch, kompilieren und instanziieren wir das Modul mit der Funktion WebAssembly.instantiate(), indem wir eine JavaScript-Funktion im Prozess in das WebAssembly-Modul importieren. Danach rufen wir eine exportierte WebAssembly-Funktion auf, die von der Instance exportiert wurde.

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

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 Import-Objekt, das das Modul verwenden soll, 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 exportierte Funktion aus diesem 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();
  });
};

Aktivieren von JavaScript-Builtins und globalen String-Importen

Dieses Beispiel aktiviert JavaScript-String-Builtins und importierte globale String-Konstanten beim Kompilieren und Instanziieren des Wasm-Moduls mit instantiate(), bevor die exportierte main()-Funktion ausgefhrt wird (die "hello world!" in die Konsole protokolliert). Sehen Sie es live laufen.

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

Browser-Kompatibilitt

Siehe auch

• WebAssembly bersicht
• WebAssembly-Konzepte
• Verwendung der WebAssembly JavaScript API