Trait zerogc::GcRef

pub unsafe trait GcRef<'gc, T: GcSafe + ?Sized + 'gc>: Copy + GcSafe + Deref<Target = &'gc T> {
    type Id: CollectorId;
    fn collector_id(&self) -> Self::Id;
    unsafe fn from_raw(id: Self::Id, value: NonNull<T>) -> Self;
    fn value(&self) -> &'gc T;
    unsafe fn as_raw_ptr(&self) -> *mut T;
    fn system(&self) -> &<Self::Id as CollectorId>::System;

    fn create_handle<'a>(
        &self
    ) -> <<Self::Id as CollectorId>::System as GcHandleSystem<'gc, 'a, T>>::Handle
    where
        <Self::Id as CollectorId>::System: GcHandleSystem<'gc, 'a, T>,
        <Self::Id as CollectorId>::System: GcHandleSystem<'gc, 'a, T, Gc = Self>,
        T: GcErase<'a, Self::Id> + 'a,
        <T as GcErase<'a, Self::Id>>::Erased: GcSafe + 'a,
    { ... }
}

A garbage collected pointer to a value.

This is the equivalent of a garbage collected smart-pointer. It’s so smart, you can even coerce it to a reference bound to the lifetime of the GarbageCollectorRef. However, all those references are invalidated by the borrow checker as soon as your reference to the collector reaches a safepoint. The objects can only survive garbage collection if they live in this smart-pointer.

The smart pointer is simply a guarantee to the garbage collector that this points to a garbage collected object with the correct header, and not some arbitrary bits that you’ve decided to heap allocate.

Generally this trait isn’t what you’re looking for. Each collector should have a separate implementation of this type.

Safety

The collector relies upon correct implementation of this trait for memory safety. Just like Trace and GcRef, incorrect implementation is undefined behavior.

In particular, this must always dereference to the same object, although it may move during collections for copying collectors.

Associated Types

type Id: CollectorId

The type of the collector’s id

Singleton collectors have a zero-sized id. However, some types of collectors may have multiple active instances and require an id to disambiguate between them.

Required methods

fn collector_id(&self) -> Self::Id

The collector’s uniquely identification.

Ensure we aren’t modifying another collector’s pointers

unsafe fn from_raw(id: Self::Id, value: NonNull<T>) -> Self

Create a GC pointer from a raw ID/pointer pair

Safety

Undefined behavior if the underlying pointer is not valid and associated with the specified collector id.

Collectors may add their own additional invariants that callers need to maintain.

fn value(&self) -> &'gc T

The value of the underlying pointer

Guaranteed to live until the next garbage collection.

unsafe fn as_raw_ptr(&self) -> *mut T

Cast this reference to a raw pointer

Safety

It’s undefined behavior to mutate the value. The pointer is only valid as long as the underlying reference is.

fn system(&self) -> &<Self::Id as CollectorId>::System

Get a reference to the system

Safety

This is based on the assumption that a GcSystem must outlive all of the pointers it owns. Although it could be restricted to the lifetime of the CollectorId (in theory that may have an internal pointer) it will still live for ‘&self’.

Provided methods

fn create_handle<'a>(
    &self
) -> <<Self::Id as CollectorId>::System as GcHandleSystem<'gc, 'a, T>>::Handle where
    <Self::Id as CollectorId>::System: GcHandleSystem<'gc, 'a, T>,
    <Self::Id as CollectorId>::System: GcHandleSystem<'gc, 'a, T, Gc = Self>,
    T: GcErase<'a, Self::Id> + 'a,
    <T as GcErase<'a, Self::Id>>::Erased: GcSafe + 'a, 

Create a handle to this object, which can be used without a context

Implementors

impl<'gc, T: GcSafe + 'gc> GcRef<'gc, T> for DummyGc<'gc, T>

type Id = DummyCollectorId

fn collector_id(&self) -> Self::Id

unsafe fn from_raw(id: DummyCollectorId, ptr: NonNull<T>) -> Self

fn value(&self) -> &'gc T

unsafe fn as_raw_ptr(&self) -> *mut T

fn system(&self) -> &<Self::Id as CollectorId>::System