Struct gc_arena::Gc

pub struct Gc<'gc, T: ?Sized + 'gc> { /* private fields */ }

A garbage collected pointer to a type T. Implements Copy, and is implemented as a plain machine pointer. You can only allocate Gc pointers through a &Mutation<'gc> inside an arena type, and through “generativity” such Gc pointers may not escape the arena they were born in or be stored inside TLS. This, combined with correct Collect implementations, means that Gc pointers will never be dangling and are always safe to access.

Implementations

impl<'gc, T: Collect + 'gc> Gc<'gc, T>

pub fn new(mc: &Mutation<'gc>, t: T) -> Gc<'gc, T>

impl<'gc, T: 'gc> Gc<'gc, T>

pub unsafe fn cast<U: 'gc>(this: Gc<'gc, T>) -> Gc<'gc, U>

Cast the internal pointer to a different type.

SAFETY: It must be valid to dereference a *mut U that has come from casting a *mut T.

pub unsafe fn from_ptr(ptr: *const T) -> Gc<'gc, T>

Retrieve a Gc from a raw pointer obtained from Gc::as_ptr

SAFETY: The provided pointer must have been obtained from Gc::as_ptr, and the pointer must not have been collected yet.

impl<'gc, T: Unlock + ?Sized + 'gc> Gc<'gc, T>

pub fn unlock(self, mc: &Mutation<'gc>) -> &'gc T::Unlocked

Shorthand for Gc::write(mc, self).unlock().

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

pub fn as_ref(self: Gc<'gc, T>) -> &'gc T

Obtains a long-lived reference to the contents of this Gc.

Unlike AsRef or Deref, the returned reference isn’t bound to the Gc itself, and will stay valid for the entirety of the current arena callback.

pub fn downgrade(this: Gc<'gc, T>) -> GcWeak<'gc, T>

pub fn write(mc: &Mutation<'gc>, gc: Self) -> &'gc Write<T>

Triggers a write barrier on this Gc, allowing for further safe mutation.

pub fn ptr_eq(this: Gc<'gc, T>, other: Gc<'gc, T>) -> bool

Returns true if two Gcs point to the same allocation.

Similarly to Rc::ptr_eq and Arc::ptr_eq, this function ignores the metadata of dyn pointers.

pub fn as_ptr(gc: Gc<'gc, T>) -> *const T

pub fn is_dead(_: &Finalization<'gc>, gc: Gc<'gc, T>) -> bool

Returns true when a pointer is dead during finalization. This is equivalent to GcWeak::is_dead for strong pointers.

Any strong pointer reachable from the root will never be dead, BUT there can be strong pointers reachable only through other weak pointers that can be dead.

pub fn resurrect(fc: &Finalization<'gc>, gc: Gc<'gc, T>)

Manually marks a dead Gc pointer as reachable and keeps it alive.

Equivalent to GcWeak::resurrect for strong pointers. Manually marks this pointer and all transitively held pointers as reachable, thus keeping them from being dropped this collection cycle.

impl<'gc, T: Copy + 'gc> Gc<'gc, Lock<T>>

pub fn get(self) -> T

pub fn set(self, mc: &Mutation<'gc>, t: T)

impl<'gc, T: ?Sized + 'gc> Gc<'gc, RefLock<T>>

pub fn borrow(self) -> Ref<'gc, T>

pub fn try_borrow(self) -> Result<Ref<'gc, T>, BorrowError>

pub fn borrow_mut(self, mc: &Mutation<'gc>) -> RefMut<'gc, T>

pub fn try_borrow_mut( self, mc: &Mutation<'gc> ) -> Result<RefMut<'gc, T>, BorrowMutError>

Trait Implementations

impl<'gc, T: ?Sized + 'gc> AsRef<T> for Gc<'gc, T>

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

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

fn clone(&self) -> Gc<'gc, T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'gc, T: ?Sized + 'gc> Collect for Gc<'gc, T>

fn trace(&self, cc: &Collection)

Must call Collect::trace on all held Gc pointers. If this type holds inner types that implement Collect, a valid implementation would simply call Collect::trace on all the held values to ensure this.

fn needs_trace() -> bool

where Self: Sized,

As an optimization, if this type can never hold a Gc pointer and trace is unnecessary to call, you may implement this method and return false. The default implementation returns true, signaling that Collect::trace must be called.

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

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

Formats the value using the given formatter.

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

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

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

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

Formats the value using the given formatter.

impl<'gc, T: Hash + ?Sized + 'gc> Hash for Gc<'gc, T>

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<'gc, T: Ord + ?Sized + 'gc> Ord for Gc<'gc, T>

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

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

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

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl<'gc, T: PartialEq + ?Sized + 'gc> PartialEq for Gc<'gc, T>

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: &Self) -> bool

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

impl<'gc, T: PartialOrd + ?Sized + 'gc> PartialOrd for Gc<'gc, T>

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

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

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

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

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

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

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

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

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

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

impl<'gc, T: ?Sized + 'gc> Pointer for Gc<'gc, T>

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

Formats the value using the given formatter.

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

impl<'gc, T: Eq + ?Sized + 'gc> Eq for Gc<'gc, T>