Struct tracing_rc::rc::Gc

pub struct Gc<T: Traceable + 'static> { /* fields omitted */ }

A cycle-collected reference-counted smart pointer. Gc<T> provides shared ownership of a value of type T, allocated on the heap. Cloining it will produce a new Gc instance which pints to the same allocation as the original Gc.

Unlike std::rc::Rc, Gc pointers may refer to each other in a way that creates cycles arbitrarily without causing leaks, provided that the program calls collect to collect those cycles.

It’s important to note a few things about collection:

• The default collect implementation only performs cycle-tracing collection if a node has been in waiting for collection for a while. This is so that we don’t pay the cost of tracing for acyclic nodes which may be marked for collection due to the number of outstanding references, but don’t actually participate in a cycle. You may use collect_full to force tracing collection of all pending nodes if you prefer.
• Dropping of data is deferred until a call to collect or collect_full is made, and the collector is able to determine that the Gc is actually dead. The collector guarantees that (in the absence of bugs) the Drop implementation for your type will be executed if it is determined to be dead, but cannot provide any guarantees on when it will be executed.
  • collect has weak guarantees even in the presence of acyclic pointers - if a node containing your type is acyclic, but has N strong references, it may take up to min(N, [CollectionOptions::old_gen_threshold] + 1) calls to collect for the value to be cleaned up even if all parents are dropped.
  • The collector does guarantee that if collect_full is used, the Drop implementation for your data will have been executed by the time collect_full completes if the value is dead.
• The collector does not make any guarantees about the relative order of drops for dead nodes. Even if the order appears stable, you may not rely on it for program correctness.

Implementations

impl<T> Gc<T> where
    T: Traceable + 'static, 

pub fn new(data: T) -> Self

Construct a new Gc containing data which will be automatically cleaned up with it is no longer reachable, even in the presence of cyclical references.

impl<T> Gc<T> where
    T: Traceable + 'static, 

pub fn strong_count(this: &Gc<T>) -> usize

Retrieve the current number of strong references outstanding.

pub fn is_live(this: &Gc<T>) -> bool

Returns true if the data in Self hasn’t been dropped yet. This will almost always be the case unless it is called inside of a Drop implementation or if there is a bug present in a Traceable impl.

pub fn get(this: &Gc<T>) -> Option<&T>

Get a reference into this Gc.

Returns None if the pointer is dead, as the data contained in this pointer is possibly cleaned up.

pub fn get_mut(this: &mut Gc<T>) -> Option<&mut T>

Try to get a mutable referenced into this Gc. Will return None if there are oustanding strong references to this, or if the pointer is dead.

pub unsafe fn get_unchecked(this: &Gc<T>) -> &T

Gets a reference into this Gc without checking if pointer is still alive.

Safety

This gc pointer must not have had its inner data dropped yet

pub unsafe fn get_mut_unchecked(this: &mut Gc<T>) -> &mut T

Gets a reference into this Gc without checking if pointer is still alive or has unique access

Safety

• This gc pointer must not have had its inner data dropped yet.
• There must be no other aliasing references to the inner data.

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

Returns true if both this & other point to the same allocation.

Trait Implementations

impl<T> AsRef<T> for Gc<T> where
    T: Traceable + 'static, 

fn as_ref(&self) -> &T

Performs the conversion.

impl<T> Clone for Gc<T> where
    T: Traceable + 'static, 

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug + Traceable + 'static> Debug for Gc<T>

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

Formats the value using the given formatter.

impl<T> Deref for Gc<T> where
    T: Traceable + 'static, 

type Target = T

The resulting type after dereferencing.

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

Dereferences the value.

impl<T: Traceable + 'static> Drop for Gc<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Traceable + 'static> Ord for Gc<T> where
    T: Ord, 

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<T: Traceable + 'static> PartialEq<Gc<T>> for Gc<T> where
    T: PartialEq, 

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<T: Traceable + 'static> PartialOrd<Gc<T>> for Gc<T> where
    T: PartialOrd, 

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<T> Traceable for Gc<T> where
    T: Traceable + 'static, 

fn visit_children(&self, visitor: &mut GcVisitor<'_>)

Visit the gc pointers owned by this type.

impl<T: Traceable + 'static> Eq for Gc<T> where
    T: Eq,