Struct AnyRef

pub struct AnyRef { /* private fields */ }

Available on crate features gc and runtime only.

An anyref GC reference.

The AnyRef type represents WebAssembly anyref values. These can be references to structs and arrays or inline/unboxed 31-bit integers. Unlike externref, Wasm guests can directly allocate anyrefs.

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

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

Example

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

let engine = Engine::new(&config)?;

// Define a module which does stuff with `anyref`s.
let module = Module::new(&engine, r#"
    (module
        (func (export "increment-if-i31") (param (ref null any)) (result (ref null any))
            block
                ;; Try to cast the arg to an `i31`, otherwise branch out
                ;; of this `block`.
                local.get 0
                br_on_cast_fail (ref null any) (ref i31) 0
                ;; Get the `i31`'s inner value and add one to it.
                i31.get_u
                i32.const 1
                i32.add
                ;; Wrap the incremented value back into an `i31` reference and
                ;; return it.
                ref.i31
                return
            end

            ;; If the `anyref` we were given is not an `i31`, just return it
            ;; as-is.
            local.get 0
        )
    )
"#)?;

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

// Extract the function.
let increment_if_i31 = instance
    .get_typed_func::<Option<Rooted<AnyRef>>, Option<Rooted<AnyRef>>>(
        &mut store,
        "increment-if-i31",
    )?;

{
    // Create a new scope for the `Rooted` arguments and returns.
    let mut scope = RootScope::new(&mut store);

    // Call the function with an `i31`.
    let arg = AnyRef::from_i31(&mut scope, I31::wrapping_u32(419));
    let result = increment_if_i31.call(&mut scope, Some(arg))?;
    assert_eq!(result.unwrap().as_i31(&scope)?, Some(I31::wrapping_u32(420)));

    // Call the function with something that isn't an `i31`.
    let result = increment_if_i31.call(&mut scope, None)?;
    assert!(result.is_none());
}

Implementations

impl AnyRef

pub fn from_i31(store: impl AsContextMut, value: I31) -> Rooted<Self>

Construct an anyref from an i31.

Example

let mut store = Store::<()>::default();

// Create an `i31`.
let i31 = I31::wrapping_u32(999);

// Convert it into an `anyref`.
let anyref = AnyRef::from_i31(&mut store, i31);

pub fn convert_extern( store: impl AsContextMut, externref: Rooted<ExternRef>, ) -> Result<Rooted<Self>>

Convert an externref into an anyref.

This is equivalent to the any.convert_extern instruction in Wasm.

You can recover the underlying externref again via the ExternRef::convert_any method or the extern.convert_any Wasm instruction.

Returns an error if the externref GC reference has been unrooted (eg if you attempt to use a Rooted<ExternRef> after exiting the scope it was rooted within). See the documentation for Rooted<T> for more details.

Example

use wasmtime::*;
let engine = Engine::default();
let mut store = Store::new(&engine, ());

// Create an `externref`.
let externref = ExternRef::new(&mut store, "hello")?;

// Convert that `externref` into an `anyref`.
let anyref = AnyRef::convert_extern(&mut store, externref)?;

// The converted value is an `anyref` but is not an `eqref`.
assert_eq!(anyref.matches_ty(&store, &HeapType::Any)?, true);
assert_eq!(anyref.matches_ty(&store, &HeapType::Eq)?, false);

// We can convert it back to the original `externref` and get its
// associated host data again.
let externref = ExternRef::convert_any(&mut store, anyref)?;
let data = externref
    .data(&store)?
    .expect("externref should have host data")
    .downcast_ref::<&str>()
    .expect("host data should be a str");
assert_eq!(*data, "hello");

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

Creates a new strongly-owned AnyRef 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 anyref value which is currently rooted within the Store.

Unsafety

This function is particularly unsafe because raw not only must be a valid anyref value produced prior by AnyRef::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 anyref 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 unsafe fn to_raw(&self, store: impl AsContextMut) -> Result<u32>

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

Returns an error if this anyref 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<HeapType>

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>

Does this anyref 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_eqref(&self, store: impl AsContext) -> Result<bool>

Is this anyref an eqref?

Errors

Return an error if this reference has been unrooted.

Panics

Panics if this reference is associated with a different store.

pub fn as_eqref(&self, store: impl AsContext) -> Result<Option<Rooted<EqRef>>>

Downcast this anyref to an eqref.

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

If this anyref is not an eqref, 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_eqref(&self, store: impl AsContext) -> Result<Rooted<EqRef>>

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

Errors

Return an error if this reference has been unrooted.

Panics

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

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

Is this anyref 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>>

Downcast this anyref to an i31.

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

If this anyref 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>

Downcast this anyref to an i31, panicking if this anyref 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 anyref is not an i31.

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

Is this anyref 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>>>

Downcast this anyref to a structref.

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

If this anyref 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>>

Downcast this anyref to a structref, panicking if this anyref 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 anyref is not a struct.

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

Is this anyref 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>>>

Downcast this anyref to an arrayref.

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

If this anyref 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>>

Downcast this anyref to an arrayref, panicking if this anyref 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 anyref is not an array.

Trait Implementations

impl Debug for AnyRef

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

Formats the value using the given formatter.