Struct ExnRef 

pub struct ExnRef { /* private fields */ }

An exnref GC reference.

The ExnRef type represents WebAssembly exnref values. These are references to exception objects created either by catching a thrown exception in WebAssembly with a catch_ref clause of a try_table, or by allocating via the host API.

Note that you can also use Rooted<ExnRef> and OwnedRooted<ExnRef> as a type parameter with Func::typed- and Func::wrap-style APIs.

Implementations

impl ExnRef

pub fn from_raw(store: impl AsContextMut, raw: u32) -> Option<Rooted<Self>>

Available on crate features runtime and gc only.

Creates a new strongly-owned ExnRef from the raw value provided.

This is intended to be used in conjunction with Func::new_unchecked, Func::call_unchecked, and ValRaw with its anyref field.

This function assumes that raw is an exnref value which is currently rooted within the Store.

Correctness

This function is tricky to get right because raw not only must be a valid exnref value produced prior by ExnRef::to_raw but it must also be correctly rooted within the store. When arguments are provided to a callback with Func::new_unchecked, for example, or returned via Func::call_unchecked, if a GC is performed within the store then floating exnref values are not rooted and will be GC’d, meaning that this function will no longer be correct to call with the values cleaned up. This function must be invoked before possible GC operations can happen (such as calling Wasm).

When in doubt try to not use this. Instead use the Rust APIs of TypedFunc and friends. Note though that this function is not unsafe as any value can be passed in. Incorrect values can result in runtime panics, however, so care must still be taken with this method.

pub fn new( store: impl AsContextMut, allocator: &ExnRefPre, tag: &Tag, fields: &[Val], ) -> Result<Rooted<ExnRef>>

Available on crate features runtime and gc only.

Synchronously allocate a new exception object and get a reference to it.

Automatic Garbage Collection

If the GC heap is at capacity, and there isn’t room for allocating this new exception object, then this method will automatically trigger a synchronous collection in an attempt to free up space in the GC heap.

Errors

If the given fields values’ types do not match the field types of the allocator’s exception type, an error is returned.

If the allocation cannot be satisfied because the GC heap is currently out of memory, then a GcHeapOutOfMemory<()> error is returned. The allocation might succeed on a second attempt if you drop some rooted GC references and try again.

Panics

Panics if your engine is configured for async; use ExnRef::new_async to perform synchronous allocation instead.

Panics if the allocator, or any of the field values, is not associated with the given store.

pub async fn new_async( store: impl AsContextMut, allocator: &ExnRefPre, tag: &Tag, fields: &[Val], ) -> Result<Rooted<ExnRef>>

Available on crate features runtime and gc and async only.

Asynchronously allocate a new exception object and get a reference to it.

Automatic Garbage Collection

If the GC heap is at capacity, and there isn’t room for allocating this new exn, then this method will automatically trigger a synchronous collection in an attempt to free up space in the GC heap.

Errors

If the given fields values’ types do not match the field types of the allocator’s exception type, an error is returned.

If the allocation cannot be satisfied because the GC heap is currently out of memory, then a GcHeapOutOfMemory<()> error is returned. The allocation might succeed on a second attempt if you drop some rooted GC references and try again.

Panics

Panics if your engine is not configured for async; use ExnRef::new to perform synchronous allocation instead.

Panics if the allocator, or any of the field values, is not associated with the given store.

pub fn to_raw(&self, store: impl AsContextMut) -> Result<u32>

Available on crate features runtime and gc only.

Converts this ExnRef to a raw value suitable to store within a ValRaw.

Returns an error if this exnref has been unrooted.

Correctness

Produces a raw value which is only valid to pass into a store if a GC doesn’t happen between when the value is produce and when it’s passed into the store.

pub fn ty(&self, store: impl AsContext) -> Result<ExnType>

Available on crate features runtime and gc only.

Get the type of this reference.

Errors

Return an error if this reference has been unrooted.

Panics

Panics if this reference is associated with a different store.

pub fn matches_ty(&self, store: impl AsContext, ty: &HeapType) -> Result<bool>

Available on crate features runtime and gc only.

Does this exnref match the given type?

That is, is this object’s type a subtype of the given type?

Errors

Return an error if this reference has been unrooted.

Panics

Panics if this reference is associated with a different store.

pub fn fields<'a, T: 'static>( &'a self, store: impl Into<StoreContextMut<'a, T>>, ) -> Result<impl ExactSizeIterator<Item = Val> + 'a>

Available on crate features runtime and gc only.

Get the values of this exception object’s fields.

Errors

Return an error if this reference has been unrooted.

Panics

Panics if this reference is associated with a different store.

pub fn field(&self, store: impl AsContextMut, index: usize) -> Result<Val>

Available on crate features runtime and gc only.

Get this exception object’s indexth field.

Errors

Returns an Err(_) if the index is out of bounds or this reference has been unrooted.

Panics

Panics if this reference is associated with a different store.

pub fn tag(&self, store: impl AsContextMut) -> Result<Tag>

Available on crate features runtime and gc only.

Get this exception object’s associated tag.

Errors

Returns an Err(_) if this reference has been unrooted.

Panics

Panics if this reference is associated with a different store.

Trait Implementations

impl Debug for ExnRef

Available on crate features gc and runtime only.

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

Formats the value using the given formatter.