Struct wasmtime::AnyRef

pub struct AnyRef { /* private fields */ }

Available on crate feature 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 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 is_i31(&self, store: impl AsContext) -> Result<bool>

Is this anyref an i31?

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

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.

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

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

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

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

Trait Implementations

impl Debug for AnyRef

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

Formats the value using the given formatter.