Struct zerogc::Gc

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

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.

Implementations

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

pub unsafe fn from_raw(id: 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 collector corresponding to the id.

pub 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 create_handle<'a>(
    &self
) -> <Id::System as GcHandleSystem<'gc, 'a, T>>::Handle where
    Id::System: GcHandleSystem<'gc, 'a, T>,
    T: GcErase<'a, Id> + 'a,
    <T as GcErase<'a, Id>>::Erased: GcSafe + 'a, 

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

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'.

pub fn collector_id(&self) -> Id

Get a copy of the collector's id

The underlying collector it points to is not necessarily always valid

Trait Implementations

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

pub fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

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

Formats the value using the given formatter.

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

type Target = &'gc T

The resulting type after dereferencing.

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

Dereferences the value.

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

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

pub 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, 'a, T, Id> GcErase<'a, Id> for Gc<'gc, T, Id> where
    T: GcSafe + GcErase<'a, Id>,
    <T as GcErase<'a, Id>>::Erased: GcSafe,
    Id: CollectorId, 

type Erased = Gc<'a, <T as GcErase<'a, Id>>::Erased, Id>

This type with all garbage collected lifetimes changed to 'static (or erased)

impl<'gc, 'new_gc, T, Id> GcRebrand<'new_gc, Id> for Gc<'gc, T, Id> where
    T: GcSafe + GcRebrand<'new_gc, Id>,
    <T as GcRebrand<'new_gc, Id>>::Branded: GcSafe,
    Id: CollectorId, 

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: GcSafe + 'gc, Id: CollectorId> GcSafe for Gc<'gc, T, Id>

Double-indirection is completely safe

pub const NEEDS_DROP: bool

If this type needs a destructor run

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

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

Feeds this value into the given Hasher.

pub 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 + PartialEq + 'gc, Id: CollectorId> PartialEq<Gc<'gc, T, Id>> for Gc<'gc, T, Id>

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

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

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

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

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

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

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'gc, T: ?Sized, Id> Send for Gc<'gc, T, Id> where
    T: GcSafe + 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: ?Sized, Id> Sync for Gc<'gc, T, Id> where
    T: GcSafe + 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 implenentation should be as well.

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

pub const NEEDS_TRACE: bool

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

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

Visit each field in this type