Struct EqRef

pub struct EqRef { /* private fields */ }

A reference to a GC-managed object that can be tested for equality.

The WebAssembly reference types that can be tested for equality, and therefore are eqrefs, include structrefs, arrayrefs, and i31refs. funcrefs, exnrefs, and externrefs cannot be tested for equality by Wasm, and are not eqrefs.

Use the Rooted::ref_eq method to actually test two references for equality.

Like all WebAssembly references, these are opaque to and unforgeable by Wasm: they cannot be faked and Wasm cannot, for example, cast the integer 0x12345678 into a reference, pretend it is a valid eqref, and trick the host into dereferencing it and segfaulting or worse.

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

Example

use wasmtime::*;

let mut config = Config::new();
config.wasm_function_references(true);
config.wasm_gc(true);

let engine = Engine::new(&config)?;
let mut store = Store::new(&engine, ());

// Define a module that exports a function that returns a new `eqref` each
// time it is invoked.
let module = Module::new(&engine, r#"
    (module
        (global $g (mut i32) (i32.const 0))
        (func (export "new-eqref") (result (ref eq))
            ;; Increment $g.
            global.get $g
            i32.const 1
            i32.add
            global.set $g

            ;; Create an `i31ref`, which is a kind of `eqref`, from $g.
            global.get $g
            ref.i31
        )
    )
"#)?;

// Instantiate the module.
let instance = Instance::new(&mut store, &module, &[])?;

// Get the exported function.
let new_eqref = instance.get_typed_func::<(), Rooted<EqRef>>(&mut store, "new-eqref")?;

{
    let mut scope = RootScope::new(&mut store);

    // Call the function to get an `eqref`.
    let x = new_eqref.call(&mut scope, ())?;

    // `x` is equal to itself!
    assert!(Rooted::ref_eq(&scope, &x, &x)?);

    // Call the function again to get a new, different `eqref`.
    let y = new_eqref.call(&mut scope, ())?;

    // `x` is not equal to `y`!
    assert!(!Rooted::ref_eq(&scope, &x, &y)?);
}

Implementations

impl EqRef

pub fn ty(&self, store: impl AsContext) -> Result<HeapType, 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 eqref 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 is_i31(&self, store: impl AsContext) -> Result<bool, Error>

Is this eqref an i31?

Errors

Return an error if this reference has been unrooted.

Panics

Panics if this reference is associated with a different store.

pub fn as_i31(&self, store: impl AsContext) -> Result<Option<I31>, Error>

Downcast this eqref to an i31.

If this eqref is an i31, then Some(_) is returned.

If this eqref is not an i31, then None is returned.

Errors

Return an error if this reference has been unrooted.

Panics

Panics if this reference is associated with a different store.

pub fn unwrap_i31(&self, store: impl AsContext) -> Result<I31, Error>

Downcast this eqref to an i31, panicking if this eqref is not an i31.

Errors

Return an error if this reference has been unrooted.

Panics

Panics if this reference is associated with a different store, or if this eqref is not an i31.

pub fn is_struct(&self, store: impl AsContext) -> Result<bool, Error>

Is this eqref a structref?

Errors

Return an error if this reference has been unrooted.

Panics

Panics if this reference is associated with a different store.

pub fn as_struct( &self, store: impl AsContext, ) -> Result<Option<Rooted<StructRef>>, Error>

Downcast this eqref to a structref.

If this eqref is a structref, then Some(_) is returned.

If this eqref is not a structref, then None is returned.

Errors

Return an error if this reference has been unrooted.

Panics

Panics if this reference is associated with a different store.

pub fn unwrap_struct( &self, store: impl AsContext, ) -> Result<Rooted<StructRef>, Error>

Downcast this eqref to a structref, panicking if this eqref is not a structref.

Errors

Return an error if this reference has been unrooted.

Panics

Panics if this reference is associated with a different store, or if this eqref is not a struct.

pub fn is_array(&self, store: impl AsContext) -> Result<bool, Error>

Is this eqref an arrayref?

Errors

Return an error if this reference has been unrooted.

Panics

Panics if this reference is associated with a different store.

pub fn as_array( &self, store: impl AsContext, ) -> Result<Option<Rooted<ArrayRef>>, Error>

Downcast this eqref to an arrayref.

If this eqref is an arrayref, then Some(_) is returned.

If this eqref is not an arrayref, then None is returned.

Errors

Return an error if this reference has been unrooted.

Panics

Panics if this reference is associated with a different store.

pub fn unwrap_array( &self, store: impl AsContext, ) -> Result<Rooted<ArrayRef>, Error>

Downcast this eqref to an arrayref, panicking if this eqref is not an arrayref.

Errors

Return an error if this reference has been unrooted.

Panics

Panics if this reference is associated with a different store, or if this eqref is not an array.

Trait Implementations

impl Debug for EqRef

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

Formats the value using the given formatter.