Skip to main content

MaybeRooted

Enum MaybeRooted 

Source
pub enum MaybeRooted<T: GcRef> {
    Rooted(Rooted<T>),
    Unrooted(Unrooted<T>),
}
Available on crate feature 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>

Source

pub fn is_rooted(&self) -> bool

Is this a rooted reference?

Source

pub fn is_unrooted(&self) -> bool

Is this an unrooted reference?

Source

pub fn as_rooted(&self) -> Option<Rooted<T>>

Get this reference as a Rooted<T>, if it is rooted.

Source

pub fn unwrap_rooted(&self) -> Rooted<T>

Get this reference as a Rooted<T>, panicking if it is not rooted.

§Panics

Panics if this reference is not rooted.

Source

pub fn as_unrooted(&self) -> Option<Unrooted<T>>

Get this reference as an Unrooted<T>, if it is unrooted.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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>

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 MaybeRooted<T>

Source§

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

Source§

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

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

impl From<MaybeRooted<AnyRef>> for Val

Source§

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

Converts to this type from the input type.
Source§

impl From<MaybeRooted<AnyRef>> for Ref

Source§

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

Converts to this type from the input type.
Source§

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

Source§

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

Converts to this type from the input type.
Source§

impl From<MaybeRooted<ArrayRef>> for Val

Source§

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

Converts to this type from the input type.
Source§

impl From<MaybeRooted<ArrayRef>> for Ref

Source§

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

Converts to this type from the input type.
Source§

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

Source§

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

Converts to this type from the input type.
Source§

impl From<MaybeRooted<EqRef>> for Val

Source§

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

Converts to this type from the input type.
Source§

impl From<MaybeRooted<EqRef>> for Ref

Source§

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

Converts to this type from the input type.
Source§

impl From<MaybeRooted<ExnRef>> for Val

Source§

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

Converts to this type from the input type.
Source§

impl From<MaybeRooted<ExnRef>> for Ref

Source§

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

Converts to this type from the input type.
Source§

impl From<MaybeRooted<ExternRef>> for Val

Source§

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

Converts to this type from the input type.
Source§

impl From<MaybeRooted<ExternRef>> for Ref

Source§

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

Converts to this type from the input type.
Source§

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

Source§

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

Converts to this type from the input type.
Source§

impl From<MaybeRooted<StructRef>> for Val

Source§

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

Converts to this type from the input type.
Source§

impl From<MaybeRooted<StructRef>> for Ref

Source§

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

Converts to this type from the input type.
Source§

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

Source§

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

Converts to this type from the input type.
Source§

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

Source§

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

Converts to this type from the input type.
Source§

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

Source§

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

Converts to this type from the input type.
Source§

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

Source§

fn from(r: Rooted<T>) -> 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<EqRef>> for MaybeRooted<AnyRef>

Source§

fn from(r: Unrooted<EqRef>) -> 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<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 MaybeRooted<T>

§

impl<T> Freeze for MaybeRooted<T>
where Rooted<T>: Freeze, Unrooted<T>: Freeze,

§

impl<T> Move for MaybeRooted<T>

§

impl<T> RefUnwindSafe for MaybeRooted<T>

§

impl<T> Send for MaybeRooted<T>
where Rooted<T>: Send, Unrooted<T>: Send,

§

impl<T> Sync for MaybeRooted<T>
where Rooted<T>: Sync, Unrooted<T>: Sync,

§

impl<T> Unpin for MaybeRooted<T>
where Rooted<T>: Unpin, Unrooted<T>: Unpin,

§

impl<T> UnsafeUnpin for MaybeRooted<T>

§

impl<T> UnwindSafe for MaybeRooted<T>

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.