WebAssembly.Exception.prototype.getArg()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since May 2022.
Die getArg()
Prototyp-Methode des Exception
Objekts kann verwendet werden, um den Wert eines angegebenen Elements in den Datenargumenten der Ausnahme abzurufen.
Die Methode übergibt ein WebAssembly.Tag
und wird nur erfolgreich sein, wenn die geworfene Exception
mit demselben Tag erstellt wurde, andernfalls wird ein TypeError
ausgelöst. Dies stellt sicher, dass die Ausnahme nur gelesen werden kann, wenn der aufrufende Code Zugriff auf das Tag hat. Tags, die weder in den noch aus dem WebAssembly-Code importiert oder exportiert werden, sind intern, und ihre zugehörigen WebAssembly.Exception
können mit dieser Methode nicht abgefragt werden!
Hinweis: Es reicht nicht aus, dass das Tag eine identische Sequenz von Datentypen hat – es muss die gleiche Identität (das gleiche Tag) sein, mit der die Ausnahme erstellt wurde.
Syntax
getArg(exceptionTag, index)
Parameter
exceptionTag
-
Ein
WebAssembly.Tag
, das mit dem dieser Ausnahme zugeordneten Tag übereinstimmen muss. index
-
Der Index des Wertes in den Datenargumenten, der zurückgegeben werden soll, 0-basiert.
Rückgabewert
Der Wert des Arguments bei index
.
Ausnahmen
TypeError
-
Die Tags stimmen nicht überein; die Ausnahme wurde nicht mit dem zur Methode übergebenen Tag erstellt.
RangeError
-
Der Wert des
index
Parameters ist größer als oder gleich der Anzahl der Felder in den Daten.
Beispiele
Um die Werte einer Ausnahme abzurufen, muss das Tag dem aufrufenden Code "bekannt" sein; es kann entweder in den Code importiert oder aus diesem exportiert werden.
Ausnahme-Wert von importiertem Tag abrufen
Betrachten Sie den folgenden WebAssembly-Code, der angenommen wird, in einer Datei "example.wasm" kompiliert zu sein. Dieser importiert ein Tag, das intern als $tagname
bezeichnet wird, und exportiert eine Methode run
, die von externem Code aufgerufen werden kann, um eine Ausnahme mit dem Tag zu werfen.
(module
;; import tag that will be referred to here as $tagname
(import "extmod" "exttag" (tag $tagname (param i32)))
;; $throwException function throws i32 param as a $tagname exception
(func $throwException (param i32)
local.get 0
throw $tagname
)
;; Exported function "run" that calls $throwException
(func (export "run")
i32.const 1
call $throwException
)
)
Der untenstehende Code ruft WebAssembly.instantiateStreaming
auf, um die Datei "example.wasm" zu importieren. Dabei wird ein "Import-Objekt" (importObject
) übergeben, das ein neues WebAssembly.Tag
namens tagToImport
enthält. Das Import-Objekt definiert ein Objekt mit Eigenschaften, die mit der import
Anweisung im WebAssembly-Code übereinstimmen.
Sobald die Datei instanziiert ist, ruft der Code die exportierte WebAssembly-run()
Methode auf, die sofort eine Ausnahme werfen wird.
const tagToImport = new WebAssembly.Tag({ parameters: ["i32"] });
// Note: the import object properties match the import statement in WebAssembly code!
const importObject = {
extmod: {
exttag: tagToImport,
},
};
WebAssembly.instantiateStreaming(fetch("example.wasm"), importObject)
.then((obj) => {
console.log(obj.instance.exports.run());
})
.catch((e) => {
console.error(e);
console.log(`getArg 0 : ${e.getArg(tagToImport, 0)}`);
});
/* Log output
example.js:40 WebAssembly.Exception: wasm exception
example.js:41 getArg 0 : 1
*/
Der Code fängt die Ausnahme ab und verwendet getArg()
, um den Wert am ersten Index auszugeben. In diesem Fall ist es einfach "1".
Ausnahme-Wert von einem exportierten Tag abrufen
Der Prozess zur Verwendung eines exportierten Tags ist dem zuvor gezeigten sehr ähnlich. Hier ist dasselbe WebAssembly-Modul, wobei einfach der Import durch einen Export ersetzt wird.
(module
;; Export tag giving it external name: "exptag"
(tag $tagname (export "exptag") (param i32))
(func $throwException (param i32)
local.get 0
throw $tagname
)
(func (export "run")
i32.const 1
call $throwException
)
)
Das JavaScript ist ebenfalls ähnlich. In diesem Fall haben wir keine Importe, aber stattdessen erhalten wir das exportierte Tag und verwenden dieses, um das Argument zu erhalten. Um es etwas "sicherer" zu machen, testen wir hier auch, ob wir das richtige Tag haben, indem wir die is()
Methode verwenden.
let tagExportedFromWasm;
WebAssembly.instantiateStreaming(fetch("example.wasm"))
.then((obj) => {
// Import the tag using its name from the WebAssembly module
tagExportedFromWasm = obj.instance.exports.exptag;
console.log(obj.instance.exports.run());
})
.catch((e) => {
console.error(e);
// If the tag is correct, get the value
if (e.is(tagExportedFromWasm)) {
console.log(`getArg 0 : ${e.getArg(tagExportedFromWasm, 0)}`);
}
});
Spezifikationen
Specification |
---|
WebAssembly JavaScript Interface: Exception Handling # dom-exception-getarg |
Browser-Kompatibilität
BCD tables only load in the browser
Siehe auch
- WebAssembly Übersichtsseite
- WebAssembly Konzepte
- Verwendung der WebAssembly JavaScript-API