Struct Gc

pub struct Gc<T: Trace + 'static> { /* private fields */ }

A cycle-collected reference-counted smart pointer.

Gc<T> provides shared ownership of a value of type T, allocated on the heap. Cloning it will produce a new Gc instance which points to the same allocation as the original Gc.

Gc provides RefCell like behavior for its data so there is no need to wrap inner data in a Cell or RefCell type in order to achieve interior mutability. You may use Gc::borrow and Gc::borrow_mut

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, CollectOptions::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: Trace + '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: Trace + 'static,

pub fn strong_count(this: &Self) -> usize

Retrieve the current number of strong references outstanding.

pub fn is_live(this: &Self) -> 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 Trace impl.

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

Get a reference into this Gc.

The borrow of the data ends until the returned Ref exists the scope. Multiple immutable borrows may be taken out at the same time.

Panics

Panics if the value is currently mutably borrowed.

pub fn try_borrow(&self) -> Option<Ref<'_, T>>

Try to get a reference into this Gc.

Returns None if the pointer is dead or immutably borrowed, as the data contained in this pointer is possibly cleaned up or cannot be aliased.

pub fn borrow_mut(&self) -> RefMut<'_, T>

Get a mutable reference into this Gc.

Similar to RefCell, the mutable borrow of the data lasts until the returned RefMut or all RefMuts derived from it exit scope.

Panics

Panics if the value is currently borrowed.

pub fn try_borrow_mut(&self) -> Option<RefMut<'_, T>>

Try to get a mutable referenced into this Gc.

Will return None if there are oustanding borrows, or if the pointer is dead.

pub fn ptr_eq(this: &Self, other: &Self) -> bool

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

Trait Implementations

impl<T> Clone for Gc<T>

where T: Trace + 'static,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Gc<T>

where T: Trace + 'static,

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

Formats the value using the given formatter.

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

fn drop(&mut self)

Executes the destructor for this type.

impl<T> Ord for Gc<T>

where T: Ord + Trace + 'static,

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,

Restrict a value to a certain interval.

impl<T> PartialEq for Gc<T>

where T: PartialEq + Trace + 'static,

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl<T> PartialOrd for Gc<T>

where T: PartialOrd + Trace + 'static,

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl<T> Trace for Gc<T>

where T: Trace + 'static,

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

It is recommended that you simply call visit_children(visitor) on each value owned by the implementor which may participate in a reference cycle. The default implementation for Gc will appropriately notify the collector when it is visited.

impl<T> Eq for Gc<T>

where T: Eq + Trace + 'static,