WebAssembly.Tag

Konstruktor

WebAssembly.Tag()

Erstellt eine neue Instanz des WebAssembly.Tag-Objekts.

Instanzmethoden

Tag.prototype.type()

Gibt das Objekt zurck, das das Datentypen-Array fr den Tag definiert (wie in seinem Konstruktor festgelegt).

Beschreibung

WebAssembly-Module knnen Ausnahmetypen unter Verwendung der tag-Moduldefinition definieren. Ausnahmen dieser Typen knnen dann mit dem throw-Befehl geworfen und mit try_table-Blcken, die catch-Klauseln enthalten, abgefangen und behandelt werden.

Falls gewnscht, knnen 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 beim Behandeln einer Ausnahme in JavaScript verfgbar haben mssen. Wenn diese in JavaScript definiert ist, erspart es Ihnen, ihn aus dem Wasm-Modul exportieren zu mssen.

Zum Beispiel knnen Sie beginnen, indem Sie einen Fehler-Tag-Typ wie folgt konstruieren:

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

Sie knnen ihn dann in ein Wasm-Modul so importieren:

const env = {
  my_error: myErrorTag,
};

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

Innerhalb des Wasm-Moduls wrden Sie den Fehler-Tag importieren und an einer Stelle in Ihrem Code eine Ausnahme dieses Typs werfen:

(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 knnten Sie dann versuchen, die exportierte throw()-Funktion in einer try...catch-Anweisung auszufhren. Wenn die Funktion eine Ausnahme wirft, wird der in den catch-Block propagierte Fehler eine Instanz des 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 knnen prfen, ob es sich um denselben Ausnahmetyp handelt, den wir zuvor definiert haben (myErrorTag), indem Sie Exception.prototype.is() verwenden und dann auf die Nutzlast der Ausnahme mit Exception.prototype.getArg() zugreifen.

Beispiele

Fr ein funktionierendes Beispiel, wie eine Wasm-Ausnahme in JavaScript behandelt wird, siehe die throw-Befehlsreferenzseite.

Grundlegende Verwendung

Dieses Codebeispiel erstellt eine neue Tag-Instanz:

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

Das unten gezeigte Beispiel demonstriert, wie wir es whrend 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 unten gezeigt importieren:

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

Wenn das Tag verwendet wurde, um eine Ausnahme zu werfen, die nach JavaScript propagiert wurde, knnten wir das Tag verwenden, um seine Werte zu inspizieren.

Spezifikationen

Browser-Kompatibilitt

Siehe auch

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