Struct zerogc::Gc

#[repr(transparent)]
pub struct Gc<'gc, T: ?Sized, Id: CollectorId> { /* private fields */ }

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.

Safety

A Gc can be safely transmuted back and forth from its corresponding pointer.

Unsafe code can rely on a pointer always dereferencing to the same value in between safepoints. This is true even for copying/moving collectors.

Lifetime

The borrow does not refer to the value &'gc T. Instead, it refers to the context &'gc Id::Context

This is necessary because T may have borrowed interior data with a shorter lifetime 'a < 'gc, making &'gc T invalid (because that would imply ’gc: ’a, which is false).

This ownership can be thought of in terms of the following (simpler) system.

struct GcContext {
    values: Vec<Box<dyn GcSafe>>
}
struct Gc<'gc, T: GcSafe> {
    index: usize,
    marker: PhantomData<T>,
    ctx: &'gc GcContext
}

In this system, safepoints can be thought of mutations that remove dead values from the Vec.

This ownership equivalency is also the justification for why the 'gc lifetime can be covariant

The only difference is that the real Gc structure uses pointers instead of indices.

Implementations

impl<'gc, T: GcSafe<'gc, Id> + ?Sized, Id: CollectorId> Gc<'gc, T, Id>

pub unsafe fn from_raw(value: NonNull<T>) -> Self

Create a GC pointer from a raw pointer

Safety

Undefined behavior if the underlying pointer is not valid and doesn’t correspond to the appropriate id.

pub fn create_handle(&self) -> Id::Handle where
    Id: HandleCollectorId,
    T: GcRebrand<'static, Id>, 

Create a GcHandle referencing this object, allowing it to be used without a context and referenced across safepoints.

Requires that the collector supports handles

pub fn system(&self) -> &Id::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’.

impl<'gc, T: ?Sized, Id: CollectorId> Gc<'gc, T, Id>

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

The value of the underlying pointer

pub 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 reference is.

pub fn collector_id(&self) -> &Id

Get a reference to the collector’s id

The underlying collector it points to is not necessarily always valid

Trait Implementations

impl<'gc, T: ?Sized, Id: CollectorId> Clone for Gc<'gc, T, Id>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'gc, T: ?Sized + GcSafe<'gc, Id> + Debug, Id: CollectorId> Debug for Gc<'gc, T, Id>

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

Formats the value using the given formatter.

impl<'gc, T: GcSafe<'gc, Id> + ?Sized, Id: CollectorId> Deref for Gc<'gc, T, Id>

type Target = T

The resulting type after dereferencing.

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

Dereferences the value.

impl<'gc, T: ?Sized + GcSafe<'gc, Id> + Display, Id: CollectorId> Display for Gc<'gc, T, Id>

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

Formats the value using the given formatter.

impl<'gc, O, V, Id> GcDirectBarrier<'gc, Gc<'gc, O, Id>> for Gc<'gc, V, Id> where
    O: GcSafe<'gc, Id> + 'gc,
    V: GcSafe<'gc, Id> + 'gc,
    Id: CollectorId, 

unsafe fn write_barrier(&self, owner: &Gc<'gc, O, Id>, field_offset: usize)

Trigger a write barrier, before writing to one of the owning object’s managed fields

impl<'gc, 'new_gc, T, Id> GcRebrand<'new_gc, Id> for Gc<'gc, T, Id> where
    T: GcSafe<'gc, Id> + ?Sized + GcRebrand<'new_gc, Id>,
    Id: CollectorId,
    Self: Trace, 

Rebrand

type Branded = Gc<'new_gc, <T as GcRebrand<'new_gc, Id>>::Branded, Id>

This type with all garbage collected lifetimes changed to 'new_gc

impl<'gc, T: ?Sized + GcSafe<'gc, Id>, Id: CollectorId> GcSafe<'gc, Id> for Gc<'gc, T, Id>

unsafe fn trace_inside_gc<V>(
    gc: &mut Gc<'gc, Self, Id>,
    visitor: &mut V
) -> Result<(), V::Err> where
    V: GcVisitor, 

Trace this object behind a Gc pointer.

impl<'gc, T: GcSafe<'gc, Id> + Hash, Id: CollectorId> Hash for Gc<'gc, T, Id>

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, 

Feeds a slice of this type into the given Hasher.

impl<'gc, T: GcSafe<'gc, Id> + Ord, Id: CollectorId> Ord for Gc<'gc, T, Id>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<'gc, T: GcSafe<'gc, Id> + PartialEq, Id: CollectorId> PartialEq<Gc<'gc, T, Id>> for Gc<'gc, T, Id>

fn eq(&self, other: &Self) -> 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 !=.

impl<'gc, T: GcSafe<'gc, Id> + PartialEq, Id: CollectorId> PartialEq<T> for Gc<'gc, T, Id>

fn eq(&self, other: &T) -> 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 !=.

impl<'gc, T: GcSafe<'gc, Id> + PartialOrd, Id: CollectorId> PartialOrd<Gc<'gc, T, Id>> for Gc<'gc, T, Id>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'gc, T: GcSafe<'gc, Id> + PartialOrd, Id: CollectorId> PartialOrd<T> for Gc<'gc, T, Id>

fn partial_cmp(&self, other: &T) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'gc, T: ?Sized + GcSafe<'gc, Id>, Id: CollectorId> Trace for Gc<'gc, T, Id>

const NEEDS_TRACE: bool

Whether this type needs to be traced by the garbage collector.

const NEEDS_DROP: bool

If this type needs a destructor run.

fn trace<V: GcVisitor>(&mut self, visitor: &mut V) -> Result<(), V::Err>

Trace each field in this type.

impl<'gc, T, U, Id> CoerceUnsized<Gc<'gc, U, Id>> for Gc<'gc, T, Id> where
    T: ?Sized + GcSafe<'gc, Id> + Unsize<U>,
    U: ?Sized + GcSafe<'gc, Id>,
    Id: CollectorId, 

impl<'gc, T: ?Sized, Id: CollectorId> Copy for Gc<'gc, T, Id>

impl<'gc, T: GcSafe<'gc, Id> + Eq, Id: CollectorId> Eq for Gc<'gc, T, Id>

impl<'gc, T, Id> Send for Gc<'gc, T, Id> where
    T: GcSafe<'gc, Id> + ?Sized + Sync,
    Id: CollectorId + Sync, 

In order to send references between threads, the underlying type must be sync.

This is the same reason that Arc<T>: Send requires T: Sync

impl<'gc, T, Id> Sync for Gc<'gc, T, Id> where
    T: GcSafe<'gc, Id> + ?Sized + Sync,
    Id: CollectorId + Sync, 

If the underlying type is Sync, it’s safe to share garbage collected references between threads.

The safety of the collector itself depends on whether CollectorId is Sync. If it is, the whole garbage collection implementation should be as well.

impl<'gc, T: ?Sized + GcSafe<'gc, Id>, Id: CollectorId> TrustedDrop for Gc<'gc, T, Id>

Double-indirection is completely safe