WebAssembly.instantiate() - WebAssembly | MDN

Seitenleiste umschalten

Farbschema

Systemeinstellung
Hell
Dunkel

Deutsch

Sprache merken Mehr erfahren

WebAssembly.instantiate()

Baseline Weitgehend verfügbar *

Diese Funktion ist gut etabliert und funktioniert auf vielen Geräten und in vielen Browserversionen. Sie ist seit Oktober 2017 browserübergreifend verfügbar.

* Einige Teile dieser Funktion werden möglicherweise unterschiedlich gut unterstützt.

Die statische Methode 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 Instanzierung in einem Schritt durch. Das zurückgegebene Promise löst sich sowohl in ein kompilierbares WebAssembly.Module als auch in seine erste WebAssembly.Instance auf.
Die sekundäre Überladung nimmt ein bereits kompilierbares WebAssembly.Module entgegen 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 abzurufen und zu instanziieren. Wenn möglich, sollten Sie die neuere Methode WebAssembly.instantiateStreaming() verwenden, die ein Modul in einem Schritt direkt aus dem Rohbytecode abruft, kompiliert und instanziiert und somit keine Umwandlung in einen ArrayBuffer erfordert.

In diesem Artikel

Syntax

js
// 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 Binärcode des zu kompilierenden Wasm-Moduls enthält.

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 für jeden deklarierten Import des kompilierten Moduls eine passende Eigenschaft geben, andernfalls wird ein WebAssembly.LinkError ausgelöst.

compileOptions Optional

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

builtins Optional

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

importedStringConstants Optional

Ein String, der einen Namensraum für importierte globale String-Konstanten angibt. Diese Eigenschaft muss angegeben werden, wenn Sie importierte globale String-Konstanten im Wasm-Modul verwenden möchten.

Rückgabewert

Wird ein bufferSource übergeben, gibt es ein Promise zurück, das sich in ein ResultObject auflöst, das zwei Felder enthält:

module: Ein WebAssembly.Module-Objekt, das das kompilierte WebAssembly-Modul repräsentiert. Dieses Module kann erneut instanziiert, über postMessage() geteilt oder zwischengespeichert werden.
instance: Ein WebAssembly.Instance-Objekt, das alle exportierten WebAssembly-Funktionen enthält.

Wird ein module übergeben, gibt es ein Promise zurück, das sich in ein WebAssembly.Instance-Objekt auflöst.

Ausnahmen

Wenn einer der Parameter nicht den richtigen Typ oder die richtige Struktur aufweist, 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.

Beispiele

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

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.

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 auch live).

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

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

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 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 ausgeführt wird (die "hello world!" in die Konsole protokolliert). 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());

WebAssembly Übersicht
WebAssembly-Konzepte
Verwendung der WebAssembly JavaScript API

Help improve MDN

War diese Übersetzung hilfreich?

Ja Nein

Erfahren Sie, wie Sie beitragen können Diese Seite wurde automatisch aus dem Englischen übersetzt.

Übersetzung auf GitHub anzeigen • Fehler mit dieser Übersetzung melden