pub struct Unrooted<T: GcRef> { /* private fields */ }gc and runtime only.Expand description
A read-only reference to a GC object, valid only until the store’s GC heap next changes.
Unlike Rooted and OwnedRooted, an Unrooted reference
does not keep its object alive (hence, “unrooted”). This means
that it could become invalid with any action that could mutate the
GC heap. If it becomes invalid, APIs will fail cleanly (indicate
that it is stale) rather than crashing or panicking.
In exchange, because Unrooted references are not recorded in the
root set, they can be used in non-mut Store contexts, and
operations on them are very cheap.
Getters and allocation methods return Unrooted references by
default: the former allows full read-only heap traversal, and the
latter works because after the allocation, the heap doesn’t
mutate. In both cases, the user is free to root the value
themselves (see Unrooted::to_rooted or
Unrooted::to_owned_rooted). This “opt-in” rooting is an
intentional pay-as-you-go design choice.
§Invalidation
In general, an Unrooted reference may (but is not guaranteed
to!) become invalid when any method that takes a &mut Store is
invoked on the corresponding store. This includes both Wasm
execution and use of host APIs, for example those that allocate or
mutate GC objects.
§Conversions
Use Rooted::to_unrooted or OwnedRooted::to_unrooted to get an
unrooted reference to a rooted object, and Unrooted::to_rooted or
Unrooted::to_owned_rooted to root the object again, to keep it alive
and usable after the heap next changes. Reading a GC reference out of an
object through an unrooted reference, for example with
Unrooted::<StructRef>::field, gives an unrooted reference as well.
Since rooting any reference invalidates all unrooted references,
it is not possible to root multiple unrooted references
one-by-one. Instead, use Rooted::to_all_rooted,
OwnedRooted::to_all_owned_rooted, or
Val::ensure_all_rooted to root several unrooted references in
a batch.
§Equality and Hashing
Unrooted does not implement PartialEq, Eq, or Hash, for the
same reasons that Rooted does not. Use Unrooted::ref_eq and
Unrooted::ref_hash to compare and hash the referenced objects.
Implementations§
Source§impl<T: GcRef> Unrooted<T>
impl<T: GcRef> Unrooted<T>
Sourcepub fn is_valid(&self, store: impl AsContext) -> bool
pub fn is_valid(&self, store: impl AsContext) -> bool
Is this reference still valid?
§Panics
Panics if this reference is associated with a different store.
Sourcepub fn ref_eq(store: impl AsContext, a: &Self, b: &Self) -> Result<bool>
pub fn ref_eq(store: impl AsContext, a: &Self, b: &Self) -> Result<bool>
Do these two unrooted references refer to the same GC object?
This is reference equality, not Wasm-level structural equality; see
Rooted::ref_eq.
§Errors
Returns an error if either reference is no longer valid.
§Panics
Panics if either reference is associated with a different store.
Sourcepub fn ref_hash<H>(&self, store: impl AsContext, state: &mut H) -> Result<()>where
H: Hasher,
pub fn ref_hash<H>(&self, store: impl AsContext, state: &mut H) -> Result<()>where
H: Hasher,
Hash the GC object that this unrooted reference refers to, consistently
with Unrooted::ref_eq; see Rooted::ref_hash.
§Errors
Returns an error if this reference is no longer valid.
§Panics
Panics if this reference is associated with a different store.
Sourcepub fn to_rooted(&self, store: impl AsContextMut) -> Result<Rooted<T>>
pub fn to_rooted(&self, store: impl AsContextMut) -> Result<Rooted<T>>
Roots the referenced object in the current LIFO rooting scope, to keep
it alive and usable after this reference becomes invalid; see
Rooted.
Rooting a reference invalidates every other unrooted reference into the
store’s GC heap; use Rooted::to_all_rooted to root several references at once.
§Errors
Returns an error if this reference is no longer valid.
§Panics
Panics if this reference is associated with a different store.
Sourcepub fn to_owned_rooted(
&self,
store: impl AsContextMut,
) -> Result<OwnedRooted<T>>
pub fn to_owned_rooted( &self, store: impl AsContextMut, ) -> Result<OwnedRooted<T>>
Roots the referenced object until the returned handle is dropped, to
keep it alive and usable after this reference becomes invalid; see
OwnedRooted.
Rooting a reference invalidates every other unrooted reference into the
store’s GC heap; use OwnedRooted::to_all_owned_rooted to root several references at once.
§Errors
Returns an error if this reference is no longer valid.
This function will return an OutOfMemory
error when memory allocation fails. See the OutOfMemory type’s
documentation for details on Wasmtime’s out-of-memory handling.
§Panics
Panics if this reference is associated with a different store.
Source§impl Unrooted<AnyRef>
impl Unrooted<AnyRef>
Sourcepub fn ty(&self, store: impl AsContext) -> Result<HeapType>
pub fn ty(&self, store: impl AsContext) -> Result<HeapType>
The type of the referenced object; see AnyRef::ty.
§Errors
Returns an error if this reference is no longer valid.
§Panics
Panics if this reference is associated with a different store.
Source§impl Unrooted<StructRef>
impl Unrooted<StructRef>
Sourcepub fn ty(&self, store: impl AsContext) -> Result<StructType>
pub fn ty(&self, store: impl AsContext) -> Result<StructType>
Sourcepub fn field(&self, store: impl AsContext, index: usize) -> Result<Val>
pub fn field(&self, store: impl AsContext, index: usize) -> Result<Val>
The value of the struct’s indexth field. i8 and i16 fields are
zero-extended into Val::I32s.
Any GC reference in the returned value is unrooted, and so is valid only
until the store’s GC heap next changes; see Unrooted.
§Errors
Returns an error if this reference is no longer valid, or if the
struct has no indexth field.
§Panics
Panics if this reference is associated with a different store.
Sourcepub fn fields<'a, T: 'static>(
&'a self,
store: impl Into<StoreContext<'a, T>>,
) -> Result<impl ExactSizeIterator<Item = Val> + 'a>
pub fn fields<'a, T: 'static>( &'a self, store: impl Into<StoreContext<'a, T>>, ) -> Result<impl ExactSizeIterator<Item = Val> + 'a>
The values of the struct’s fields; see Unrooted::<StructRef>::field.
Any GC references in the returned values are unrooted, and so are valid
only until the store’s GC heap next changes; see Unrooted.
§Errors
Returns an error if this reference is no longer valid.
§Panics
Panics if this reference is associated with a different store.
Source§impl Unrooted<ArrayRef>
impl Unrooted<ArrayRef>
Sourcepub fn get(&self, store: impl AsContext, index: u32) -> Result<Val>
pub fn get(&self, store: impl AsContext, index: u32) -> Result<Val>
The value of the array’s indexth element. i8 and i16 elements
are zero-extended into Val::I32s.
Any GC reference in the returned value is unrooted, and so is valid only
until the store’s GC heap next changes; see Unrooted.
§Errors
Returns an error if this reference is no longer valid, or if index is
out of bounds.
§Panics
Panics if this reference is associated with a different store.
Source§impl Unrooted<ExnRef>
impl Unrooted<ExnRef>
Sourcepub fn field(&self, store: impl AsContext, index: usize) -> Result<Val>
pub fn field(&self, store: impl AsContext, index: usize) -> Result<Val>
The value of the exception’s indexth payload field.
Any GC reference in the returned value is unrooted, and so is valid only
until the store’s GC heap next changes; see Unrooted.
§Errors
Returns an error if this reference is no longer valid, or if the
exception has no indexth field.
§Panics
Panics if this reference is associated with a different store.
Sourcepub fn fields<'a, T: 'static>(
&'a self,
store: impl Into<StoreContext<'a, T>>,
) -> Result<impl ExactSizeIterator<Item = Val> + 'a>
pub fn fields<'a, T: 'static>( &'a self, store: impl Into<StoreContext<'a, T>>, ) -> Result<impl ExactSizeIterator<Item = Val> + 'a>
The values of the exception’s payload fields; see
Unrooted::<ExnRef>::field.
Any GC references in the returned values are unrooted, and so are valid
only until the store’s GC heap next changes; see Unrooted.
§Errors
Returns an error if this reference is no longer valid.
§Panics
Panics if this reference is associated with a different store.
Source§impl Unrooted<ExternRef>
impl Unrooted<ExternRef>
Sourcepub fn data<'a, T: 'static>(
&self,
store: impl Into<StoreContext<'a, T>>,
) -> Result<Option<&'a (dyn Any + Send + Sync)>>
pub fn data<'a, T: 'static>( &self, store: impl Into<StoreContext<'a, T>>, ) -> Result<Option<&'a (dyn Any + Send + Sync)>>
The host data of the referenced externref; see ExternRef::data.
§Errors
Returns an error if this reference is no longer valid.
§Panics
Panics if this reference is associated with a different store.
Trait Implementations§
impl<T: GcRef> Copy for Unrooted<T>
Auto Trait Implementations§
impl<T> Forget for Unrooted<T>
impl<T> Freeze for Unrooted<T>
impl<T> Move for Unrooted<T>
impl<T> RefUnwindSafe for Unrooted<T>
impl<T> Send for Unrooted<T>
impl<T> Sync for Unrooted<T>
impl<T> Unpin for Unrooted<T>
impl<T> UnsafeUnpin for Unrooted<T>
impl<T> UnwindSafe for Unrooted<T>
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> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
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