WebAssembly.Tag

Constructor

WebAssembly.Tag()

Creates a new WebAssembly.Tag object instance.

Instance methods

Tag.prototype.type()

Returns the object defining the data-types array for the tag (as set in its constructor).

Description

WebAssembly modules can define exception types using the tag module definition. Exceptions of those types can then be thrown using the throw instruction, and caught and handled using try_table blocks containing catch clauses.

If wished, you can define a Wasm exception type in the JavaScript host using the WebAssembly.Tag() constructor, before importing it into the Wasm module to use there.

One of the main advantages of defining Wasm exception types in JavaScript is that you need the exception type available when handling an exception in JavaScript. Having it defined in JavaScript saves you having to export it from the Wasm module.

So for example, you can start by constructing an error tag type like this:

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

You can then import it into a Wasm module like this:

const env = {
  my_error: myErrorTag,
};

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

Inside the Wasm module, you'd import the error tag and throw an exception of that type somewhere in your code:

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

Back in the JavaScript, you could then try running the exported throw() function in a try...catch statement. If the function throws, the error propagated to the catch block will be a WebAssembly.Exception object instance.

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

You can check whether it has the same exception type we defined earlier (myErrorTag) using Exception.prototype.is(), and then access the exception's payload using Exception.prototype.getArg()).

Examples

For a working example of handling a Wasm exception in JavaScript, see the throw instruction reference page.

Basic usage

This code snippet creates a new Tag instance:

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

The snippet below shows how we might import it into a Wasm module during instantiation:

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

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

The WebAssembly module might then import the tag as shown below:

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

If the tag was used to throw an exception that propagated to JavaScript, we could use the tag to inspect its values.

Specifications

Browser compatibility

See also

• WebAssembly overview
• WebAssembly concepts
• Using the WebAssembly JavaScript API
• tag definition
• exnref type