WebAssembly.instantiate()

bufferSource

Ein Typed Array oder ArrayBuffer mit dem Binärcode des zu kompilierenden Wasm-Moduls oder ein WebAssembly.Module.

module

Das zu instanziierende WebAssembly.Module-Objekt.

importObject Optional

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

compileOptions Optional

Ein Objekt mit Kompilierungsoptionen. Die Eigenschaften können Folgendes enthalten:

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 Stringkonstanten angibt. Diese Eigenschaft muss angegeben werden, wenn Sie importierte globale Stringkonstanten im Wasm-Modul verwenden möchten.

Wenn ein bufferSource übergeben wird, gibt er ein Promise zurück, das auf ein ResultObject aufgelöst wird, das zwei Felder enthält:

• module: Ein WebAssembly.Module-Objekt, das das kompilierte WebAssembly-Modul darstellt. Dieses Module 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 er ein Promise zurück, das auf ein WebAssembly.Instance-Objekt aufgelöst wird.

• 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, abhängig von der Ursache des Fehlers.

Nachdem wir einige WebAssembly-Bytecode mithilfe von fetch abgerufen haben, kompilieren und instanziieren wir das Modul mithilfe der WebAssembly.instantiate()-Funktion, indem wir eine JavaScript-Funktion in das WebAssembly-Modul importieren. Dann rufen wir eine exportierte WebAssembly-Funktion auf, die vom 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 (sehen Sie unsere index-compile.html Demo auf GitHub und sehen Sie es live) kompiliert den geladenen simple.wasm-Bytecode mit der Methode WebAssembly.compileStreaming() und sendet ihn dann an einen Worker mittels 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 zu verwendende Modul und richten einen Ereignis-Handler ein, um das Modul vom Haupt-Thread zu empfangen. Wenn das Modul empfangen wird, erstellen wir eine Instanz daraus mithilfe der WebAssembly.instantiate()-Methode 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 Stringkonstanten beim Kompilieren und Instanziieren des Wasm-Moduls mit instantiate(), bevor die exportierte main()-Funktion ausgeführt wird (die "hello world!" in die Konsole ausgibt). Sehen Sie es live.

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

• WebAssembly Übersichtsseite
• WebAssembly-Konzepte
• Verwendung der WebAssembly-JavaScript-API