Struct safe_gc::Gc

pub struct Gc<T> { /* private fields */ }

A reference to a garbage-collected T.

Gc<T> should be used when:

• Referencing other GC-managed objects from within a GC-managed object’s type definition.

• Traversing or mutating GC-managed objects when you know a garbage collection cannot happen.

A Gc<T> does not root the referenced T or keep it alive across garbage collections. (The Root<T> type does that.) Therefore, Gc<T> should not be used to hold onto GC references across any operation that could trigger a garbage collection.

Example: Referencing Other GC-Managed Objects Within a GC-Managed Object

use safe_gc::{Collector, Gc, Trace};

struct Tree<T: Trace> {
    // A non-nullable reference to a GC-managed `T`.
    value: Gc<T>,

    // Nullable references to parent, left, and right tree nodes.
    parent: Option<Gc<Tree<T>>>,
    left: Option<Gc<Tree<T>>>,
    right: Option<Gc<Tree<T>>>,
}

impl<T: Trace> Trace for Tree<T> {
    fn trace(&self, collector: &mut Collector) {
        // Report each of the `Gc<T>`s referenced from within `self` to the
        // collector. See the `Trace` docs for more details.
        collector.edge(self.value);
        if let Some(parent) = self.parent {
            collector.edge(parent);
        }
        if let Some(left) = self.left {
            collector.edge(left);
        }
        if let Some(right) = self.right {
            collector.edge(right);
        }
    }
}

Example: Accessing a Gc<T>’s referenced T

use safe_gc::{Gc, Heap, Trace};

struct Node {
    value: u32,
    tail: Option<Gc<Node>>,
}

impl Trace for Node {
    // ...
}

let mut heap = Heap::new();

let a = heap.alloc(Node { value: 36, tail: None });
let b = heap.alloc(Node { value: 42, tail: Some(a.into()) });
let c = heap.alloc(Node { value: 99, tail: Some(b.clone().into()) });

// Read `(*c).tail`.
let c_tail = heap[&c].tail;
assert_eq!(c_tail, Some(b.into()));

// Write `(*c).tail = None`.
heap[&c].tail = None;

Example: Downgrading a Root<T> into a Gc<T>

The Heap::alloc method returns rooted references, but to store those references into the field of a GC-managed object, you’ll need to unroot the reference with Root<T>::unrooted. (You can also use root.into() or Gc::from(root).)

use safe_gc::{Gc, Heap, Root, Trace};

struct Cat {
    siblings: Vec<Gc<Cat>>,
}

impl Trace for Cat {
    // ...
}

let mut heap = Heap::new();

let momo: Root<Cat> = heap.alloc(Cat { siblings: vec![] });
let juno: Root<Cat> = heap.alloc(Cat { siblings: vec![] });

// Add `momo` and `juno` to each other's siblings vectors. This requires
// downgrading the `Root<Cat>`s to `Gc<Cat>`s via the `unrooted` method.
heap[&momo].siblings.push(juno.unrooted());
heap[&juno].siblings.push(momo.unrooted());

Example: Upgrading a Gc<T> into a Root<T>

You can upgrade a Gc<T> into a Root<T> via the Heap::root method, so that you can hold references to GC-objects across operations that can potentially trigger garbage collections.

See the docs for Heap::root for more details and an example.

Implementations

impl<T> Gc<T>

pub fn from_raw_parts(heap_id: u32, index: u32) -> Self

Create a new Gc<T> from a raw heap ID and index.

pub fn into_raw_parts(self) -> (u32, u32)

Get the raw heap ID and index from a Gc<T>.

Trait Implementations

impl<T> Clone for Gc<T>

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 for Gc<T>

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

Formats the value using the given formatter.

impl<'a, T> From<&'a Root<T>> for Gc<T>

where T: Trace,

fn from(root: &'a Root<T>) -> Self

Converts to this type from the input type.

impl<T> From<Root<T>> for Gc<T>

where T: Trace,

fn from(root: Root<T>) -> Self

Converts to this type from the input type.

impl<T> Hash for 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<T> Index<Gc<T>> for Heap

where T: Trace,

type Output = T

The returned type after indexing.

fn index(&self, index: Gc<T>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T> IndexMut<Gc<T>> for Heap

where T: Trace,

fn index_mut(&mut self, gc: Gc<T>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<T> PartialEq<Gc<T>> for Root<T>

where T: Trace,

fn eq(&self, other: &Gc<T>) -> 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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq<Root<T>> for Gc<T>

where T: Trace,

fn eq(&self, other: &Root<T>) -> 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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq for 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: &Rhs) -> bool

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

impl<T> Copy for Gc<T>

impl<T> Eq for Gc<T>