#include <wasmtime/conf.h>
#include <wasmtime/types/exnref.h>
#include <wasmtime/val.h>

Functions
WASM_API_EXTERN wasmtime_error_t *	wasmtime_exnref_new (wasmtime_context_t store, const wasmtime_tag_t tag, const wasmtime_val_t fields, size_t nfields, wasmtime_exnref_t exn_ret)
	Creates a new exception object. More...

WASM_API_EXTERN void	wasmtime_exnref_clone (const wasmtime_exnref_t ref, wasmtime_exnref_t out)
	Creates a new reference pointing to the same exception that `ref` points to. More...

WASM_API_EXTERN void	wasmtime_exnref_unroot (wasmtime_exnref_t *ref)
	Unroots the `ref` provided, enabling future garbage collection. More...

WASM_API_EXTERN void	wasmtime_exnref_from_raw (wasmtime_context_t context, uint32_t raw, wasmtime_exnref_t out)
	Converts a raw `exnref` value coming from wasmtime_val_raw_t into a wasmtime_exnref_t. More...

WASM_API_EXTERN uint32_t	wasmtime_exnref_to_raw (wasmtime_context_t context, const wasmtime_exnref_t ref)
	Converts a wasmtime_exnref_t to a raw value suitable for storing into a wasmtime_val_raw_t. More...

WASM_API_EXTERN wasmtime_error_t *	wasmtime_exnref_tag (wasmtime_context_t store, const wasmtime_exnref_t exn, wasmtime_tag_t *tag_ret)
	Returns the tag associated with this exception. More...

WASM_API_EXTERN size_t	wasmtime_exnref_field_count (wasmtime_context_t store, const wasmtime_exnref_t exn)
	Returns the number of fields in this exception. More...

WASM_API_EXTERN wasmtime_error_t *	wasmtime_exnref_field (wasmtime_context_t store, const wasmtime_exnref_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, const wasmtime_exnref_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_exnref_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...

WASM_API_EXTERN wasmtime_exn_type_t *	wasmtime_exnref_type (wasmtime_context_t context, const wasmtime_exnref_t exnref)
	Returns the type of the specified `exnref`. More...

Detailed Description

APIs for interacting with WebAssembly exnref type in Wasmtime.

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,
		const wasmtime_exnref_t *	exn
	)

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

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

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_exnref_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_exnref_unroot.

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

WASM_API_EXTERN void wasmtime_exnref_clone	(	const wasmtime_exnref_t *	ref,
		wasmtime_exnref_t *	out
	)

Creates a new reference pointing to the same exception that ref points to.

The returned reference is stored in out.

◆ wasmtime_exnref_field()

WASM_API_EXTERN wasmtime_error_t * wasmtime_exnref_field	(	wasmtime_context_t *	store,
		const wasmtime_exnref_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_exnref_field_count()

WASM_API_EXTERN size_t wasmtime_exnref_field_count	(	wasmtime_context_t *	store,
		const wasmtime_exnref_t *	exn
	)

Returns the number of fields in this exception.

Parameters

store	the store context
exn	the exception to query

◆ wasmtime_exnref_from_raw()

WASM_API_EXTERN void wasmtime_exnref_from_raw	(	wasmtime_context_t *	context,
		uint32_t	raw,
		wasmtime_exnref_t *	out
	)

Converts a raw exnref value coming from wasmtime_val_raw_t into a wasmtime_exnref_t.

The out reference is filled in with the non-raw version of this exnref. It must eventually be unrooted with wasmtime_exnref_unroot.

◆ wasmtime_exnref_new()

WASM_API_EXTERN wasmtime_error_t * wasmtime_exnref_new	(	wasmtime_context_t *	store,
		const wasmtime_tag_t *	tag,
		const wasmtime_val_t *	fields,
		size_t	nfields,
		wasmtime_exnref_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_exnref_unroot.

Returns: NULL on success, or an error on failure.

◆ wasmtime_exnref_tag()

WASM_API_EXTERN wasmtime_error_t * wasmtime_exnref_tag	(	wasmtime_context_t *	store,
		const wasmtime_exnref_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.

◆ wasmtime_exnref_to_raw()

WASM_API_EXTERN uint32_t wasmtime_exnref_to_raw	(	wasmtime_context_t *	context,
		const wasmtime_exnref_t *	ref
	)

Converts a wasmtime_exnref_t to a raw value suitable for storing into a wasmtime_val_raw_t.

Note that the returned underlying value is not tracked by Wasmtime's garbage collector until it enters WebAssembly. This means that a GC may release the context's reference to the raw value, making the raw value invalid within the context of the store. Do not perform a GC between calling this function and passing it to WebAssembly.

◆ wasmtime_exnref_type()

WASM_API_EXTERN wasmtime_exn_type_t * wasmtime_exnref_type	(	wasmtime_context_t *	context,
		const wasmtime_exnref_t *	exnref
	)

Returns the type of the specified exnref.

Returns: If exnref is NULL or represents ref.null exn, then NULL is returned. Otherwise the type of this value is returned. Callers must delete the returned value.

◆ wasmtime_exnref_unroot()

WASM_API_EXTERN void wasmtime_exnref_unroot ( wasmtime_exnref_t * ref )

Unroots the ref provided, enabling future garbage collection.

After this call, ref is left in an undefined state and should not be used.

Functions

Detailed Description

Function Documentation

◆ wasmtime_context_has_exception()

◆ wasmtime_context_set_exception()

◆ wasmtime_context_take_exception()

◆ wasmtime_exnref_clone()

◆ wasmtime_exnref_field()

◆ wasmtime_exnref_field_count()

◆ wasmtime_exnref_from_raw()

◆ wasmtime_exnref_new()

◆ wasmtime_exnref_tag()

◆ wasmtime_exnref_to_raw()

◆ wasmtime_exnref_type()

◆ wasmtime_exnref_unroot()