WebAssembly.Tag

Konstruktor

WebAssembly.Tag()

Erstellt eine neue Instanz eines WebAssembly.Tag-Objekts.

Instanzmethoden

Tag.prototype.type()

Gibt das Objekt zurück, das das Datentypen-Array für das Tag definiert (wie im Konstruktor festgelegt).

Beschreibung

WebAssembly-Module können Ausnahmetypen mit der tag-Moduldefinition definieren. Ausnahmen dieser Typen können dann mit der throw-Anweisung ausgelöst und mit try_table-Blöcken, die catch-Klauseln enthalten, abgefangen und behandelt werden.

Falls gewünscht, können Sie einen Wasm-Ausnahmetyp im JavaScript-Host mit dem WebAssembly.Tag()-Konstruktor definieren, bevor Sie ihn in das Wasm-Modul importieren, um ihn dort zu verwenden.

Einer der Hauptvorteile der Definition von Wasm-Ausnahmetypen in JavaScript besteht darin, dass Sie den Ausnahmetyp benötigen, wenn Sie eine Ausnahme in JavaScript behandeln. Wenn er in JavaScript definiert ist, erspart Ihnen das den Export aus dem Wasm-Modul.

Zum Beispiel können Sie beginnen, indem Sie einen Fehlertag-Typ wie folgt konstruieren:

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

Sie können ihn dann in ein Wasm-Modul wie folgt importieren:

const env = {
  my_error: myErrorTag,
};

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

Innerhalb des Wasm-Moduls würden Sie den Fehlertag importieren und an irgendeiner Stelle in Ihrem Code eine Ausnahme dieses Typs auslösen:

(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))

Zurück in JavaScript könnten Sie dann versuchen, die exportierte throw()-Funktion in einer try...catch-Anweisung auszuführen. Wenn die Funktion eine Ausnahme auslöst, wird der zu dem catch-Block propagierte Fehler eine Instanz eines WebAssembly.Exception-Objekts sein.

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

Sie können prüfen, ob er den gleichen Ausnahmetyp hat, den wir zuvor definiert haben (myErrorTag), indem Sie Exception.prototype.is() verwenden, und dann auf die Nutzdaten der Ausnahme mit Exception.prototype.getArg() zugreifen.

Beispiele

Für ein funktionierendes Beispiel zum Umgang mit einer Wasm-Ausnahme in JavaScript siehe die Referenzseite zur throw-Anweisung.

Grundlegende Verwendung

Dieses Codebeispiel erstellt eine neue Tag-Instanz:

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

Das untenstehende Beispiel zeigt, wie wir es während der Instanziierung in ein Wasm-Modul importieren könnten:

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

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

Das WebAssembly-Modul könnte das Tag dann wie unten gezeigt importieren:

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

Wenn das Tag verwendet wurde, um eine Ausnahme auszulösen, die nach JavaScript propagiert wurde, könnten wir das Tag verwenden, um seine Werte zu inspizieren.

Spezifikationen

Browser-Kompatibilität

Siehe auch

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