pub struct OwnedRooted<T>where
T: GcRef,{ /* private fields */ }gc and runtime only.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 it is dropped.
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>
pub fn to_anyref(self) -> OwnedRooted<AnyRef>
Upcast this arrayref into an anyref.
Sourcepub fn to_eqref(self) -> OwnedRooted<EqRef>
pub fn to_eqref(self) -> OwnedRooted<EqRef>
Upcast this arrayref into an eqref.
Source§impl OwnedRooted<EqRef>
impl OwnedRooted<EqRef>
Sourcepub fn to_anyref(self) -> OwnedRooted<AnyRef>
pub fn to_anyref(self) -> OwnedRooted<AnyRef>
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>
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());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> reference to the same GC
object, which is valid until the store’s GC heap next changes.
Unlike rooting, this needs only shared access to the store.
§Errors
Returns an error if this reference is not associated with store’s
GC heap.
§Panics
Panics if this reference is associated with a different store.
Sourcepub fn to_all_owned_rooted(
store: impl AsContextMut,
refs: &[Unrooted<T>],
out: &mut Vec<OwnedRooted<T>>,
) -> Result<()>
pub fn to_all_owned_rooted( store: impl AsContextMut, refs: &[Unrooted<T>], out: &mut Vec<OwnedRooted<T>>, ) -> Result<()>
Root all of the given unrooted references until the returned handles are dropped, returning the handles in the same order.
Any single rooting operation, such as
Unrooted::to_rooted, changes
the store’s GC heap, and so invalidates every unrooted
reference into it, not just the one that was rooted. Rooting a
list of unrooted references one at a time therefore fails once
the second reference is rooted. This function solves that
use-case by providing a batched rooting operation.
See Rooted::to_all_rooted to root the references in the current
LIFO rooting scope instead.
§Errors
Returns an error, and roots nothing and leaves out unchanged, if any
of refs is no longer valid.
This function will return an OutOfMemory
error when memory allocation fails, in which case out is also left
unchanged. See the OutOfMemory type’s documentation for details on
Wasmtime’s out-of-memory handling.
§Panics
Panics if any of refs is associated with a different store.
Sourcepub fn ref_eq(
store: impl AsContext,
a: &impl RootedGcRef<T>,
b: &impl RootedGcRef<T>,
) -> Result<bool>
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)?);
}Sourcepub fn rooted_hash<H>(&self, state: &mut H)where
H: Hasher,
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.
Sourcepub fn ref_hash<H>(&self, store: impl AsContext, state: &mut H)where
H: Hasher,
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.
Source§impl OwnedRooted<StructRef>
impl OwnedRooted<StructRef>
Sourcepub fn to_anyref(self) -> OwnedRooted<AnyRef>
pub fn to_anyref(self) -> OwnedRooted<AnyRef>
Upcast this structref into an anyref.
Sourcepub fn to_eqref(self) -> OwnedRooted<EqRef>
pub fn to_eqref(self) -> OwnedRooted<EqRef>
Upcast this structref into an eqref.
Trait Implementations§
Source§impl<T: GcRef> Clone for OwnedRooted<T>
impl<T: GcRef> Clone for OwnedRooted<T>
Source§impl<T: GcRef> Debug for OwnedRooted<T>
impl<T: GcRef> Debug for OwnedRooted<T>
Source§impl<T: GcRef> Deref for OwnedRooted<T>
impl<T: GcRef> Deref for OwnedRooted<T>
Source§impl From<OwnedRooted<ArrayRef>> for OwnedRooted<AnyRef>
impl From<OwnedRooted<ArrayRef>> for OwnedRooted<AnyRef>
Source§fn from(s: OwnedRooted<ArrayRef>) -> Self
fn from(s: OwnedRooted<ArrayRef>) -> Self
Source§impl From<OwnedRooted<ArrayRef>> for OwnedRooted<EqRef>
impl From<OwnedRooted<ArrayRef>> for OwnedRooted<EqRef>
Source§fn from(s: OwnedRooted<ArrayRef>) -> Self
fn from(s: OwnedRooted<ArrayRef>) -> Self
Source§impl From<OwnedRooted<EqRef>> for OwnedRooted<AnyRef>
impl From<OwnedRooted<EqRef>> for OwnedRooted<AnyRef>
Source§fn from(e: OwnedRooted<EqRef>) -> Self
fn from(e: OwnedRooted<EqRef>) -> Self
Source§impl From<OwnedRooted<StructRef>> for OwnedRooted<AnyRef>
impl From<OwnedRooted<StructRef>> for OwnedRooted<AnyRef>
Source§fn from(s: OwnedRooted<StructRef>) -> Self
fn from(s: OwnedRooted<StructRef>) -> Self
Source§impl From<OwnedRooted<StructRef>> for OwnedRooted<EqRef>
impl From<OwnedRooted<StructRef>> for OwnedRooted<EqRef>
Source§fn from(s: OwnedRooted<StructRef>) -> Self
fn from(s: OwnedRooted<StructRef>) -> Self
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>
Auto Trait Implementations§
impl<T> Forget for OwnedRooted<T>
impl<T> Freeze for OwnedRooted<T>where
PhantomData<T>: Freeze,
impl<T> Move for OwnedRooted<T>
impl<T> RefUnwindSafe for OwnedRooted<T>where
PhantomData<T>: RefUnwindSafe,
impl<T> Send for OwnedRooted<T>where
PhantomData<T>: Send,
impl<T> Sync for OwnedRooted<T>where
PhantomData<T>: Sync,
impl<T> Unpin for OwnedRooted<T>where
PhantomData<T>: Unpin,
impl<T> UnsafeUnpin for OwnedRooted<T>where
PhantomData<T>: UnsafeUnpin,
impl<T> UnwindSafe for OwnedRooted<T>where
PhantomData<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, U> RootedGcRef<T> for U
§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