Enum Trap

#[non_exhaustive]
pub enum Trap {
    StackOverflow,
    MemoryOutOfBounds,
    HeapMisaligned,
    TableOutOfBounds,
    IndirectCallToNull,
    BadSignature,
    IntegerOverflow,
    IntegerDivisionByZero,
    BadConversionToInteger,
    UnreachableCodeReached,
    Interrupt,
    AlwaysTrapAdapter,
    OutOfFuel,
    AtomicWaitNonSharedMemory,
    NullReference,
    ArrayOutOfBounds,
    AllocationTooLarge,
    CastFailure,
    CannotEnterComponent,
}

Representation of a WebAssembly trap and what caused it to occur.

WebAssembly traps happen explicitly for instructions such as unreachable but can also happen as side effects of other instructions such as i32.load loading an out-of-bounds address. Traps halt the execution of WebAssembly and cause an error to be returned to the host. This enumeration is a list of all possible traps that can happen in wasm, in addition to some Wasmtime-specific trap codes listed here as well.

Errors in Wasmtime

Error-handling in Wasmtime is primarily done through the anyhow crate where most results are a Result<T> which is an alias for Result<T, anyhow::Error>. Errors in Wasmtime are represented with anyhow::Error which acts as a container for any type of error in addition to optional context for this error. The “base” error or anyhow::Error::root_cause is a Trap whenever WebAssembly hits a trap, or otherwise it’s whatever the host created the error with when returning an error for a host call.

Any error which happens while WebAssembly is executing will also, by default, capture a backtrace of the wasm frames while executing. This backtrace is represented with a WasmBacktrace instance and is attached to the anyhow::Error return value as a context. Inspecting a WasmBacktrace can be done with the downcast_ref function. For information on this see the WasmBacktrace documentation.

Examples

let engine = Engine::default();
let module = Module::new(
    &engine,
    r#"
        (module
            (func (export "trap")
                unreachable)
            (func $overflow (export "overflow")
                call $overflow)
        )
    "#,
)?;
let mut store = Store::new(&engine, ());
let instance = Instance::new(&mut store, &module, &[])?;

let trap = instance.get_typed_func::<(), ()>(&mut store, "trap")?;
let error = trap.call(&mut store, ()).unwrap_err();
assert_eq!(*error.downcast_ref::<Trap>().unwrap(), Trap::UnreachableCodeReached);
assert!(error.root_cause().is::<Trap>());

let overflow = instance.get_typed_func::<(), ()>(&mut store, "overflow")?;
let error = overflow.call(&mut store, ()).unwrap_err();
assert_eq!(*error.downcast_ref::<Trap>().unwrap(), Trap::StackOverflow);

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

StackOverflow

The current stack space was exhausted.

MemoryOutOfBounds

An out-of-bounds memory access.

HeapMisaligned

A wasm atomic operation was presented with a not-naturally-aligned linear-memory address.

TableOutOfBounds

An out-of-bounds access to a table.

IndirectCallToNull

Indirect call to a null table entry.

BadSignature

Signature mismatch on indirect call.

IntegerOverflow

An integer arithmetic operation caused an overflow.

IntegerDivisionByZero

An integer division by zero.

BadConversionToInteger

Failed float-to-int conversion.

UnreachableCodeReached

Code that was supposed to have been unreachable was reached.

Interrupt

Execution has potentially run too long and may be interrupted.

AlwaysTrapAdapter

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.

OutOfFuel

When wasm code is configured to consume fuel and it runs out of fuel then this trap will be raised.

AtomicWaitNonSharedMemory

Used to indicate that a trap was raised by atomic wait operations on non shared memory.

NullReference

Call to a null reference.

ArrayOutOfBounds

Attempt to access beyond the bounds of an array.

AllocationTooLarge

Attempted an allocation that was too large to succeed.

CastFailure

Attempted to cast a reference to a type that it is not an instance of.

CannotEnterComponent

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.

Implementations

impl Trap

pub fn from_u8(byte: u8) -> Option<Trap>

Available on crate feature runtime only.

Converts a byte back into a Trap if its in-bounds

Trait Implementations

impl Clone for Trap

fn clone(&self) -> Trap

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Trap

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for Trap

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Error for Trap

Available on crate feature std only.

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl Hash for Trap

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Trap

fn eq(&self, other: &Trap) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for Trap

impl Eq for Trap

impl StructuralPartialEq for Trap