Struct mjb_gc::Gc

pub struct Gc<T: Trace> { /* fields omitted */ }

A pointer type over a value that provides shared ownership and immediate cycle collection upon Drop.

Implementations

impl<T: Trace> Gc<T>

pub fn new(value: T) -> Self

Creates a new Gc<T> with the given value.

Examples

use mjb_gc::Gc;

// Why would we ever want to GC an integer?
let five = Gc::new(5);

pub fn new_cyclic<F>(data_fn: F) -> Self where
    F: FnOnce(Self) -> T, 

Construct a new Gc<T> value using a reference to itself. Attempting to dereference the reference before this function returns will panic.

Examples

use mjb_gc::{Gc, Trace};

#[derive(Trace)]
struct Gadget {
    self_gc: Gc<Gadget>,
    // ...
}

impl Gadget {
    fn new() -> Gc<Self> {
        Gc::new_cyclic(|self_gc| Gadget {
            self_gc,
            // ...
        })
    }
}

use mjb_gc::Gc;

let _ = Gc::new_cyclic(|a| {
    let _ = &*a; // Dereference the Gc, and thus panic.
});

pub fn pin(value: T) -> Pin<Self>

Creates a pinned Gc<T> with the given value.

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

Whether two Gcs point to the same allocation.

pub fn as_ptr(&self) -> *const T

pub fn as_mut_ptr(&mut self) -> *mut T

pub fn try_unwrap(this: Self) -> Result<T, Self>

Unwraps the Gc<T> if this is the only reference.

Otherwise, an Err is returned with the same Gc that was passed in.

Examples

use mjb_gc::Gc;

let x = Gc::new(3);
assert_eq!(Gc::try_unwrap(x), Ok(3));

let x = Gc::new(4);
let _y = Gc::clone(&x);
assert_eq!(*Gc::try_unwrap(x).unwrap_err(), 4);

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

Gets the amount of references to this Gc<T>.

Note that this includes both external and internal references.

pub fn is_unique(this: &Self) -> bool

Whether this reference is the only reference to the value.

If the value is self-referential, those references will cause this never to be true.

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

Get a mutable reference into the Gc if there are no other references to the allocation.

Returns None otherwise, since mutability xor aliasing.

See also make_mut, which clones the inner value instead of returning None.

Panics

If the value has already been dropped, this function will panic.

Examples

use mjb_gc::Gc;

let mut x = Gc::new(3);
*Gc::get_mut(&mut x).unwrap() = 4;
assert_eq!(*x, 4);

let _y = Gc::clone(&x);
assert!(Gc::get_mut(&mut x).is_none());

pub unsafe fn get_unchecked_mut(this: &mut Self) -> &mut T

Get the value as mutable, bypassing any safety checks.

Safety

There needs to be no other references in use while this one is in use.

impl<T: Trace + Clone> Gc<T>

pub fn make_mut(this: &mut Self) -> &mut T

Make a mutable reference into the given Gc.

If there are more references to the value, it will be cloned.

Panics

If the value has already been dropped, this function will panic.

Trait Implementations

impl<T: Trace> Clone for Gc<T>

fn clone(&self) -> Self

Creates a new Gc pointer to the same allocation.

This doesn’t clone the inner data.

This call will panic if the reference count would overflow.

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

Performs copy-assignment from source.

impl<T: Trace + Debug> Debug for Gc<T>

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

Formats the value using the given formatter.

impl<T: Trace> Deref for Gc<T>

fn deref(&self) -> &T

Dereference a Gc<T> into T.

If the value has already been dropped, this function will panic.

Examples

use mjb_gc::{Gc, Trace};

#[derive(Trace)]
struct Cyclic(Gc<Cyclic>);

impl Drop for Cyclic {
    fn drop(&mut self) {
        let _a = &*self.0; // Dereference the Gc and panic.
    }
}

let a = Gc::new_cyclic(|v| Cyclic(v));

type Target = T

The resulting type after dereferencing.

impl<T: Trace + Display> Display for Gc<T>

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

Formats the value using the given formatter.

impl<T: Trace> Drop for Gc<T>

fn drop(&mut self)

Drops the Gc.

This will decrement the reference count. If there are no external references, this will drop the contained value.

Examples

use mjb_gc::{Gc, Trace};

#[derive(Trace)]
struct Cyclic(Gc<Cyclic>);

impl Drop for Cyclic {
    fn drop(&mut self) {
        println!("dropped!");
    }
}

let foo = Gc::new_cyclic(|g| Cyclic(g));
let foo2 = Gc::clone(&foo);

drop(foo); // Doesn't print anything
drop(foo2); // Prints "dropped!"

impl<T: Trace + PartialEq> PartialEq<Gc<T>> 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 !=.

impl<T: Trace> Trace for Gc<T>

unsafe fn untrace(&self)

Resets the Gc for another trace cycle.

unsafe fn trace(&self)

Runs a trace cycle on the Gc.

unsafe fn set_undone(&self)

Sets the done flags to false.

fn counts_match(&self) -> bool

Checks whether the reference counts match.

fn could_contain_cycles() -> bool

Whether the type could contain cycles.

impl<T: Trace + Eq> Eq for Gc<T>

impl<T: Trace> Unpin for Gc<T>