WebAssembly.Tag

Konstruktor

WebAssembly.Tag()

Erstellt eine neue Instanz eines WebAssembly.Tag-Objekts.

Instanzmethoden

Tag.prototype.type()

Gibt das Objekt zurck, das das Array der Datentypen fr den Tag definiert (wie im Konstruktor festgelegt).

Beschreibung

WebAssembly-Module knnen Ausnahmetypen mit der Moduldefinition tag definieren. Ausnahmen dieser Typen knnen dann mit der Anweisung throw ausgelst und mithilfe von try_table-Blcken mit catch-Klauseln abgefangen und behandelt werden.

Bei Bedarf knnen Sie einen Wasm-Ausnahmetyp im JavaScript-Host mit dem Konstruktor WebAssembly.Tag() definieren und ihn anschlieend zur Verwendung in das Wasm-Modul importieren.

Ein wesentlicher Vorteil der Definition von Wasm-Ausnahmetypen in JavaScript besteht darin, dass der Ausnahmetyp dort verfgbar sein muss, um eine Ausnahme in JavaScript zu behandeln. Wenn Sie ihn in JavaScript definieren, mssen Sie ihn nicht aus dem Wasm-Modul exportieren.

Beispielsweise knnen Sie zunchst einen Fehler-Tag-Typ wie folgt 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(/* ... */);

Im Wasm-Modul importieren Sie den Fehler-Tag und lsen an einer Stelle in Ihrem Code eine Ausnahme dieses Typs aus:

(tag $my_error (import "env" "my_error") (param i32))

(func $throw (param $value i32)

  ...

  (i32.const 42)     ;; error code payload
  (throw $my_error)  ;; throw exception type $my_error

  ...

)

(export "throw" (func $throw))

Zurck in JavaScript knnen Sie versuchen, die exportierte Funktion throw() in einer try...catch-Anweisung auszufhren. Wenn die Funktion eine Ausnahme auslst, ist der an den catch-Block weitergegebene Fehler eine Instanz eines 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 Ausnahmetyp hat, den wir zuvor definiert haben (myErrorTag). Anschlieend knnen Sie mit Exception.prototype.getArg() auf die Nutzdaten der Ausnahme zugreifen.

Beispiele

Ein funktionsfhiges Beispiel fr die Behandlung einer Wasm-Ausnahme in JavaScript finden Sie auf der Referenzseite zur Anweisung throw.

Grundlegende Verwendung

Dieser Codeausschnitt erstellt eine neue Tag-Instanz:

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

Der folgende Ausschnitt zeigt, wie wir sie bei der Instanziierung in ein Wasm-Modul importieren knnten:

const importObject = {
  extmod: {
    exttag: tagToImport,
  },
};

WebAssembly.instantiateStreaming(fetch("example.wasm"), importObject).then(
  (obj) => {
    // 
  },
);

Das WebAssembly-Modul knnte den Tag dann wie folgt importieren:

(module
  (import "extmod" "exttag" (tag $tagname (param i32 f32)))
)

Wenn mit dem Tag eine Ausnahme ausgelst wurde, die an JavaScript weitergegeben wurde, knnten wir den Tag verwenden, um die Werte der Ausnahme zu untersuchen.

Spezifikationen

Browser-Kompatibilitt

Siehe auch

• WebAssembly berblick
• WebAssembly-Konzepte
• Verwendung der WebAssembly JavaScript API
• tag-Definition
• exnref-Typ