WebAssembly.Tag

Konstruktor

WebAssembly.Tag()

Erstellt eine neue Instanz des WebAssembly.Tag Objekts.

Instanzmethoden

Tag.prototype.type()

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

Beschreibung

WebAssembly-Module können Ausnahmetypen mithilfe 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.

Wenn 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 ist, dass der Ausnahmetyp verfügbar sein muss, wenn eine Ausnahme in JavaScript behandelt wird. Wenn er in JavaScript definiert ist, ersparen Sie sich den Export aus dem Wasm-Modul.

So können Sie beispielsweise beginnen, einen Fehler-Tag-Typ wie folgt zu erstellen:

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(/* ... */);

Im Wasm-Modul würden Sie den Fehler-Tag importieren und an irgendeiner Stelle im 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 Fehler, der in den catch Block propagiert wird, 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 können überprüfen, ob es sich um den gleichen Ausnahmetyp handelt, den wir zuvor definiert haben (myErrorTag), mithilfe von Exception.prototype.is(), und dann die Nutzlast der Ausnahme mit Exception.prototype.getArg() abrufen.

Beispiele

Für ein funktionierendes Beispiel zur Behandlung einer Wasm-Ausnahme in JavaScript, siehe die throw Anweisungsreferenzseite.

Grundlegende Verwendung

Dieser Codeausschnitt erstellt eine neue Tag Instanz:

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

Der untenstehende Ausschnitt zeigt, wie wir ihn 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 dann den Tag wie unten gezeigt importieren:

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

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

Spezifikationen

Browser-Kompatibilität

Siehe auch

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