Struct GcWeak

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

Implementations

impl<'gc, T> GcWeak<'gc, T>

where T: 'gc + ?Sized,

pub fn upgrade(self, mc: &Mutation<'gc>) -> Option<Gc<'gc, T>>

pub fn is_dropped(self, _cc: &Collection) -> bool

During collection, return whether the value referenced by this GcWeak has already been dropped.

pub fn is_dead(self, fc: &Finalization<'gc>) -> bool

Returns true when a pointer is dead during finalization.

This is a weaker condition than being dropped, as the pointer may still be valid. Being dead means that there were no strong pointers pointing to this weak pointer that were found by the marking phase, and if it is not already dropped, it will be dropped as soon as collection resumes.

If the pointer is still valid, it may be resurrected using GcWeak::upgrade or GcWeak::resurrect`.

NOTE: This returns true if the pointer was destined to be collected at the start of the current finalization callback. Resurrecting one pointer can transitively resurrect others, and this method does not reflect this from within the same finalization call! If transitive resurrection is important, you may have to carefully call finalize multiple times for one collection cycle with marking stages in-between, and in the precise order that you want.

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

Manually marks a dead (but non-dropped) GcWeak as strongly reachable and keeps it alive.

This is similar to a write barrier in that it moves the collection phase back to Marking if it is not already there. All transitively held pointers from this will also be marked as reachable once marking resumes.

Returns the upgraded Gc pointer as a convenience. Whether or not the strong pointer is stored anywhere, the value and all transitively reachable values are still guaranteed to not be dropped this collection cycle.

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

Returns true if two GcWeaks 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(self) -> *const T

impl<'gc, T> GcWeak<'gc, T>

where T: 'gc,

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

where U: 'gc,

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) -> GcWeak<'gc, T>

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

SAFETY: The provided pointer must have been obtained from GcWeak::as_ptr or Gc::as_ptr, and the pointer must not have been fully collected yet (it may be a dropped but valid weak pointer).

Trait Implementations

impl<'gc, T> Clone for GcWeak<'gc, T>

where T: 'gc + ?Sized,

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'gc, T> Collect for GcWeak<'gc, T>

where T: 'gc + ?Sized,

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 for GcWeak<'gc, T>

where T: 'gc + ?Sized,

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

Formats the value using the given formatter.

impl<'gc, T> Copy for GcWeak<'gc, T>

where T: 'gc + ?Sized,