WebAssembly.instantiateStreaming()

Syntax

WebAssembly.instantiateStreaming(source)
WebAssembly.instantiateStreaming(source, importObject)
WebAssembly.instantiateStreaming(source, importObject, compileOptions)

Parameter

source

Ein Response-Objekt oder ein Promise, das mit einem solchen Objekt erfüllt wird. Es stellt die Quelle eines Wasm-Moduls dar, das Sie streamen, kompilieren und instanziieren möchten.

importObject Optional

Ein Objekt mit den Werten, die in die neu erstellte Instance importiert werden sollen, beispielsweise Funktionen oder WebAssembly.Memory-Objekte. Für jeden deklarierten Import des kompilierten Moduls muss eine passende Eigenschaft vorhanden sein, andernfalls wird ein WebAssembly.LinkError ausgelöst.

compileOptions Optional

Ein Objekt mit Kompilierungsoptionen. Es kann folgende Eigenschaften enthalten:

builtins Optional

Ein Array von Strings, das die Verwendung von JavaScript-Built-ins im kompilierten Wasm-Modul ermöglicht. Die Strings legen fest, welche Built-ins Sie aktivieren möchten. Derzeit ist nur der Wert "js-string" verfügbar, der JavaScript-String-Built-ins 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

Ein Promise, das mit einem ResultObject erfüllt wird, das zwei Felder enthält:

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

Ausnahmen

• Wenn einer der Parameter nicht den richtigen Typ oder die richtige Struktur hat, wird das Promise mit einem TypeError abgelehnt.
• Wenn die Antwort einen falschen MIME-Typ hat (statt application/wasm), wird das Promise mit einem TypeError abgelehnt.
• Wenn die Operation fehlschlägt, wird das Promise je nach Ursache des Fehlers mit einem WebAssembly.CompileError, WebAssembly.LinkError oder WebAssembly.RuntimeError abgelehnt.

Beispiele

Instanziieren per Streaming

Das folgende Beispiel (siehe die Demo „instantiate-streaming.html“ auf GitHub; Sie können sie auch live ansehen) streamt ein Wasm-Modul direkt aus einer Quelle, kompiliert und instanziiert es anschließend. Das Promise wird dabei mit einem ResultObject erfüllt. Da die Funktion instantiateStreaming() ein Promise für ein Response-Objekt akzeptiert, können Sie ihr direkt einen Aufruf von fetch() übergeben. Sobald das Promise erfüllt wird, wird die Antwort an die Funktion übergeben.

const importObject = {
  my_namespace: { imported_func: (arg) => console.log(arg) },
};

WebAssembly.instantiateStreaming(fetch("simple.wasm"), importObject).then(
  (obj) => obj.instance.exports.exported_func(),
);

Anschließend wird auf die instance-Eigenschaft des ResultObject zugegriffen und die darin enthaltene exportierte Funktion aufgerufen.

JavaScript-Built-ins und globale String-Importe aktivieren

Dieses Beispiel aktiviert JavaScript-String-Built-ins und importierte globale String-Konstanten beim Kompilieren und Instanziieren des Wasm-Moduls mit instantiateStreaming(). Anschließend wird die exportierte Funktion main() ausgeführt, die "hello world!" in der Konsole ausgibt. Sehen Sie sich das Beispiel live an.

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

WebAssembly.instantiateStreaming(
  fetch("log-concat.wasm"),
  importObject,
  compileOptions,
).then((result) => result.instance.exports.main());

Spezifikationen

Browser-Kompatibilität

Siehe auch

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