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 ManuallyRooted<ExnRef> as a type parameter with Func::typed- and Func::wrap-style APIs.

Implementations

impl ExnRef

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

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.

Unsafety

This function is particularly unsafe 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 safe 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 safe Rust APIs of TypedFunc and friends.

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

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>, Error>

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 unsafe fn to_raw(&self, store: impl AsContextMut) -> Result<u32, Error>

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

Returns an error if this exnref has been unrooted.

Unsafety

Produces a raw value which is only safe 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, Error>

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, Error>

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>( &'a self, store: impl Into<StoreContextMut<'a, T>>, ) -> Result<impl ExactSizeIterator + 'a, Error>

where T: 'static,

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, Error>

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, Error>

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

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

Formats the value using the given formatter.