pub struct AnyRef { /* private fields */ }
Expand description
An anyref
GC reference.
The AnyRef
type represents WebAssembly anyref
values. These can be
references to struct
s and array
s or inline/unboxed 31-bit
integers. Unlike externref
, Wasm guests can directly allocate anyref
s.
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
impl AnyRef
sourcepub fn from_i31(store: impl AsContextMut, value: I31) -> Rooted<Self>
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);
sourcepub unsafe fn from_raw(
store: impl AsContextMut,
raw: u32,
) -> Option<Rooted<Self>>
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.
sourcepub unsafe fn to_raw(&self, store: impl AsContextMut) -> Result<u32>
pub unsafe fn to_raw(&self, store: impl AsContextMut) -> Result<u32>
sourcepub fn unwrap_i31(&self, store: impl AsContext) -> Result<I31>
pub fn unwrap_i31(&self, store: impl AsContext) -> Result<I31>
Trait Implementations§
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> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> IntoEither for T
impl<T> IntoEither for T
source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
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 moresource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
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