WebAssembly.instantiate()

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.

importObject Optional

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.

compileOptions Optional

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

builtins Optional

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.

importedStringConstants Optional

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.

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

• module: Ein WebAssembly.Module-Objekt, das das kompilierte WebAssembly-Modul darstellt. Dieses Modul kann erneut instanziiert, über postMessage() geteilt oder gecached werden.
• instance: Ein WebAssembly.Instance-Objekt, das alle Exportierten WebAssembly-Funktionen enthält.

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

• Wenn einer der Parameter nicht den richtigen Typ oder die richtige Struktur hat, wird das Promise mit einem TypeError abgelehnt.
• Wenn die Operation fehlschlägt, wird das Promise mit einem WebAssembly.CompileError, WebAssembly.LinkError oder WebAssembly.RuntimeError abgelehnt, je nach Ursache des Fehlers.

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.

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

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

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.

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

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.

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

• Überblick über WebAssembly
• WebAssembly-Konzepte
• Verwenden der WebAssembly-JavaScript-API