WebAssembly.Exception

Konstruktor

WebAssembly.Exception()

Erstellt eine neue Instanz des WebAssembly.Exception-Objekts.

Instanzmethoden

Exception.prototype.is()

Prft, ob die Ausnahme mit einem bestimmten Tag bereinstimmt.

Exception.prototype.getArg()

Gibt die Datenfelder einer Ausnahme zurck, die mit einem angegebenen Tag bereinstimmt.

Instanzeigenschaften

Exception.prototype.stack

Gibt den Stack-Trace der Ausnahme zurck.

Beschreibung

Wenn Wasm-Ausnahmen im JavaScript-Host behandelt werden, haben abgefangene Ausnahmen den Objekttyp WebAssembly.Exception.

Sie knnen beispielsweise zunchst mit dem Konstruktor WebAssembly.Tag() einen Fehler-Tag-Typ erstellen:

const myErrorTag = new WebAssembly.Tag({ parameters: ["i32"] });

Anschlieend knnen Sie ihn wie folgt in ein Wasm-Modul importieren:

const env = {
  my_error: myErrorTag,
};

WebAssembly.instantiateStreaming(fetch("module.wasm"), { env }).then(/* ... */);

Danach knnen Sie versuchen, eine exportierte Wasm-Funktion innerhalb einer try...catch-Anweisung auszufhren. Wenn die Funktion eine Ausnahme auslst, ist der an den catch-Block weitergegebene Fehler eine Instanz des WebAssembly.Exception-Objekts.

WebAssembly.instantiateStreaming(fetch("module.wasm"), { env }).then(
  (result) => {
    try {
      // Cause function to throw
      result.instance.exports.throw(-1);
    } catch (e) {
      if (e instanceof WebAssembly.Exception && e.is(myErrorTag)) {
        const errorCode = e.getArg(myErrorTag, 0); // 0 = first payload value
        console.log("Error code:", errorCode); // 42
      } else {
        throw e; // throw other errors
      }
    }
  },
);

Mit Exception.prototype.is() knnen Sie prfen, ob die Ausnahme denselben Typ wie das zuvor definierte Tag (myErrorTag) hat. Anschlieend knnen Sie mit Exception.prototype.getArg() auf die Nutzdaten der Ausnahme zugreifen.

JavaScript und anderer Client-Code knnen nur dann auf WebAssembly-Ausnahmewerte zugreifen und umgekehrt , wenn das zugehrige Tag gemeinsam verwendet wird. Es reicht nicht aus, ein anderes Tag zu verwenden, das zufllig dieselben Datentypen definiert. Ohne das passende Tag knnen Ausnahmen abgefangen und erneut ausgelst, aber nicht untersucht werden.

Damit das Auslsen von Ausnahmen schneller ist, enthalten aus WebAssembly ausgelste Ausnahmen in der Regel keinen Stack-Trace. WebAssembly-Code, der einen Stack-Trace bereitstellen muss, muss eine JavaScript-Funktion aufrufen, um die Ausnahme zu erstellen, und dabei den Parameter options.traceStack=true an den Konstruktor bergeben. Der Konstruktor kann dann eine Ausnahme zurckgeben, deren Eigenschaft stack einen Stack-Trace enthlt.

Beispiele

Dieses Beispiel zeigt, wie Sie ein Tag definieren und in ein Modul importieren. Anschlieend wird damit eine Ausnahme ausgelst, die in JavaScript abgefangen wird.

Betrachten Sie den folgenden WebAssembly-Code, der in eine Datei namens example.wasm kompiliert wurde.

• Das Modul importiert ein Tag, das intern als $tagname bezeichnet wird und einen einzelnen i32-Parameter hat. Das Tag wird unter dem Modulnamen extmod und dem Tagnamen exttag bergeben.
• Die Funktion $throwException lst mit der Anweisung throw eine Ausnahme aus und verwendet dabei $tagname und das Parameterargument.
• Das Modul exportiert die Funktion run(), die eine Ausnahme mit dem Wert 42 auslst.

(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 $errorValueArg i32)
    local.get $errorValueArg
    throw $tagname
  )

  ;; Exported function "run" that calls $throwException
  (func (export "run")
    i32.const 42
    call $throwException
  )
)

Der folgende Code ruft WebAssembly.instantiateStreaming auf, um die Datei example.wasm zu importieren. Dabei bergibt er ein Importobjekt (importObject), das ein neues WebAssembly.Tag namens tagToImport enthlt. Das Importobjekt enthlt ein Objekt mit Eigenschaften, die zur import-Anweisung im WebAssembly-Code passen.

Nachdem die Datei instanziiert wurde, ruft der Code die exportierte WebAssembly-Methode run() auf, die sofort eine Ausnahme auslst.

const tagToImport = new WebAssembly.Tag({ parameters: ["i32"] });

// Note: import object properties match the WebAssembly import statement!
const importObject = {
  extmod: {
    exttag: tagToImport,
  },
};

WebAssembly.instantiateStreaming(fetch("example.wasm"), importObject)
  .then((obj) => {
    console.log(obj.instance.exports.run());
  })
  .catch((e) => {
    console.error(e);
    // Check we have the right tag for the exception
    // If so, use getArg() to inspect it
    if (e.is(tagToImport)) {
      console.log(`getArg 0 : ${e.getArg(tagToImport, 0)}`);
    }
  });

/* Log output
example.js:40 WebAssembly.Exception: wasm exception
example.js:41 getArg 0 : 42
*/

Die Ausnahme wird in JavaScript im catch-Block abgefangen. Sie hat den Typ WebAssembly.Exception. Ohne das passende Tag knnten wir jedoch kaum etwas Weiteres damit anfangen.

Da uns das Tag zur Verfgung steht, prfen wir mit Exception.prototype.is(), ob es das richtige ist. Da dies der Fall ist, lesen wir mit Exception.prototype.getArg() den Wert 42 aus.

Spezifikationen

Browser-Kompatibilitt

Siehe auch

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