pub struct OwnedRooted<T>where
T: GcRef,{ /* private fields */ }
Expand description
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§
Source§impl OwnedRooted<ArrayRef>
impl OwnedRooted<ArrayRef>
Sourcepub fn to_anyref(self) -> OwnedRooted<AnyRef>
Available on crate features runtime
and gc
only.
pub fn to_anyref(self) -> OwnedRooted<AnyRef>
runtime
and gc
only.Upcast this arrayref
into an anyref
.
Sourcepub fn to_eqref(self) -> OwnedRooted<EqRef>
Available on crate features runtime
and gc
only.
pub fn to_eqref(self) -> OwnedRooted<EqRef>
runtime
and gc
only.Upcast this arrayref
into an eqref
.
Source§impl OwnedRooted<EqRef>
impl OwnedRooted<EqRef>
Sourcepub fn to_anyref(self) -> OwnedRooted<AnyRef>
Available on crate features runtime
and gc
only.
pub fn to_anyref(self) -> OwnedRooted<AnyRef>
runtime
and gc
only.Upcast this eqref
into an anyref
.
Source§impl<T> OwnedRooted<T>where
T: GcRef,
impl<T> OwnedRooted<T>where
T: GcRef,
Sourcepub fn to_rooted(&self, context: impl AsContextMut) -> Rooted<T>
Available on crate features runtime
and gc
only.
pub fn to_rooted(&self, context: impl AsContextMut) -> Rooted<T>
runtime
and gc
only.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());
Sourcepub fn ref_eq(
store: impl AsContext,
a: &impl RootedGcRef<T>,
b: &impl RootedGcRef<T>,
) -> Result<bool>
Available on crate features runtime
and gc
only.
pub fn ref_eq( store: impl AsContext, a: &impl RootedGcRef<T>, b: &impl RootedGcRef<T>, ) -> Result<bool>
runtime
and gc
only.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)?);
}
Sourcepub fn rooted_hash<H>(&self, state: &mut H)where
H: Hasher,
Available on crate features runtime
and gc
only.
pub fn rooted_hash<H>(&self, state: &mut H)where
H: Hasher,
runtime
and gc
only.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.
Sourcepub fn ref_hash<H>(&self, store: impl AsContext, state: &mut H)where
H: Hasher,
Available on crate features runtime
and gc
only.
pub fn ref_hash<H>(&self, store: impl AsContext, state: &mut H)where
H: Hasher,
runtime
and gc
only.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.
Source§impl OwnedRooted<StructRef>
impl OwnedRooted<StructRef>
Sourcepub fn to_anyref(self) -> OwnedRooted<AnyRef>
Available on crate features runtime
and gc
only.
pub fn to_anyref(self) -> OwnedRooted<AnyRef>
runtime
and gc
only.Upcast this structref
into an anyref
.
Sourcepub fn to_eqref(self) -> OwnedRooted<EqRef>
Available on crate features runtime
and gc
only.
pub fn to_eqref(self) -> OwnedRooted<EqRef>
runtime
and gc
only.Upcast this structref
into an eqref
.
Trait Implementations§
Source§impl<T: GcRef> Clone for OwnedRooted<T>
Available on crate features gc
and runtime
only.
impl<T: GcRef> Clone for OwnedRooted<T>
gc
and runtime
only.Source§impl<T: GcRef> Debug for OwnedRooted<T>
Available on crate features gc
and runtime
only.
impl<T: GcRef> Debug for OwnedRooted<T>
gc
and runtime
only.Source§impl<T: GcRef> Deref for OwnedRooted<T>
Available on crate features gc
and runtime
only.
impl<T: GcRef> Deref for OwnedRooted<T>
gc
and runtime
only.Source§impl From<OwnedRooted<ArrayRef>> for OwnedRooted<AnyRef>
Available on crate features gc
and runtime
only.
impl From<OwnedRooted<ArrayRef>> for OwnedRooted<AnyRef>
gc
and runtime
only.Source§fn from(s: OwnedRooted<ArrayRef>) -> Self
fn from(s: OwnedRooted<ArrayRef>) -> Self
Source§impl From<OwnedRooted<ArrayRef>> for OwnedRooted<EqRef>
Available on crate features gc
and runtime
only.
impl From<OwnedRooted<ArrayRef>> for OwnedRooted<EqRef>
gc
and runtime
only.Source§fn from(s: OwnedRooted<ArrayRef>) -> Self
fn from(s: OwnedRooted<ArrayRef>) -> Self
Source§impl From<OwnedRooted<EqRef>> for OwnedRooted<AnyRef>
Available on crate features gc
and runtime
only.
impl From<OwnedRooted<EqRef>> for OwnedRooted<AnyRef>
gc
and runtime
only.Source§fn from(e: OwnedRooted<EqRef>) -> Self
fn from(e: OwnedRooted<EqRef>) -> Self
Source§impl From<OwnedRooted<StructRef>> for OwnedRooted<AnyRef>
Available on crate features gc
and runtime
only.
impl From<OwnedRooted<StructRef>> for OwnedRooted<AnyRef>
gc
and runtime
only.Source§fn from(s: OwnedRooted<StructRef>) -> Self
fn from(s: OwnedRooted<StructRef>) -> Self
Source§impl From<OwnedRooted<StructRef>> for OwnedRooted<EqRef>
Available on crate features gc
and runtime
only.
impl From<OwnedRooted<StructRef>> for OwnedRooted<EqRef>
gc
and runtime
only.Source§fn from(s: OwnedRooted<StructRef>) -> Self
fn from(s: OwnedRooted<StructRef>) -> Self
impl WasmTy for OwnedRooted<AnyRef>
gc
and runtime
only.impl WasmTy for OwnedRooted<ArrayRef>
gc
and runtime
only.impl WasmTy for OwnedRooted<EqRef>
gc
and runtime
only.impl WasmTy for OwnedRooted<ExnRef>
gc
and runtime
only.impl WasmTy for OwnedRooted<ExternRef>
gc
and runtime
only.impl WasmTy for OwnedRooted<StructRef>
gc
and runtime
only.Auto Trait Implementations§
impl<T> Freeze for OwnedRooted<T>
impl<T> RefUnwindSafe for OwnedRooted<T>where
T: RefUnwindSafe,
impl<T> Send for OwnedRooted<T>where
T: Send,
impl<T> Sync for OwnedRooted<T>where
T: Sync,
impl<T> Unpin for OwnedRooted<T>where
T: Unpin,
impl<T> UnwindSafe for OwnedRooted<T>where
T: UnwindSafe,
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§impl<T> Pointable for T
impl<T> Pointable for T
§impl<T> Source for T
impl<T> Source for T
§type Slice<'a> = <<T as Deref>::Target as Source>::Slice<'a>
where
T: 'a
type Slice<'a> = <<T as Deref>::Target as Source>::Slice<'a> where T: 'a
Source
can be sliced into.§fn read<'a, Chunk>(&'a self, offset: usize) -> Option<Chunk>where
Chunk: Chunk<'a>,
fn read<'a, Chunk>(&'a self, offset: usize) -> Option<Chunk>where
Chunk: Chunk<'a>,
None
when reading
out of bounds would occur. Read more§fn slice(&self, range: Range<usize>) -> Option<<T as Source>::Slice<'_>>
fn slice(&self, range: Range<usize>) -> Option<<T as Source>::Slice<'_>>
slice::get(range)
. Read more§fn is_boundary(&self, index: usize) -> bool
fn is_boundary(&self, index: usize) -> bool
§fn find_boundary(&self, index: usize) -> usize
fn find_boundary(&self, index: usize) -> usize
&str
sources attempts to find the closest char
boundary at which source
can be sliced, starting from index
. Read more