WebAssembly.instantiate()
Baseline Widely available *
This feature is well established and works across many devices and browser versions. It’s been available across browsers since October 2017.
* Some parts of this feature may have varying levels of support.
Die Funktion 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 Instanziierung in einem Schritt durch. Das zurückgegebenePromise
löst sich in ein kompiliertesWebAssembly.Module
und seine ersteWebAssembly.Instance
auf. - Die sekundäre Überladung nimmt ein bereits kompiliertes
WebAssembly.Module
und gibt einPromise
zurück, das sich in eineInstance
diesesModule
auflöst. Diese Überladung ist nützlich, wenn dasModule
bereits kompiliert wurde.
Warnung:
Diese Methode ist nicht der effizienteste Weg, um Wasm-Module zu holen und zu instanziieren. Wenn möglich, sollten Sie die neuere Methode WebAssembly.instantiateStreaming()
verwenden, die ein Modul in einem Schritt direkt aus dem Roh-Bytecode abruft, kompiliert und instanziiert, sodass keine Konvertierung in einen ArrayBuffer
erforderlich ist.
Syntax
Primäre Überladung — Verarbeitung von Wasm-Binärcode
WebAssembly.instantiate(bufferSource);
WebAssembly.instantiate(bufferSource, importObject);
WebAssembly.instantiate(bufferSource, importObject, compileOptions);
Parameter
bufferSource
-
Ein typisiertes Array oder ein
ArrayBuffer
, das den Binärcode des zu kompilierenden Wasm-Moduls enthält, oder einWebAssembly.Module
. importObject
Optional-
Ein Objekt, das die Werte enthält, die in die neu erstellte
Instance
importiert werden sollen, wie Funktionen oderWebAssembly.Memory
-Objekte. Es muss eine passende Eigenschaft für jeden deklarierten Import des kompilierten Moduls vorhanden sein, andernfalls wird einWebAssembly.LinkError
ausgelöst. compileOptions
Optional-
Ein Objekt, das Kompilierungsoptionen enthält. Eigenschaften können umfassen:
builtins
Optional-
Ein Array von Zeichenfolgen, das die Verwendung von JavaScript Builtins im kompilierten Wasm-Modul ermöglicht. Die Zeichenfolgen 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 Zeichenfolge, die einen Namensraum für importierte globale Zeichenfolgenkonstanten angibt. Diese Eigenschaft muss angegeben werden, wenn Sie importierte globale Zeichenfolgenkonstanten im Wasm-Modul verwenden möchten.
Rückgabewert
Ein Promise
, das sich in ein ResultObject
auflöst, das zwei Felder enthält:
module
: EinWebAssembly.Module
-Objekt, das das kompilierte WebAssembly-Modul darstellt. DiesesModule
kann erneut instanziiert, überpostMessage()
geteilt oder zwischengespeichert werden.instance
: EinWebAssembly.Instance
-Objekt, das alle exportierten WebAssembly-Funktionen enthält.
Ausnahmen
- Wenn einer der Parameter nicht den korrekten Typ oder die richtige Struktur hat, wird das Promise mit einem
TypeError
abgelehnt. - Wenn der Vorgang fehlschlägt, wird das Promise mit einem
WebAssembly.CompileError
,WebAssembly.LinkError
oderWebAssembly.RuntimeError
abgelehnt, abhängig von der Ursache des Fehlers.
Sekundäre Überladung — Verarbeitung eines Modulobjekt-Instanz
WebAssembly.instantiate(module);
WebAssembly.instantiate(module, importObject);
WebAssembly.instantiate(module, importObject, compileOptions);
Parameter
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 Funktionen oderWebAssembly.Memory
-Objekte. Es muss eine passende Eigenschaft für jeden deklarierten Import desModuls
vorhanden sein, andernfalls wird einWebAssembly.LinkError
ausgelöst. compileOptions
Optional-
Ein Objekt, das Kompilierungsoptionen enthält. Eigenschaften können umfassen:
builtins
Optional-
Ein Array von Zeichenfolgen, das die Verwendung von JavaScript Builtins im kompilierten Wasm-Modul ermöglicht. Die Zeichenfolgen 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 Zeichenfolge, die einen Namensraum für importierte globale Zeichenfolgenkonstanten angibt. Diese Eigenschaft muss angegeben werden, wenn Sie importierte globale Zeichenfolgenkonstanten im Wasm-Modul verwenden möchten.
Rückgabewert
Ein Promise
, das sich in ein WebAssembly.Instance
-Objekt auflöst.
Ausnahmen
- Wenn einer der Parameter nicht den korrekten Typ oder die richtige Struktur hat, wird ein
TypeError
ausgelöst. - Wenn der Vorgang fehlschlägt, wird das Promise mit einem
WebAssembly.CompileError
,WebAssembly.LinkError
oderWebAssembly.RuntimeError
abgelehnt, abhängig von der Ursache des Fehlers.
Beispiele
Hinweis:
In den meisten Fällen möchten Sie wahrscheinlich WebAssembly.instantiateStreaming()
verwenden, da dies effizienter ist als instantiate()
.
Erstes Überladungsbeispiel
Nach dem Abrufen von WebAssembly-Bytecode mit fetch, kompilieren und instanziieren wir das Modul mit 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());
Hinweis: Sie können dieses Beispiel auch unter index.html auf GitHub finden (sehen Sie es sich auch live an).
Zweites Überladungsbeispiel
Das folgende Beispiel (siehe unser index-compile.html-Demo auf GitHub und sehen Sie es sich live an 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 Importobjekt für das Modul zur Verwendung und richten 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 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();
});
};
Aktivierung von JavaScript-Builtins und globalen Zeichenfolgenimporten
Dieses Beispiel aktiviert JavaScript-String-Builtins und importierte globale Zeichenfolgenkonstanten bei der Kompilierung und Instanziierung des Wasm-Moduls mit instantiate()
, bevor es die exportierte main()
-Funktion ausführt (die "hello world!"
auf die Konsole schreibt). 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
Specification |
---|
WebAssembly JavaScript Interface # dom-webassembly-instantiate |
Browser-Kompatibilität
Report problems with this compatibility data on GitHubdesktop | mobile | server | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
instantiate() static method | ||||||||||||||
compileOptions parameter |
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- No support
- No support
Siehe auch
- WebAssembly Übersichtsseite
- WebAssembly-Konzepte
- Verwendung der WebAssembly-JavaScript-API