pub enum MaybeRooted<T: GcRef> {
Rooted(Rooted<T>),
Unrooted(Unrooted<T>),
}runtime only.Expand description
A reference to a GC object of type T, as held in a Val
or Ref: either rooted or unrooted.
A MaybeRooted::Rooted reference keeps its object alive until the
current LIFO rooting scope exits; see Rooted. A
MaybeRooted::Unrooted reference is cheaper to create and needs only
shared access to the store, but is valid only until the store’s GC heap
next changes; see Unrooted.
APIs that read GC values, such as Global::get,
StructRef::field, or the results of
Func::call, return unrooted references, so that
rooting is always opt-in: the caller can choose to root them, and how
(with MaybeRooted::to_rooted, MaybeRooted::to_owned_rooted, or
Val::ensure_all_rooted for several at
once), or to keep them unrooted.
APIs that take GC values to store or pass along, such as
Global::set,
StructRef::new, or the arguments of
Func::call, mutate the store, which invalidates
unrooted references, and so they require rooted references, and return an
error for unrooted ones; root them first.
Variants§
Rooted(Rooted<T>)
A reference rooted in the current LIFO rooting scope; see Rooted.
Unrooted(Unrooted<T>)
A reference that is not rooted, and is valid only until the store’s GC
heap next changes; see Unrooted.
Implementations§
Source§impl<T: GcRef> MaybeRooted<T>
impl<T: GcRef> MaybeRooted<T>
Sourcepub fn is_unrooted(&self) -> bool
pub fn is_unrooted(&self) -> bool
Is this an unrooted reference?
Sourcepub fn as_rooted(&self) -> Option<Rooted<T>>
pub fn as_rooted(&self) -> Option<Rooted<T>>
Get this reference as a Rooted<T>, if it is rooted.
Sourcepub fn unwrap_rooted(&self) -> Rooted<T>
pub fn unwrap_rooted(&self) -> Rooted<T>
Sourcepub fn as_unrooted(&self) -> Option<Unrooted<T>>
pub fn as_unrooted(&self) -> Option<Unrooted<T>>
Get this reference as an Unrooted<T>, if it is unrooted.
Sourcepub fn unwrap_unrooted(&self) -> Unrooted<T>
pub fn unwrap_unrooted(&self) -> Unrooted<T>
Get this reference as an Unrooted<T>, panicking if it is not
unrooted.
§Panics
Panics if this reference is not unrooted.
Sourcepub fn validate_rooted(&self) -> Result<Rooted<T>>
pub fn validate_rooted(&self) -> Result<Rooted<T>>
Get this reference as a Rooted<T>, or return an error if it is not
rooted.
APIs that take GC values to store or pass along, such as
StructRef::new, use this to check that their
values are rooted.
§Errors
Returns an error if this reference is not rooted.
Sourcepub fn ensure_rooted(&mut self, store: impl AsContextMut) -> Result<Rooted<T>>
pub fn ensure_rooted(&mut self, store: impl AsContextMut) -> Result<Rooted<T>>
Root this reference in place, if it is not rooted already, in the
current LIFO rooting scope, and return it as a Rooted<T>.
Rooting a reference invalidates every other unrooted reference into the
store’s GC heap; use Rooted::to_all_rooted or
Val::ensure_all_rooted to root
several references at once.
§Errors
Returns an error if this reference is unrooted and 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>>
Get a Rooted<T> referencing the same GC object as this reference:
this reference itself if it is rooted, or a new root in the current
LIFO rooting scope if it is unrooted.
Rooting a reference invalidates every other unrooted reference into the
store’s GC heap; use Rooted::to_all_rooted or
Val::ensure_all_rooted to root
several references at once.
§Errors
Returns an error if this reference is unrooted and no longer valid.
§Panics
Panics if this reference is associated with a different store.
Sourcepub fn to_unrooted(&self, store: impl AsContext) -> Result<Unrooted<T>>
pub fn to_unrooted(&self, store: impl AsContext) -> Result<Unrooted<T>>
Get an Unrooted<T> referencing the same GC object as this
reference.
§Errors
Returns an error if this reference is no longer valid: if it is rooted and has since been unrooted, or if it is unrooted and the store’s GC heap has since changed.
§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>>
Create an OwnedRooted<T> holding onto the same GC object as this
reference.
§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.
Trait Implementations§
Source§impl<T: GcRef> Clone for MaybeRooted<T>
impl<T: GcRef> Clone for MaybeRooted<T>
impl<T: GcRef> Copy for MaybeRooted<T>
Source§impl<T: GcRef> Debug for MaybeRooted<T>
impl<T: GcRef> Debug for MaybeRooted<T>
Source§impl From<MaybeRooted<ArrayRef>> for MaybeRooted<AnyRef>
impl From<MaybeRooted<ArrayRef>> for MaybeRooted<AnyRef>
Source§fn from(r: MaybeRooted<ArrayRef>) -> Self
fn from(r: MaybeRooted<ArrayRef>) -> Self
Source§impl From<MaybeRooted<EqRef>> for MaybeRooted<AnyRef>
impl From<MaybeRooted<EqRef>> for MaybeRooted<AnyRef>
Source§fn from(r: MaybeRooted<EqRef>) -> Self
fn from(r: MaybeRooted<EqRef>) -> Self
Source§impl From<MaybeRooted<StructRef>> for MaybeRooted<AnyRef>
impl From<MaybeRooted<StructRef>> for MaybeRooted<AnyRef>
Source§fn from(r: MaybeRooted<StructRef>) -> Self
fn from(r: MaybeRooted<StructRef>) -> Self
Auto Trait Implementations§
impl<T> Forget for MaybeRooted<T>
impl<T> Freeze for MaybeRooted<T>
impl<T> Move for MaybeRooted<T>
impl<T> RefUnwindSafe for MaybeRooted<T>
impl<T> Send for MaybeRooted<T>
impl<T> Sync for MaybeRooted<T>
impl<T> Unpin for MaybeRooted<T>
impl<T> UnsafeUnpin for MaybeRooted<T>
impl<T> UnwindSafe for MaybeRooted<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