Struct wasmtime::AnyRef

source ·
pub struct AnyRef { /* private fields */ }
Expand description

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§

source§

impl AnyRef

source

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);
source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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§

source§

impl Debug for AnyRef

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl Freeze for AnyRef

§

impl RefUnwindSafe for AnyRef

§

impl Send for AnyRef

§

impl Sync for AnyRef

§

impl Unpin for AnyRef

§

impl UnwindSafe for AnyRef

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

impl<T> Pointable for T

source§

const ALIGN: usize = _

The alignment of pointer.
source§

type Init = T

The type for initializers.
source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T> Same for T

source§

type Output = T

Should always be Self
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> GcRef for T
where T: GcRefImpl,