exn.h File Reference

Wasmtime APIs for WebAssembly exception objects. More...

#include <wasmtime/conf.h>
#include <wasm.h>
#include <wasmtime/error.h>
#include <wasmtime/store.h>
#include <wasmtime/tag.h>
#include <wasmtime/val.h>

Go to the source code of this file.

Typedefs
typedef struct wasmtime_exn	wasmtime_exn_t
	An opaque type representing a WebAssembly exception object. More...

Functions
WASM_API_EXTERN void	wasmtime_exn_delete (wasmtime_exn_t *exn)
	Deletes a wasmtime_exn_t.
WASM_API_EXTERN wasmtime_error_t *	wasmtime_exn_new (wasmtime_context_t *store, const wasmtime_tag_t *tag, const wasmtime_val_t *fields, size_t nfields, wasmtime_exn_t **exn_ret)
	Creates a new exception object. More...
WASM_API_EXTERN wasmtime_error_t *	wasmtime_exn_tag (wasmtime_context_t *store, const wasmtime_exn_t *exn, wasmtime_tag_t *tag_ret)
	Returns the tag associated with this exception. More...
WASM_API_EXTERN size_t	wasmtime_exn_field_count (wasmtime_context_t *store, const wasmtime_exn_t *exn)
	Returns the number of fields in this exception. More...
WASM_API_EXTERN wasmtime_error_t *	wasmtime_exn_field (wasmtime_context_t *store, const wasmtime_exn_t *exn, size_t index, wasmtime_val_t *val_ret)
	Reads a field value from this exception by index. More...
WASM_API_EXTERN wasm_trap_t *	wasmtime_context_set_exception (wasmtime_context_t *store, wasmtime_exn_t *exn)
	Sets the pending exception on the store and returns a trap. More...
WASM_API_EXTERN bool	wasmtime_context_take_exception (wasmtime_context_t *store, wasmtime_exn_t **exn_ret)
	Takes the pending exception from the store, if any. More...
WASM_API_EXTERN bool	wasmtime_context_has_exception (wasmtime_context_t *store)
	Tests whether there is a pending exception on the store. More...

Detailed Description

Wasmtime APIs for WebAssembly exception objects.

Exception objects carry a tag and a set of field values. They are allocated on the GC heap within a store.

Throwing from host functions

To throw an exception from a host function implemented via the C API:

1. Create an exception object with wasmtime_exn_new.
2. Set it as the pending exception with wasmtime_context_set_exception.
3. Return a trap from the host callback (e.g. via wasmtime_trap_new).

The runtime will propagate the exception through WebAssembly try_table/catch blocks.

Catching exceptions from Wasm

When a call to a WebAssembly function (e.g. via wasmtime_func_call) returns a trap, check for a pending exception:

1. Call wasmtime_context_has_exception or wasmtime_context_take_exception.
2. If present, examine the exception's tag and fields.

Typedef Documentation

wasmtime_exn_t

wasmtime_exn_t

An opaque type representing a WebAssembly exception object.

Exception objects are allocated on the GC heap and referenced through this handle. The handle is owned by the caller and must be freed with wasmtime_exn_delete.

Function Documentation

wasmtime_context_has_exception()

WASM_API_EXTERN bool wasmtime_context_has_exception

(

wasmtime_context_t *

store

)

Tests whether there is a pending exception on the store.

Parameters

store

the store context

Returns

true if a pending exception is set, false otherwise.

wasmtime_context_set_exception()

WASM_API_EXTERN wasm_trap_t * wasmtime_context_set_exception	(	wasmtime_context_t *	store,
		wasmtime_exn_t *	exn
	)

Sets the pending exception on the store and returns a trap.

This transfers ownership of exn to the store. After this call, the caller must not use or free exn.

Returns a wasm_trap_t that the host callback MUST return to signal to the Wasm runtime that an exception was thrown. The caller owns the returned trap.

Parameters

store	the store context
exn	the exception to throw (ownership transferred)

Returns

a trap to return from the host callback (caller-owned)

wasmtime_context_take_exception()

WASM_API_EXTERN bool wasmtime_context_take_exception	(	wasmtime_context_t *	store,
		wasmtime_exn_t **	exn_ret
	)

Takes the pending exception from the store, if any.

If there is a pending exception, removes it from the store and returns it. The caller owns the returned pointer and must free it with wasmtime_exn_delete.

Parameters

store	the store context
exn_ret	on success, set to the exception (caller-owned)

Returns

true if there was a pending exception, false otherwise.

wasmtime_exn_field()

WASM_API_EXTERN wasmtime_error_t * wasmtime_exn_field	(	wasmtime_context_t *	store,
		const wasmtime_exn_t *	exn,
		size_t	index,
		wasmtime_val_t *	val_ret
	)

Reads a field value from this exception by index.

Parameters

store	the store context
exn	the exception to query
index	the field index (0-based)
val_ret	on success, filled with the field value (caller-owned on return).

Returns

NULL on success, or an error if the index is out of bounds.

wasmtime_exn_field_count()

WASM_API_EXTERN size_t wasmtime_exn_field_count	(	wasmtime_context_t *	store,
		const wasmtime_exn_t *	exn
	)

Returns the number of fields in this exception.

Parameters

store	the store context
exn	the exception to query

wasmtime_exn_new()

WASM_API_EXTERN wasmtime_error_t * wasmtime_exn_new	(	wasmtime_context_t *	store,
		const wasmtime_tag_t *	tag,
		const wasmtime_val_t *	fields,
		size_t	nfields,
		wasmtime_exn_t **	exn_ret
	)

Creates a new exception object.

Parameters

store	the store context
tag	the tag to associate with this exception
fields	pointer to an array of field values matching the tag's payload signature
nfields	the number of elements in fields
exn_ret	on success, set to the newly allocated exception. The caller owns the returned pointer and must free it with wasmtime_exn_delete.

Returns

NULL on success, or an error on failure.

wasmtime_exn_tag()

WASM_API_EXTERN wasmtime_error_t * wasmtime_exn_tag	(	wasmtime_context_t *	store,
		const wasmtime_exn_t *	exn,
		wasmtime_tag_t *	tag_ret
	)

Returns the tag associated with this exception.

Parameters

store	the store context
exn	the exception to query
tag_ret	on success, filled with the exception's tag

Returns

NULL on success, or an error on failure.