Struct wasmtime_runtime::VMGcRef

pub struct VMGcRef(/* private fields */);

A raw, unrooted GC reference.

A VMGcRef is either:

• A reference to some kind of object on the GC heap, but we don’t know exactly which kind without further reflection. Furthermore, this is not actually a pointer, but a compact index into a Wasm GC heap.

• An i31ref: it doesn’t actually reference an object in the GC heap, but is instead an inline, unboxed 31-bit integer.

VMGcRef and GC Barriers

Depending on the garbage collector in use, cloning, writing, and dropping a VMGcRef may require invoking GC barriers (little snippets of code provided by the collector to ensure it is correctly tracking all GC references).

Therefore, to encourage correct usage of GC barriers, this type does NOT implement Clone or Copy. Use GcStore::clone_gc_ref, GcStore::write_gc_ref, and GcStore::drop_gc_ref to clone, write, and drop VMGcRefs respectively.

As an escape hatch, if you really need to copy a VMGcRef without invoking GC barriers and you understand why that will not lead to GC bugs in this particular case, you can use the unchecked_copy method.

Implementations

impl VMGcRef

pub const ONLY_EXTERN_REF_AND_I31: bool = true

The only type of valid VMGcRef is currently VMExternRef.

Assert on this anywhere you are making that assumption, so that we know all the places to update when it no longer holds true.

pub const I31_REF_DISCRIMINANT: u32 = 1u32

If this bit is set on a GC reference, then the GC reference is actually an unboxed i31.

Must be kept in sync with wasmtime_cranelift::I31_REF_DISCRIMINANT.

pub fn from_raw_u32(raw: u32) -> Option<Self>

Create a new VMGcRef from the given raw u32 value.

Does not discriminate between indices into a GC heap and i31refs.

Returns None for zero values.

The given index should point to a valid GC-managed object within this reference’s associated heap. Failure to uphold this will be memory safe, but will lead to general failures such as panics or incorrect results.

pub fn from_heap_index(index: NonZeroU32) -> Option<Self>

Create a new VMGcRef from the given index into a GC heap.

The given index should point to a valid GC-managed object within this reference’s associated heap. Failure to uphold this will be memory safe, but will lead to general failures such as panics or incorrect results.

Returns None when the index is not 2-byte aligned and therefore conflicts with the i31ref discriminant.

pub fn from_raw_non_zero_u32(raw: NonZeroU32) -> Self

Create a new VMGcRef from the given raw value.

Does not discriminate between indices into a GC heap and i31refs.

pub fn from_i31(val: I31) -> Self

Construct a new VMGcRef from an unboxed 31-bit integer.

pub fn from_r64(raw: u64) -> Result<Option<Self>>

Create a new VMGcRef from a raw r64 value from Cranelift.

Returns an error if raw cannot be losslessly converted from a u64 into a u32.

Returns Ok(None) if raw is zero (aka a “null” VMGcRef).

This method only exists because we can’t currently use Cranelift’s r32 type on 64-bit platforms. We should instead have a from_r32 method.

pub fn unchecked_copy(&self) -> Self

Copy this VMGcRef without running the GC’s clone barriers.

Prefer calling clone(&mut GcStore) instead! This is mostly an internal escape hatch for collector implementations.

Failure to run GC barriers when they would otherwise be necessary can lead to leaks, panics, and wrong results. It cannot lead to memory unsafety, however.

pub fn as_heap_index(&self) -> Option<NonZeroU32>

Get this GC reference as a u32 index into its GC heap.

Returns None for i31refs.

pub fn as_raw_u32(&self) -> u32

Get this GC refererence as a raw u32 value, regardless whether it is actually a reference to a GC object or is an i31ref.

pub fn into_r64(self) -> u64

Get this GC reference as a raw r64 value for passing to Cranelift.

This method only exists because we can’t currently use Cranelift’s r32 type on 64-bit platforms. We should instead be able to pass VMGcRef into compiled code directly.

pub fn as_r64(&self) -> u64

Get this GC reference as a raw r64 value for passing to Cranelift.

This method only exists because we can’t currently use Cranelift’s r32 type on 64-bit platforms. We should instead be able to pass VMGcRef into compiled code directly.

pub fn into_typed<T>(self, gc_heap: &impl GcHeap) -> Result<TypedGcRef<T>, Self>

where T: GcHeapObject,

Creates a typed GC reference from self, checking that self actually is a T.

If this is not a GC reference to a T, then Err(self) is returned.

pub fn into_typed_unchecked<T>(self) -> TypedGcRef<T>

where T: GcHeapObject,

Creates a typed GC reference without actually checking that self is a T.

self should point to a T object. Failure to uphold this invariant is memory safe, but will lead to general incorrectness such as panics or wrong results.

pub fn as_typed<T>(&self, gc_heap: &impl GcHeap) -> Option<&TypedGcRef<T>>

where T: GcHeapObject,

Borrow self as a typed GC reference, checking that self actually is a T.

pub fn as_typed_unchecked<T>(&self) -> &TypedGcRef<T>

where T: GcHeapObject,

Creates a typed GC reference without actually checking that self is a T.

self should point to a T object. Failure to uphold this invariant is memory safe, but will lead to general incorrectness such as panics or wrong results.

pub fn gc_header<'a>(&self, gc_heap: &'a dyn GcHeap) -> Option<&'a VMGcHeader>

Get a reference to the GC header that this GC reference is pointing to.

Returns None when this is an i31ref and doesn’t actually point to a GC header.

pub fn is_i31(&self) -> bool

Is this VMGcRef actually an unboxed 31-bit integer, and not actually a GC reference?

pub fn as_i31(&self) -> Option<I31>

Get the underlying i31, if any.

pub fn unwrap_i31(&self) -> I31

Get the underlying i31, panicking if this is not an i31.

pub fn is_extern_ref(&self) -> bool

Is this VMGcRef a VMExternRef?

Trait Implementations

impl Debug for VMGcRef

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

Formats the value using the given formatter.

impl<T> From<TypedGcRef<T>> for VMGcRef

fn from(value: TypedGcRef<T>) -> Self

Converts to this type from the input type.

impl From<VMGcRef> for TableElement

fn from(x: VMGcRef) -> TableElement

Converts to this type from the input type.

impl Hash for VMGcRef

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl LowerHex for VMGcRef

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

Formats the value using the given formatter.

impl PartialEq for VMGcRef

fn eq(&self, other: &VMGcRef) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Pointer for VMGcRef

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

Formats the value using the given formatter.

impl UpperHex for VMGcRef

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

Formats the value using the given formatter.

impl Eq for VMGcRef

impl StructuralPartialEq for VMGcRef