Struct OwnedRooted

pub struct OwnedRooted<T>
where
    T: GcRef,
{ /* private fields */ }

Available on crate features gc and runtime only.

A rooted reference to a garbage-collected T with automatic lifetime.

An OwnedRooted<T> is a strong handle to a garbage-collected T, preventing its referent (and anything else transitively referenced) from being collected by the GC until [unroot][crate::OwnedRooted::unroot] is explicitly called.

An OwnedRooted<T> keeps its rooted GC object alive at least until the OwnedRooted<T> itself is dropped. The “de-registration” of the root is automatic and is triggered (in a deferred way) by the drop of this type.

The primary way to create an OwnedRooted<T> is to promote a temporary Rooted<T> into an OwnedRooted<T> via its to_owned_rooted method.

OwnedRooted<T> dereferences to its underlying T, allowing you to call T’s methods.

Example

let mut store = Store::<Option<OwnedRooted<ExternRef>>>::default();

// Create our `OwnedRooted` in a nested scope to avoid rooting it for
// the duration of the store's lifetime.
let x = {
    let mut scope = RootScope::new(&mut store);
    let x = ExternRef::new(&mut scope, 1234)?;
    x.to_owned_rooted(&mut scope)?
};

// Place `x` into our store.
*store.data_mut() = Some(x);

// Do a bunch stuff that may or may not access, replace, or take `x`...

Implementations

impl OwnedRooted<ArrayRef>

pub fn to_anyref(self) -> OwnedRooted<AnyRef>

Upcast this arrayref into an anyref.

pub fn to_eqref(self) -> OwnedRooted<EqRef>

Upcast this arrayref into an eqref.

impl OwnedRooted<EqRef>

pub fn to_anyref(self) -> OwnedRooted<AnyRef>

Upcast this eqref into an anyref.

impl<T> OwnedRooted<T>

where T: GcRef,

pub fn to_rooted(&self, context: impl AsContextMut) -> Rooted<T>

Clone this OwnedRooted<T> into a Rooted<T>.

This operation does not consume or unroot this OwnedRooted<T>.

The underlying GC object is re-rooted in the given context’s scope. The resulting Rooted<T> is only valid during the given context’s scope. See the Rooted<T> documentation for more details on rooting scopes.

This operation does not consume or unroot this OwnedRooted<T>.

Panics

Panics if this object is not associated with the given context’s store.

Example

let mut store = Store::<()>::default();

let root1: Rooted<_>;

let owned = {
    let mut scope = RootScope::new(&mut store);
    root1 = ExternRef::new(&mut scope, 1234)?;
    root1.to_owned_rooted(&mut scope)?
};

// `root1` is no longer accessible because it was unrooted when `scope`
// was dropped.
assert!(root1.data(&store).is_err());

// But we can re-root `owned` into this scope.
let root2 = owned.to_rooted(&mut store);
assert!(root2.data(&store).is_ok());

pub fn ref_eq( store: impl AsContext, a: &impl RootedGcRef<T>, b: &impl RootedGcRef<T>, ) -> Result<bool>

Are these two GC roots referencing the same underlying GC object?

This function will return true even when a and b are different GC roots (for example because they were rooted in different scopes) if they are rooting the same underlying GC object.

Because this method takes any impl RootedGcRef<T> arguments, it can be used to compare, for example, a Rooted<T> and an OwnedRooted<T>.

Panics

Panics if either a or b is not associated with the given store.

Example

let mut store = Store::<()>::default();

let a;
let b;
let x;

{
    let mut scope = RootScope::new(&mut store);

    a = ExternRef::new(&mut scope, "hello")?.to_owned_rooted(&mut scope)?;
    b = a.clone();

    // `a` and `b` are rooting the same object.
    assert!(OwnedRooted::ref_eq(&scope, &a, &b)?);

    // `c` is a different GC root, is in a different scope, and is a
    // `Rooted<T>` instead of a `OwnedRooted<T>`, but is still rooting
    // the same object.
    let c = a.to_rooted(&mut scope);
    assert!(OwnedRooted::ref_eq(&scope, &a, &c)?);

    x = ExternRef::new(&mut scope, "goodbye")?.to_owned_rooted(&mut scope)?;

    // `a` and `x` are rooting different objects.
    assert!(!OwnedRooted::ref_eq(&scope, &a, &x)?);
}

pub fn rooted_hash<H>(&self, state: &mut H)

where H: Hasher,

Hash this root.

Note that, similar to Rooted::rooted_eq, this only operates on the root and not the underlying GC reference. That means that two different rootings of the same object will hash to different values (modulo hash collisions). If this is undesirable, use the ref_hash method instead.

pub fn ref_hash<H>(&self, store: impl AsContext, state: &mut H)

where H: Hasher,

Hash the underlying rooted object reference.

Note that, similar to Rooted::ref_eq, and operates on the underlying rooted GC object reference, not the root. That means that two different rootings of the same object will hash to the same value. If this is undesirable, use the rooted_hash method instead.

impl OwnedRooted<StructRef>

pub fn to_anyref(self) -> OwnedRooted<AnyRef>

Upcast this structref into an anyref.

pub fn to_eqref(self) -> OwnedRooted<EqRef>

Upcast this structref into an eqref.

Trait Implementations

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

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

impl<T: GcRef> Deref for OwnedRooted<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl From<OwnedRooted<ArrayRef>> for OwnedRooted<AnyRef>

fn from(s: OwnedRooted<ArrayRef>) -> Self

Converts to this type from the input type.

impl From<OwnedRooted<ArrayRef>> for OwnedRooted<EqRef>

fn from(s: OwnedRooted<ArrayRef>) -> Self

Converts to this type from the input type.

impl From<OwnedRooted<EqRef>> for OwnedRooted<AnyRef>

fn from(e: OwnedRooted<EqRef>) -> Self

Converts to this type from the input type.

impl From<OwnedRooted<StructRef>> for OwnedRooted<AnyRef>

fn from(s: OwnedRooted<StructRef>) -> Self

Converts to this type from the input type.

impl From<OwnedRooted<StructRef>> for OwnedRooted<EqRef>

fn from(s: OwnedRooted<StructRef>) -> Self

Converts to this type from the input type.

impl WasmTy for OwnedRooted<AnyRef>

impl WasmTy for OwnedRooted<ArrayRef>

impl WasmTy for OwnedRooted<EqRef>

impl WasmTy for OwnedRooted<ExnRef>

impl WasmTy for OwnedRooted<ExternRef>

impl WasmTy for OwnedRooted<StructRef>