Skip to main content

Unrooted

Struct Unrooted 

Source
pub struct Unrooted<T: GcRef> { /* private fields */ }
Available on crate features 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>

Source

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.

Source

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.

Source

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.

Source

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.

Source

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>

Source

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

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

The referenced i31, if this refers to one.

§Errors

Returns an error if this reference is no longer valid.

§Panics

Panics if this reference is associated with a different store.

Source

pub fn as_struct( &self, store: impl AsContext, ) -> Result<Option<Unrooted<StructRef>>>

This reference as a reference to a struct, if it refers to one.

§Errors

Returns an error if this reference is no longer valid.

§Panics

Panics if this reference is associated with a different store.

Source

pub fn as_array( &self, store: impl AsContext, ) -> Result<Option<Unrooted<ArrayRef>>>

This reference as a reference to an array, if it refers to one.

§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>

Source

pub fn ty(&self, store: impl AsContext) -> Result<StructType>

The type of the referenced struct.

§Errors

Returns an error if this reference is no longer valid.

§Panics

Panics if this reference is associated with a different store.

Source

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.

Source

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>

Source

pub fn ty(&self, store: impl AsContext) -> Result<ArrayType>

The type of the referenced array.

§Errors

Returns an error if this reference is no longer valid.

§Panics

Panics if this reference is associated with a different store.

Source

pub fn len(&self, store: impl AsContext) -> Result<u32>

The number of elements in the array.

§Errors

Returns an error if this reference is no longer valid.

§Panics

Panics if this reference is associated with a different store.

Source

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>

Source

pub fn ty(&self, store: impl AsContext) -> Result<ExnType>

The type of the referenced exception.

§Errors

Returns an error if this reference is no longer valid.

§Panics

Panics if this reference is associated with a different store.

Source

pub fn tag(&self, store: impl AsContext) -> Result<Tag>

The tag of the referenced exception.

§Errors

Returns an error if this reference is no longer valid.

§Panics

Panics if this reference is associated with a different store.

Source

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.

Source

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>

Source

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§

Source§

impl<T: GcRef> Clone for Unrooted<T>

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl<T: GcRef> Copy for Unrooted<T>

Source§

impl<T: GcRef> Debug for Unrooted<T>

Source§

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

Formats the value using the given formatter. Read more
Source§

impl From<Unrooted<AnyRef>> for Val

Source§

fn from(val: Unrooted<AnyRef>) -> Val

Converts to this type from the input type.
Source§

impl From<Unrooted<AnyRef>> for Ref

Source§

fn from(e: Unrooted<AnyRef>) -> Ref

Converts to this type from the input type.
Source§

impl From<Unrooted<ArrayRef>> for Unrooted<AnyRef>

Source§

fn from(r: Unrooted<ArrayRef>) -> Self

Converts to this type from the input type.
Source§

impl From<Unrooted<ArrayRef>> for MaybeRooted<AnyRef>

Source§

fn from(r: Unrooted<ArrayRef>) -> Self

Converts to this type from the input type.
Source§

impl From<Unrooted<ArrayRef>> for Val

Source§

fn from(val: Unrooted<ArrayRef>) -> Val

Converts to this type from the input type.
Source§

impl From<Unrooted<ArrayRef>> for Ref

Source§

fn from(e: Unrooted<ArrayRef>) -> Ref

Converts to this type from the input type.
Source§

impl From<Unrooted<EqRef>> for Unrooted<AnyRef>

Source§

fn from(r: Unrooted<EqRef>) -> Self

Converts to this type from the input type.
Source§

impl From<Unrooted<EqRef>> for MaybeRooted<AnyRef>

Source§

fn from(r: Unrooted<EqRef>) -> Self

Converts to this type from the input type.
Source§

impl From<Unrooted<EqRef>> for Val

Source§

fn from(val: Unrooted<EqRef>) -> Val

Converts to this type from the input type.
Source§

impl From<Unrooted<EqRef>> for Ref

Source§

fn from(e: Unrooted<EqRef>) -> Ref

Converts to this type from the input type.
Source§

impl From<Unrooted<ExnRef>> for Val

Source§

fn from(val: Unrooted<ExnRef>) -> Val

Converts to this type from the input type.
Source§

impl From<Unrooted<ExnRef>> for Ref

Source§

fn from(e: Unrooted<ExnRef>) -> Ref

Converts to this type from the input type.
Source§

impl From<Unrooted<ExternRef>> for Val

Source§

fn from(val: Unrooted<ExternRef>) -> Val

Converts to this type from the input type.
Source§

impl From<Unrooted<ExternRef>> for Ref

Source§

fn from(e: Unrooted<ExternRef>) -> Ref

Converts to this type from the input type.
Source§

impl From<Unrooted<StructRef>> for Unrooted<AnyRef>

Source§

fn from(r: Unrooted<StructRef>) -> Self

Converts to this type from the input type.
Source§

impl From<Unrooted<StructRef>> for MaybeRooted<AnyRef>

Source§

fn from(r: Unrooted<StructRef>) -> Self

Converts to this type from the input type.
Source§

impl From<Unrooted<StructRef>> for Val

Source§

fn from(val: Unrooted<StructRef>) -> Val

Converts to this type from the input type.
Source§

impl From<Unrooted<StructRef>> for Ref

Source§

fn from(e: Unrooted<StructRef>) -> Ref

Converts to this type from the input type.
Source§

impl<T: GcRef> From<Unrooted<T>> for MaybeRooted<T>

Source§

fn from(r: Unrooted<T>) -> Self

Converts to this type from the input type.

Auto Trait Implementations§

§

impl<T> Forget for Unrooted<T>

§

impl<T> Freeze for Unrooted<T>
where PhantomData<fn() -> T>: Freeze,

§

impl<T> Move for Unrooted<T>

§

impl<T> RefUnwindSafe for Unrooted<T>
where PhantomData<fn() -> T>: RefUnwindSafe,

§

impl<T> Send for Unrooted<T>
where PhantomData<fn() -> T>: Send,

§

impl<T> Sync for Unrooted<T>
where PhantomData<fn() -> T>: Sync,

§

impl<T> Unpin for Unrooted<T>
where PhantomData<fn() -> T>: Unpin,

§

impl<T> UnsafeUnpin for Unrooted<T>
where PhantomData<fn() -> T>: UnsafeUnpin,

§

impl<T> UnwindSafe for Unrooted<T>
where PhantomData<fn() -> T>: UnwindSafe,

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> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. 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
§

impl<T> Pointable for T

§

const ALIGN: usize

The alignment of pointer.
§

type Init = T

The type for initializers.
§

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

Initializes a with the given initializer. Read more
§

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

Dereferences the given pointer. Read more
§

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

Mutably dereferences the given pointer. Read more
§

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> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

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

Source§

type Error = !

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

fn try_from(value: U) -> Result<T, !>

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.