Struct safe_gc::Root

pub struct Root<T>
where
    T: Trace,
{ /* private fields */ }

A rooted reference to a GC-managed T.

Root<T>s prevent their referenced T from being reclaimed during garbage collections. This makes them suitable for holding references to GC-managed objects across operations that can trigger GCs.

Root<T>s are not suitable for referencing other GC-manged objects within the definition of a GC-managed object. Doing this will effectively leak everything transitively referenced from the Root<T>. Instead, use Gc<T> for references to other GC-managed objects from within a GC-managed object.

See also the docs for Gc<T> for more examples of converting between Root<T> and Gc<T> and when you want to use which type.

Example: Creating a Root<T> via Allocation

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

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

impl Trace for Node {
    // ...
}

let mut heap = Heap::new();

// Allocating a new GC object in a heap returns a `Root<T>` reference.
let node: Root<Node> = heap.alloc(Node { value: 1234, tail: None });

Implementations

impl<T> Root<T>

where T: Trace,

pub fn unrooted(&self) -> Gc<T>

Get an unrooted Gc<T> reference pointing to the same T that this Root<T> points to.

See also the docs for Gc<T> for more examples of converting between Root<T> and Gc<T> and when you want to use which type.

Trait Implementations

impl<T> Clone for Root<T>

where T: Trace,

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Drop for Root<T>

where T: Trace,

fn drop(&mut self)

Executes the destructor for this type.

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<'a, T> Index<&'a Root<T>> for Heap

where T: Trace,

type Output = T

The returned type after indexing.

fn index(&self, root: &'a Root<T>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T> Index<Root<T>> for Heap

where T: Trace,

type Output = T

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<'a, T> IndexMut<&'a Root<T>> for Heap

where T: Trace,

fn index_mut(&mut self, root: &'a Root<T>) -> &mut Self::Output

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

impl<T> IndexMut<Root<T>> for Heap

where T: Trace,

fn index_mut(&mut self, root: Root<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 Root<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.