wasmtime

Enum Trap

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

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

This enum is marked as 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. Read more
1.0.0 · Source§

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

Performs copy-assignment from source. Read more
§

impl Debug for Trap

§

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

Formats the value using the given formatter. Read more
§

impl Display for Trap

§

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

Formats the value using the given formatter. Read more
§

impl Error for Trap

Available on crate feature std only.
1.30.0 · Source§

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

Returns the lower-level source of this error, if any. Read more
1.0.0 · Source§

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()
1.0.0 · Source§

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

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

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. Read more
§

impl Hash for Trap

§

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

Feeds this value into the given Hasher. Read more
1.3.0 · Source§

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

Feeds a slice of this type into the given Hasher. Read more
§

impl PartialEq for Trap

§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

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

Auto Trait Implementations§

§

impl Freeze for Trap

§

impl RefUnwindSafe for Trap

§

impl Send for Trap

§

impl Sync for Trap

§

impl Unpin for Trap

§

impl UnwindSafe for Trap

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dst: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

§

fn equivalent(&self, key: &K) -> bool

Compare self to key and return true if they are equal.
§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

§

impl<T> IntoAnyhow for T
where T: Into<Error>,

§

fn into_anyhow(self) -> Error

Converts self into an anyhow::Error.
Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<T> Pointable for T

§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T> ToString for T
where T: Display + ?Sized,

Source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.