trap.h File Reference

#include <wasm.h>

Go to the source code of this file.

Typedefs
typedef uint8_t	wasmtime_trap_code_t
	Code of an instruction trap. More...

Enumerations
enum	wasmtime_trap_code_enum {   WASMTIME_TRAP_CODE_STACK_OVERFLOW , WASMTIME_TRAP_CODE_MEMORY_OUT_OF_BOUNDS , WASMTIME_TRAP_CODE_HEAP_MISALIGNED , WASMTIME_TRAP_CODE_TABLE_OUT_OF_BOUNDS ,   WASMTIME_TRAP_CODE_INDIRECT_CALL_TO_NULL , WASMTIME_TRAP_CODE_BAD_SIGNATURE , WASMTIME_TRAP_CODE_INTEGER_OVERFLOW , WASMTIME_TRAP_CODE_INTEGER_DIVISION_BY_ZERO ,   WASMTIME_TRAP_CODE_BAD_CONVERSION_TO_INTEGER , WASMTIME_TRAP_CODE_UNREACHABLE_CODE_REACHED , WASMTIME_TRAP_CODE_INTERRUPT , WASMTIME_TRAP_CODE_ALWAYS_TRAP_ADAPTER ,   WASMTIME_TRAP_CODE_OUT_OF_FUEL , WASMTIME_TRAP_CODE_ATOMIC_WAIT_NON_SHARED_MEMORY , WASMTIME_TRAP_CODE_NULL_REFERENCE , WASMTIME_TRAP_CODE_ARRAY_OUT_OF_BOUNDS ,   WASMTIME_TRAP_CODE_ALLOCATION_TOO_LARGE , WASMTIME_TRAP_CODE_CAST_FAILURE , WASMTIME_TRAP_CODE_CANNOT_ENTER_COMPONENT , WASMTIME_TRAP_CODE_NO_ASYNC_RESULT ,   WASMTIME_TRAP_CODE_DISABLED_OPCODE }
	Trap codes for instruction traps. More...

Functions
WASM_API_EXTERN wasm_trap_t *	wasmtime_trap_new (const char *msg, size_t msg_len)
	Creates a new trap with the given message. More...
WASM_API_EXTERN wasm_trap_t *	wasmtime_trap_new_code (wasmtime_trap_code_t code)
	Creates a new trap from the given trap code. More...
WASM_API_EXTERN bool	wasmtime_trap_code (const wasm_trap_t *, wasmtime_trap_code_t *code)
	Attempts to extract the trap code from this trap. More...
WASM_API_EXTERN const wasm_name_t *	wasmtime_frame_func_name (const wasm_frame_t *)
	Returns a human-readable name for this frame's function. More...
WASM_API_EXTERN const wasm_name_t *	wasmtime_frame_module_name (const wasm_frame_t *)
	Returns a human-readable name for this frame's module. More...

Detailed Description

Wasmtime APIs for interacting with traps and extensions to wasm_trap_t.

Typedef Documentation

wasmtime_trap_code_t

typedef uint8_t wasmtime_trap_code_t

Code of an instruction trap.

See wasmtime_trap_code_enum for possible values.

Enumeration Type Documentation

wasmtime_trap_code_enum

enum wasmtime_trap_code_enum

Trap codes for instruction traps.

Enumerator
WASMTIME_TRAP_CODE_STACK_OVERFLOW	The current stack space was exhausted.
WASMTIME_TRAP_CODE_MEMORY_OUT_OF_BOUNDS	An out-of-bounds memory access.
WASMTIME_TRAP_CODE_HEAP_MISALIGNED	A wasm atomic operation was presented with a not-naturally-aligned linear-memory address.
WASMTIME_TRAP_CODE_TABLE_OUT_OF_BOUNDS	An out-of-bounds access to a table.
WASMTIME_TRAP_CODE_INDIRECT_CALL_TO_NULL	Indirect call to a null table entry.
WASMTIME_TRAP_CODE_BAD_SIGNATURE	Signature mismatch on indirect call.
WASMTIME_TRAP_CODE_INTEGER_OVERFLOW	An integer arithmetic operation caused an overflow.
WASMTIME_TRAP_CODE_INTEGER_DIVISION_BY_ZERO	An integer division by zero.
WASMTIME_TRAP_CODE_BAD_CONVERSION_TO_INTEGER	Failed float-to-int conversion.
WASMTIME_TRAP_CODE_UNREACHABLE_CODE_REACHED	Code that was supposed to have been unreachable was reached.
WASMTIME_TRAP_CODE_INTERRUPT	Execution has potentially run too long and may be interrupted.
WASMTIME_TRAP_CODE_ALWAYS_TRAP_ADAPTER	When the component-model feature is enabled this trap represents a function that was canon lift'd, then canon lower'd, then called. This combination of creation of a function in the component model generates a function that always traps and, when called, produces this flavor of trap.
WASMTIME_TRAP_CODE_OUT_OF_FUEL	Execution has run out of the configured fuel amount.
WASMTIME_TRAP_CODE_ATOMIC_WAIT_NON_SHARED_MEMORY	Used to indicate that a trap was raised by atomic wait operations on non shared memory.
WASMTIME_TRAP_CODE_NULL_REFERENCE	Call to a null reference.
WASMTIME_TRAP_CODE_ARRAY_OUT_OF_BOUNDS	Attempt to access beyond the bounds of an array.
WASMTIME_TRAP_CODE_ALLOCATION_TOO_LARGE	Attempted an allocation that was too large to succeed.
WASMTIME_TRAP_CODE_CAST_FAILURE	Attempted to cast a reference to a type that it is not an instance of.
WASMTIME_TRAP_CODE_CANNOT_ENTER_COMPONENT	When the component-model feature is enabled this trap represents a scenario where one component tried to call another component but it would have violated the reentrance rules of the component model, triggering a trap instead.
WASMTIME_TRAP_CODE_NO_ASYNC_RESULT	Async-lifted export failed to produce a result by calling task.return before returning STATUS_DONE and/or after all host tasks completed.
WASMTIME_TRAP_CODE_DISABLED_OPCODE	A Pulley opcode was executed at runtime when the opcode was disabled at compile time.

Function Documentation

wasmtime_frame_func_name()

WASM_API_EXTERN const wasm_name_t * wasmtime_frame_func_name

(

const wasm_frame_t *

)

Returns a human-readable name for this frame's function.

This function will attempt to load a human-readable name for function this frame points to. This function may return NULL.

The lifetime of the returned name is the same as the wasm_frame_t itself.

wasmtime_frame_module_name()

WASM_API_EXTERN const wasm_name_t * wasmtime_frame_module_name

(

const wasm_frame_t *

)

Returns a human-readable name for this frame's module.

This function will attempt to load a human-readable name for module this frame points to. This function may return NULL.

The lifetime of the returned name is the same as the wasm_frame_t itself.

wasmtime_trap_code()

WASM_API_EXTERN bool wasmtime_trap_code	(	const wasm_trap_t *	,
		wasmtime_trap_code_t *	code
	)

Attempts to extract the trap code from this trap.

Returns true if the trap is an instruction trap triggered while executing Wasm. If true is returned then the trap code is returned through the code pointer. If false is returned then this is not an instruction trap – traps can also be created using wasm_trap_new, or occur with WASI modules exiting with a certain exit code.

wasmtime_trap_new()

WASM_API_EXTERN wasm_trap_t * wasmtime_trap_new	(	const char *	msg,
		size_t	msg_len
	)

Creates a new trap with the given message.

Parameters

msg	the message to associate with this trap
msg_len	the byte length of msg

The wasm_trap_t returned is owned by the caller.

wasmtime_trap_new_code()

WASM_API_EXTERN wasm_trap_t * wasmtime_trap_new_code

(

wasmtime_trap_code_t

code

)

Creates a new trap from the given trap code.

Parameters

code	the trap code to associate with this trap

The wasm_trap_t returned is owned by the caller.